X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fintro.sdf;h=1c8f7d281f9bb3aa3910878e1d0f41a2201bf5dc;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=9517af25ce801bbdedd651111c29268b223449f3;hpb=e45efa877e6ea8c9e37de265d67596f2a1e70f4c;p=openldap diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf index 9517af25ce..1c8f7d281f 100644 --- a/doc/guide/admin/intro.sdf +++ b/doc/guide/admin/intro.sdf @@ -1,266 +1,309 @@ # $OpenLDAP$ -# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# Copyright 1999-2003, The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Introduction to slapd and slurpd - -This document describes how to build, configure, and run the stand-alone -{{TERM:LDAP}} daemon, {{slapd}}(8) and the stand-alone LDAP update replication -daemon, {{slurpd}}(8). It is intended for newcomers and experienced -administrators alike. This section provides a basic introduction to -directory services and, in particular, the directory services provided -by {{slapd}}(8). +H1: Introduction to OpenLDAP Directory Services +This document describes how to build, configure, and operate OpenLDAP +software to provide directory services. This includes details on +how to configure and run the stand-alone {{TERM:LDAP}} daemon, +{{slapd}}(8) and the stand-alone LDAP update replication daemon, +{{slurpd}}(8). It is intended for newcomers and experienced +administrators alike. This section provides a basic introduction +to directory services and, in particular, the directory services +provided by {{slapd}}(8). H2: What is a directory service? -A directory is specialized database optimized for reading, browsing and -searching. Directories tend to contain descriptive, attribute-based -information and support sophisticated filtering capabilities. Directories -are generally do not support complicated transaction or roll-back schemes -found in database management systems designed for handling high-volume -complex updates. Directory updates are typically simple all-or-nothing -changes, if they are allowed at all. Directories are tuned to give -quick-response to high-volume lookup or search operations. They may have -the ability to replicate information widely in order to increase -availability and reliability, while reducing response time. When -directory information is replicated, temporary inconsistencies between -the replicas may be OK, as long as they get in sync eventually. - -There are many different ways to provide a directory service. Different -methods allow different kinds of information to be stored in the directory, -place different requirements on how that information can be referenced, -queried and updated, how it is protected from unauthorized access, etc. -Some directory services are {{local}}, providing service to a restricted -context (e.g., the finger service on a single machine). Other services are -global, providing service to a much broader context (e.g., the entire Internet). -Global services are usually {{distributed}}, meaning that the data they -contain is spread across many machines, all of which cooperate to provide -the directory service. Typically a global service defines a uniform -{{namespace}} which gives the same view of the data no matter where -you are in relation to the data itself. The Internet {{TERM[expand]DNS}} -is an example of a globally distributed directory service. - +A directory is a specialized database optimized for reading, browsing +and searching. Directories tend to contain descriptive, attribute-based +information and support sophisticated filtering capabilities. +Directories generally do not support complicated transaction or +roll-back schemes found in database management systems designed +for handling high-volume complex updates. Directory updates are +typically simple all-or-nothing changes, if they are allowed at +all. Directories are tuned to give quick response to high-volume +lookup or search operations. They may have the ability to replicate +information widely in order to increase availability and reliability, +while reducing response time. When directory information is +replicated, temporary inconsistencies between the replicas may be +okay, as long as they get in sync eventually. + +There are many different ways to provide a directory service. +Different methods allow different kinds of information to be stored +in the directory, place different requirements on how that information +can be referenced, queried and updated, how it is protected from +unauthorized access, etc. Some directory services are {{local}}, +providing service to a restricted context (e.g., the finger service +on a single machine). Other services are global, providing service +to a much broader context (e.g., the entire Internet). Global +services are usually {{distributed}}, meaning that the data they +contain is spread across many machines, all of which cooperate to +provide the directory service. Typically a global service defines +a uniform {{namespace}} which gives the same view of the data no +matter where you are in relation to the data itself. The Internet +{{TERM[expand]DNS}} (DNS) is an example of a globally distributed +directory service. H2: What is LDAP? -{{slapd}}'s model for directory service is based on a global directory -model called {{TERM:LDAP}}. LDAP stands for {{TERM[expand]LDAP}}. -LDAP is a directory access protocol that runs over -{{TERM:TCP}}/{{TERM:IP}}. The nitty-gritty details of LDAP are defined in -{{REF:RFC2251}} "The Lightweight Directory Access Protocol (v3)." -This section gives an overview of LDAP from a user's perspective. - -{{What kind of information can be stored in the directory?}} -The LDAP information model is based on {{entries}}. An entry is a -collection of attributes that has a globally-unique -{{TERM[expand]DN}} (DN). -The DN is used to refer to the entry unambiguously. Each of the -entry's attributes has a {{type}} and one or more {{values}}. -The types are typically mnemonic strings, like "{{EX:cn}}" for common -name, or "{{EX:mail}}" for email address. The syntax of values depend -on the attribute type is. For example, {{EX:cn}} attribute might -be the value {{EX: Babs Jensen}}. A {{EX:mail}} attribute might -contain the value "{{EX:babs@openldap.org}}". A {{EX:jpegPhoto}} -attribute would contain a photograph in the JPEG (binary) format. - -{{How is the information arranged?}} -In LDAP, directory entries are arranged in a hierarchical tree-like -structure. Traditionally, this structure reflected the geographic -and/or organizational boundaries. Entries representing countries -appeared at the top of the tree. Below them are entries representing -states and national organizations. Below them might be entries -representing organizational units, people, printers, documents, -or just about anything else you can think of. Figure 1.1 shows an -example LDAP directory tree using traditional naming. +{{TERM:LDAP}} stands for {{TERM[expand]LDAP}}. As the name suggests, +it is a lightweight protocol for accessing directory services, +specifically {{TERM:X.500}}-based directory services. LDAP runs +over {{TERM:TCP}}/{{TERM:IP}} or other connection oriented transfer +services. The nitty-gritty details of LDAP are defined in +{{REF:RFC2251}} "The Lightweight Directory Access Protocol (v3)" +and other documents comprising the technical specification +{{REF:RFC3377}}. This section gives an overview of LDAP from a +user's perspective. + +{{What kind of information can be stored in the directory?}} The +LDAP information model is based on {{entries}}. An entry is a +collection of attributes that has a globally-unique {{TERM[expand]DN}} +(DN). The DN is used to refer to the entry unambiguously. Each of +the entry's attributes has a {{type}} and one or more {{values}}. +The types are typically mnemonic strings, like "{{EX:cn}}" for +common name, or "{{EX:mail}}" for email address. The syntax of +values depend on the attribute type. For example, a {{EX:cn}} +attribute might contain the value {{EX:Babs Jensen}}. A {{EX:mail}} +attribute might contain the value "{{EX:babs@example.com}}". A +{{EX:jpegPhoto}} attribute would contain a photograph in the JPEG +(binary) format. + +{{How is the information arranged?}} In LDAP, directory entries +are arranged in a hierarchical tree-like structure. Traditionally, +this structure reflected the geographic and/or organizational +boundaries. Entries representing countries appear at the top of +the tree. Below them are entries representing states and national +organizations. Below them might be entries representing organizational +units, people, printers, documents, or just about anything else +you can think of. Figure 1.1 shows an example LDAP directory tree +using traditional naming. !import "intro_tree.gif"; align="center"; \ title="LDAP directory tree (traditional naming)" FT[align="Center"] Figure 1.1: LDAP directory tree (traditional naming) The tree may also be arranged based upon Internet domain names. -Figure 1.2 shows an example using this increasing popular naming approach. +This naming approach is becoming increasing popular as it allows +for directory services to be located using the {{DNS}}. +Figure 1.2 shows an example LDAP directory tree using domain-based +naming. !import "intro_dctree.gif"; align="center"; \ title="LDAP directory tree (Internet naming)" FT[align="Center"] Figure 1.2: LDAP directory tree (Internet naming) In addition, LDAP allows you to control which attributes are required -and allowed in an entry through the use of a special attribute called -{{objectClass}}. The values of the {{objectClass}} attribute -determine the {{schema}} rules the entry must obey. - -{{How is the information referenced?}} -An entry is referenced by its distinguished name, which is constructed -by taking the name of the entry itself (called the {{TERM[expand]RDN}} -or RDN) and concatenating the names of its ancestor entries. For -example, the entry for Barbara Jensen in the Internet naming example -above has an RDN of {{EX:uid=babs}} and a DN of -{{EX:uid=babs, ou=People, dc=OpenLDAP, dc=com}}". The full DN format is -described in {{REF:RFC2253}}, "Lightweight Directory Access Protocol (v3): -UTF-8 String Representation of Distinguished Names." - -{{How is the information accessed?}} -LDAP defines operations for interrogating and updating the directory. -Operations are provided for adding and deleting -an entry from the directory, changing an existing entry, and changing the -name of an entry. Most of the time, though, LDAP is used to search for -information in the directory. The LDAP search operation allows some portion -of the directory to be searched for entries that match some criteria specified -by a search filter. Information can be requested from each entry that matches -the criteria. - -For example, you might want to search the entire directory subtree at -and below {{EX:dc=OpenLDAP,dc=org}} for people with the name {{EX:Barbara -Jensen}}, retrieving the email address of each entry found. LDAP lets -you do this easily. Or you might want to search the entries directly -below the {{EX:st=California, c=US}} entry for organizations with the -string {{EX:Acme}} in their name, and that have a fax number. LDAP lets -you do this too. The next section describes in more detail what you can -do with LDAP and how it might be useful to you. - -{{How is the information protected from unauthorized access?}} -Some directory services provide no protection, allowing anyone to see -the information. LDAP provides a method for a client to authenticate, -or prove its identity to a directory server, paving the way for rich -access control to protect the information the server contains. +and allowed in an entry through the use of a special attribute +called {{EX:objectClass}}. The values of the {{EX:objectClass}} +attribute determine the {{schema}} rules the entry must obey. + +{{How is the information referenced?}} An entry is referenced by +its distinguished name, which is constructed by taking the name of +the entry itself (called the {{TERM[expand]RDN}} or RDN) and +concatenating the names of its ancestor entries. For example, the +entry for Barbara Jensen in the Internet naming example above has +an RDN of {{EX:uid=babs}} and a DN of +{{EX:uid=babs,ou=People,dc=example,dc=com}}. The full DN format +is described in {{REF:RFC2253}}, "Lightweight Directory Access +Protocol (v3): UTF-8 String Representation of Distinguished Names." + +{{How is the information accessed?}} LDAP defines operations for +interrogating and updating the directory. Operations are provided +for adding and deleting an entry from the directory, changing an +existing entry, and changing the name of an entry. Most of the +time, though, LDAP is used to search for information in the directory. +The LDAP search operation allows some portion of the directory to +be searched for entries that match some criteria specified by a +search filter. Information can be requested from each entry that +matches the criteria. + +For example, you might want to search the entire directory subtree +at and below {{EX:dc=example,dc=com}} for people with the name +{{EX:Barbara Jensen}}, retrieving the email address of each entry +found. LDAP lets you do this easily. Or you might want to search +the entries directly below the {{EX:st=California,c=US}} entry for +organizations with the string {{EX:Acme}} in their name, and that +have a fax number. LDAP lets you do this too. The next section +describes in more detail what you can do with LDAP and how it might +be useful to you. + +{{How is the information protected from unauthorized access?}} Some +directory services provide no protection, allowing anyone to see +the information. LDAP provides a mechanism for a client to +authenticate, or prove its identity to a directory server, paving +the way for rich access control to protect the information the +server contains. LDAP also supports privacy and integrity security +services. H2: How does LDAP work? -LDAP directory service is based on a {{client-server}} model. One or more -LDAP servers contain the data making up the LDAP directory tree. An LDAP -client connects to an LDAP server and asks it a question. The server -responds with the answer and/or with a pointer to where the client can -get additional information (typically, another LDAP server). No matter -which LDAP server a client connects to, it sees the same view of the -directory; a name presented to one LDAP server references the same -entry it would at another LDAP server. This is an important feature of -a global directory service, like LDAP. +LDAP directory service is based on a {{client-server}} model. One +or more LDAP servers contain the data making up the directory +information tree (DIT). The client connects to servers and +asks it a question. The server responds with an answer and/or +with a pointer to where the client can get additional information +(typically, another LDAP server). No matter which LDAP server a +client connects to, it sees the same view of the directory; a name +presented to one LDAP server references the same entry it would at +another LDAP server. This is an important feature of a global +directory service, like LDAP. + + +H2: What about X.500? + +Technically, {{TERM:LDAP}} is a directory access protocol to an +{{TERM:X.500}} directory service, the {{TERM:OSI}} directory service. +Initially, LDAP clients accessed gateways to the X.500 directory service. +This gateway ran LDAP between the client and gateway and X.500's +{{TERM[expand]DAP}} ({{TERM:DAP}}) between the gateway and the +X.500 server. DAP is a heavyweight protocol that operates over a +full OSI protocol stack and requires a significant amount of +computing resources. LDAP is designed to operate over +{{TERM:TCP}}/{{TERM:IP}} and provides most of the functionality of +DAP at a much lower cost. + +While LDAP is still used to access X.500 directory service via +gateways, LDAP is now more commonly directly implemented in X.500 +servers. + +The stand-alone LDAP daemon, or {{slapd}}(8), can be viewed as a +{{lightweight}} X.500 directory server. That is, it does not +implement the X.500's DAP. As a {{lightweight directory}} server, +{{slapd}}(8) implements only a subset of the X.500 models. + +If you are already running a X.500 DAP service and you want to +continue to do so, you can probably stop reading this guide. This +guide is all about running LDAP via {{slapd}}(8), without running +X.500 DAP. If you are not running X.500 DAP, want to stop running +X.500 DAP, or have no immediate plans to run X.500 DAP, read on. + +It is possible to replicate data from an LDAP directory server to +a X.500 DAP {{TERM:DSA}}. This requires an LDAP/DAP gateway. +OpenLDAP does not provide such a gateway, but our replication daemon +can be used to replicate to such a gateway. See the {{SECT:Replication +with slurpd}} chapter of this document for information regarding +replication. + + +H2: What is the difference between LDAPv2 and LDAPv3? + +LDAPv3 was developed in the late 1990's to replace LDAPv2. +LDAPv3 adds the following features to LDAP: + + - Strong Authentication via {{TERM:SASL}} + - Integrity and Confidentiality Protection via {{TERM:TLS}} (SSL) + - Internationalization through the use of Unicode + - Referrals and Continuations + - Schema Discovery + - Extensibility (controls, extended operations, and more) + +LDAPv2 is historic ({{REF:RFC3494}}). As most implementations +(including {{slapd}}(8)) of LDAPv2 do not conform to the LDAPv2 +technical specification, interoperatibility amongst implementations +claiming LDAPv2 support will be limited. As LDAPv2 differs +significantly from LDAPv3, deploying both LDAPv2 and LDAPv3 +simultaneously can be quite problematic. LDAPv2 should be avoided. +LDAPv2 is disabled by default. H2: What is slapd and what can it do? -{{slapd}} is an LDAP directory server that runs on many different -platforms. You can use it to provide a directory service of your very own. -Your directory can contain pretty much anything you want to put in it. You -can connect it to the global LDAP directory service, or run a service all by -yourself. Some of slapd's more interesting features and capabilities include: - -{{B:LDAPv2}} and {{B:LDAPv3}}: {{slapd}} supports both version 2 and 3 -of the {{TERM[expand]LDAP}}. {{slapd}} provides support -for the latest features while maintaining interoperability with existing -clients. {{slapd}} supports both IPv4 and IPv6 protocols. - -{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports -strong authentication services through the use of SASL. {{slapd}}'s -SASL implementation utilizes {{PRD:Cyrus}} software which supports -a number of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI. - -{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and -integrity protections through the use of TLS (or SSL). {{slapd}}'s -TLS implementation utilizes {{PRD:OpenSSL}} software. - -{{B:Access control}}: {{slapd}} provides a rich and powerful access -control facility, allowing you to control access to the information -in your database(s). You can control access to entries based on +{{slapd}}(8) is an LDAP directory server that runs on many different +platforms. You can use it to provide a directory service of your +very own. Your directory can contain pretty much anything you want +to put in it. You can connect it to the global LDAP directory +service, or run a service all by yourself. Some of slapd's more +interesting features and capabilities include: + +{{B:LDAPv3}}: {{slapd}} implements version 3 of {{TERM[expand]LDAP}}. +{{slapd}} supports LDAP over both IPv4 and IPv6. + +{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports strong authentication +services through the use of SASL. {{slapd}}'s SASL implementation +utilizes {{PRD:Cyrus}} {{PRD:SASL}} software which supports a number +of mechanisms including DIGEST-MD5, EXTERNAL, and GSSAPI. + +{{B:{{TERM[expand]TLS}}}}: {{slapd}} provides privacy and integrity +protections through the use of TLS (or SSL). {{slapd}}'s TLS +implementation utilizes {{PRD:OpenSSL}} software. + +{{B:Topology control}}: {{slapd}} allows one to restrict access to +the server based upon network topology. This feature utilizes +{{TCP wrappers}}. + +{{B:Access control}}: {{slapd}} provides a rich and powerful access +control facility, allowing you to control access to the information +in your database(s). You can control access to entries based on LDAP authorization information, {{TERM:IP}} address, domain name -and other criteria. -{{slapd}} supports both {{static}} and {{dynamic}} access control -information. +and other criteria. {{slapd}} supports both {{static}} and +{{dynamic}} access control information. {{B:Internationalization}}: {{slapd}} supports Unicode and language tags. -{{B:Choice of databases}}: {{slapd}} comes with a variety of different -backend databases you can choose from. They include -{{TERM:LDBM}}, a high-performance disk-based {{embedded}} database; -SHELL, a database interface to arbitrary shell scripts; and -PASSWD, a simple password file database. LDBM utilizes either -{{PRD:BerkeleyDB}} or {{PRD:GDBM}}. - -{{B:Multiple database instances}}: {{slapd}} can be configured to serve -multiple databases at the same time. This means that a single {{slapd}} -server can respond to requests for many logically different portions -of the LDAP tree, using the same or different backend databases. +{{B:Choice of database backends}}: {{slapd}} comes with a variety +of different database backends you can choose from. They include +{{TERM:BDB}}, a high-performance transactional database backend; +{{TERM:LDBM}}, a lightweight DBM based backend; {{SHELL}}, a backend +interface to arbitrary shell scripts; and PASSWD, a simple backend +interface to the {{passwd}}(5) file. BDB utilizes {{ORG:Sleepycat}} +{{PRD:Berkeley DB}}. LDBM utilizes either {{PRD:Berkeley DB}} or +{{PRD:GDBM}}. + +{{B:Multiple database instances}}: {{slapd}} can be configured to +serve multiple databases at the same time. This means that a single +{{slapd}} server can respond to requests for many logically different +portions of the LDAP tree, using the same or different database +backends. {{B:Generic modules API}}: If you require even more customization, -{{slapd}} lets you write your own modules easily. {{slapd}} -consists of two distinct parts: a front end that handles protocol -communication with LDAP clients; and modules which handles specific -tasks such as database operations. Because these two pieces communicate -via a well-defined C API, you can write your own customized modules -which extend {{slapd}} in numerous ways. Also, a number of -{{programmable database}} modules are provided. These allowing you -to expose external data sources to {{slapd}} using popular programming -languages ({{PRD:Perl}}, {{Shell}}, {{PRD:SQL}}, and {{PRD:TCL}}. - -{{B:Threads}}: {{slapd}} is threaded for high performance. A -single multi-threaded {{slapd}} process handles all incoming -requests, reducing the amount of system overhead required. - -{{B:Replication}}: {{slapd}} can be configured to maintain replica +{{slapd}} lets you write your own modules easily. {{slapd}} consists +of two distinct parts: a front end that handles protocol communication +with LDAP clients; and modules which handle specific tasks such as +database operations. Because these two pieces communicate via a +well-defined {{TERM:C}} {{TERM:API}}, you can write your own +customized modules which extend {{slapd}} in numerous ways. Also, +a number of {{programmable database}} modules are provided. These +allow you to expose external data sources to {{slapd}} using popular +programming languages ({{PRD:Perl}}, {{shell}}, {{PRD:SQL}}, and +{{PRD:TCL}}). + +{{B:Threads}}: {{slapd}} is threaded for high performance. A single +multi-threaded {{slapd}} process handles all incoming requests +using a pool of threads. This reduces the amount of system overhead +required while providing high performance. + +{{B:Replication}}: {{slapd}} can be configured to maintain replica copies of its database. This {{single-master/multiple-slave}} replication scheme is vital in high-volume environments where a single {{slapd}} just doesn't provide the necessary availability -or reliability. {{slapd}} -also includes experimental support for {{multi-master}} replication. +or reliability. {{slapd}} also includes experimental support for +{{multi-master}} replication. -{{B:Configuration}}: {{slapd}} is highly configurable through a -single configuration file which allows you to change just about -everything you'd ever want to change. Configuration options have +{{B:Configuration}}: {{slapd}} is highly configurable through a +single configuration file which allows you to change just about +everything you'd ever want to change. Configuration options have reasonable defaults, making your job much easier. -{{slapd}} also has its limitations, of course. The main LDBM -database backend does not handle range queries or negation queries -very well. These features and more will be coming in a future release. - - - -H2: What about X.500? - -Technically, LDAP is a directory access protocol to an {{TERM:X.500}} -directory service, the {{TERM:OSI}} directory service. Initial -LDAP servers were were gateway between LDAP and the X.500 -{{TERM[expand]DAP}} ({{TERM:DAP}}). -DAP is a heavyweight protocol that runs over a full OSI protocol stack -and requires a significant amount of computing resources to run. -LDAP is designed to operate over {{TERM:TCP}}/{{TERM:IP}} and provides -most of the functionality of DAP at a much lower cost. - -This use of LDAP makes it easy to access the X.500 directory, but still -requires a full X.500 service to make data available to the many LDAP -clients being developed. As with full X.500 DAP clients, a full X.500 -DAP server is no small piece of software to run. - -The stand-alone LDAP daemon, or {{slapd}}(8), is meant to remove much -of the burden from the server side just as LDAP itself removed much of -the burden from clients. If you are already running an X.500 DAP service -and you want to continue to do so, you can probably stop reading this -guide, which is all about running LDAP via {{slapd}}, without running -X.500 DAP. If you are not running X.500 DAP, want to stop running -X.500 DAP, or have no immediate plans to run X.500 DAP, read on. - -It is possible to replicate data from a {{slapd}} directory -server to a X.500 {{TERM:DSA}}, which allows your organization to -make your data available as part of the global X.500 DAP directory -service on a "read-only" basis. This is discussed in section 11.6. - -Another way to make data in a {{slapd}} server available to the -X.500 community would be by using a X.500 DAP to LDAP gateway. At -this time, no such software has been written (to the best of our -knowledge), but hopefully some group will see fit to write such a -gateway. +{{slapd}} also has its limitations, of course. The main BDB +backend does not handle range queries or negation queries +very well. H2: What is slurpd and what can it do? -{{slurpd}}(8) is a daemon that helps {{slapd}} provide -replicated service. It is responsible for distributing changes made -to the master {{slapd}} database out to the various {{slapd}} -replicas. It frees {{slapd}} from having to worry that some -replicas might be down or unreachable when a change comes through; -{{slurpd}} handles retrying failed requests automatically. -{{slapd}} and {{slurpd}} communicate through a simple text -file that is used to log changes. +{{slurpd}}(8) is a daemon that helps {{slapd}} provide replicated +service. It is responsible for distributing changes made to the +master {{slapd}} database out to the various {{slapd}} replicas. +It frees {{slapd}} from having to worry that some replicas might +be down or unreachable when a change comes through; {{slurpd}} +handles retrying failed requests automatically. {{slapd}} and +{{slurpd}} communicate through a simple text file that is used to +log changes. + +See the {{SECT:Replication with slurpd}} chapter for information +about how to configure and run {{slurpd}}(8).