X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fintro.sdf;h=1c8f7d281f9bb3aa3910878e1d0f41a2201bf5dc;hb=14745b74d29fe80f2988908b3f3fa3a4532937d9;hp=6b8d47981c33a8f1e69ab981a657a2fa001c27c3;hpb=daf62ca04fb434fd3d14016e13336f2a9fa47289;p=openldap diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf index 6b8d47981c..1c8f7d281f 100644 --- a/doc/guide/admin/intro.sdf +++ b/doc/guide/admin/intro.sdf @@ -1,237 +1,309 @@ # $OpenLDAP$ -# Copyright 1999, 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 -LDAP daemon ({{I:slapd}}) and the stand-alone LDAP update replication -daemon ({{I:slurpd}}). It is intended for newcomers and experienced -administrators alike. This section provides a basic introduction to directory -service, and the directory service provided by {{I:slapd}} in particular. +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 like a database, but tends to contain more descriptive, -attribute-based information. The information in a directory is generally read -much more often than it is written. As a consequence, directories don't -usually implement the complicated transaction or roll-back schemes regular -databases use for doing 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 {{I: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 {{I: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 {{I:namespace}} -which gives the same view of the data no matter where you are in relation to -the data itself. - +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? -{{I:Slapd}}'s model for directory service is based on a global directory model -called LDAP, which stands for the Lightweight Directory Access Protocol. -LDAP is a directory service protocol that runs over TCP/IP. The nitty-gritty -details of LDAP are defined in RFC 1777 "The Lightweight Directory Access -Protocol." This section gives an overview of LDAP from a user's perspective. - -{{I:What kind of information can be stored in the directory?}} -The LDAP directory -service model is based on {{I:entries}}. An entry is a collection of -attributes that has a name, called a {{I:distinguished name}} (DN). -The DN is used to refer to the entry unambiguously. Each of the -entry's attributes has a {{I:type}} and one or -more {{I:values}}. -The types are typically mnemonic strings, like "{{EX:cn}}" for common -name, or "{{EX:mail}}" for email address. The values depend on what type of -attribute it is. For example, a {{EX:mail}} attribute might contain the value -"{{EX:babs@openldap.org}}". A {{EX:jpegPhoto}} attribute would contain -a photograph in binary JPEG/JFIF format. - -{{I:How is the information arranged?}} -In LDAP, directory entries are arranged in -a hierarchical tree-like structure that reflects political, geographic and/or -organizational boundaries. Entries representing countries appear at the top -of the tree. Below them are entries representing states or national -organizations. Below them might be entries representing people, -organizational units, printers, documents, or just about anything else you can -think of. Figure 1 shows an example LDAP directory tree, which should help -make things clear. - - -!import "intro_tree.gif"; align="center"; title="An example LDAP directory tree" -FT[align="Center"] Figure 1: An example LDAP directory tree. - - -In addition, LDAP allows you to control which attributes are required and -allowed in an entry through the use of a special attribute called -{{I:objectclass}}. -The values of the {{I:objectclass}} attribute determine -the {{I:schema}} rules the entry -must obey. - -{{I: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 relative distinguished name, or RDN) and concatenating the -names of its ancestor entries. For example, the entry for Barbara Jensen in -the example above has an RDN of "{{EX:cn=Barbara J Jensen}}" and a DN of -"{{EX:cn=Barbara J Jensen, o=OpenLDAP Project, c=US}}". The full DN format is -described in RFC 1779, "A String Representation of Distinguished Names." - -{{I: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 below the -OpenLDAP Project for people with the name 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 c=US entry for -organizations with the string "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. - -{{I: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. - +{{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. +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 {{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 {{I: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, or with a pointer to where the client can get more -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 is slapd and what can it do? - -{{I:Slapd}} is an LDAP directory server that runs on many different UNIX -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:Choice of databases}}: {{I:Slapd}} comes with three different backend -databases you can choose from. They are LDBM, a high-performance disk-based -database; SHELL, a database interface to arbitrary UNIX commands or shell -scripts; and PASSWD, a simple password file database. - -{{B:Multiple database instances}}: {{I:Slapd}} can be configured to serve -multiple databases at the same time. This means that a single {{I:slapd}} -server can respond to requests for many logically different portions -of the LDAP tree, using the same or different backend databases. - -{{B:Generic database API}}: If you require even more customization, {{I:slapd}} -lets you write your own backend database easily. {{I:Slapd}} -consists of two distinct parts: a front end that handles protocol -communication with LDAP clients; and a backend that handles database -operations. Because these two pieces communicate via a well-defined -C API, you can write your own customized database backend to {{I:slapd}}. - -{{B:Access control}}: {{I: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 authentication information, IP address, domain name and other criteria. - -{{B:Threads}}: {{I:Slapd}} is threaded for high performance. A -single multi-threaded {{I:slapd}} process handles all incoming -requests, reducing the amount of system overhead required. {{I:Slapd}} -will automatically select the best thread support for your platform. - -{{B:Replication}}: {{I:Slapd}} can be configured to maintain replica -copies of its database. This master/slave replication scheme is -vital in high-volume environments where a single {{I:slapd}} just -doesn't provide the necessary availability or reliability. - -{{B:Configuration}}: {{I: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. - -{{I:Slapd}} also has its limitations, of course. It does not -currently handle aliases, which are part of the LDAP model. 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. - +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? -LDAP was originally developed as a front end to X.500, the OSI directory -service. X.500 defines the Directory Access Protocol (DAP) for clients to -use when contacting directory servers. DAP is a heavyweight protocol that -runs over a full OSI stack and requires a significant amount of computing -resources to run. LDAP runs directly over TCP and provides most of the -functionality of DAP at a much lower cost. +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. -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 server is no -small piece of software to run. -The stand-alone LDAP daemon, or {{I:slapd}}, 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 service and you want to -continue to do so, you can probably stop reading this guide, which is all -about running LDAP via {{I:slapd}}, without running X.500. If you are not -running X.500, -want to stop running X.500, or have no immediate plans to run X.500, -read on. - -It is possible to replicate data from a {{I:slapd}} directory -server to an X.500 DSA, which allows your organization to make your -data available as part of the global X.500 directory service on a -"read-only" basis. This is discussed in section 11.6. +H2: What is slapd and what can it do? -Another way to make data in a {{I: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 towrite such a gateway. +{{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. + +{{B:Internationalization}}: {{slapd}} supports Unicode and language +tags. + +{{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 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. + +{{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 BDB +backend does not handle range queries or negation queries +very well. H2: What is slurpd and what can it do? -{{I:Slurpd}} is a UNIX daemon that helps {{I:slapd}} provide -replicated service. It is responsible for distributing changes made -to the master {{I:slapd}} database out to the various {{I:slapd}} -replicas. It frees {{I:slapd}} from having to worry that some -replicas might be down or unreachable when a change comes through; -{{I:slurpd}} handles retrying failed requests automatically. -{{I:Slapd}} and {{I:slurpd}} communicate through a simple text -file that is used to log changes. - -PB: - - +{{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).