From b527294153be3b79563c82c66102adc0004736c0 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 19:54:12 +0200 Subject: Adding upstream version 2.6.7+dfsg. Signed-off-by: Daniel Baumann --- doc/guide/admin/intro.sdf | 465 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 465 insertions(+) create mode 100644 doc/guide/admin/intro.sdf (limited to 'doc/guide/admin/intro.sdf') diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf new file mode 100644 index 0000000..8417c1e --- /dev/null +++ b/doc/guide/admin/intro.sdf @@ -0,0 +1,465 @@ +# $OpenLDAP$ +# Copyright 1999-2022 The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. +H1: Introduction to OpenLDAP Directory Services + +This document describes how to build, configure, and operate +{{PRD:OpenLDAP}} Software to provide directory services. This +includes details on how to configure and run the Standalone +{{TERM:LDAP}} Daemon, {{slapd}}(8). It is intended for new and +experienced administrators alike. This section provides a basic +introduction to directory services and, in particular, the directory +services provided by {{slapd}}(8). This introduction is only +intended to provide enough information so one might get started +learning about {{TERM:LDAP}}, {{TERM:X.500}}, and directory services. + + +H2: What is a directory service? + +A directory is a specialized database specifically designed for +searching and browsing, in additional to supporting basic lookup +and update functions. + +Note: A directory is defined by some as merely a database optimized +for read access. This definition, at best, is overly simplistic. + +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 generally +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 consumers may be okay, as long +as inconsistencies are resolved in a timely manner. + +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. + +A web directory, such as provided by the {{Curlie Project}} +<{{URL:https://curlie.org}}>, is a good example of a directory service. +These services catalog web pages and are specifically designed to +support browsing and searching. + +While some consider the Internet {{TERM[expand]DNS}} (DNS) is an +example of a globally distributed directory service, DNS is not +browsable nor searchable. It is more properly described as a +globally distributed {{lookup}} service. + + +H2: What is LDAP? + +{{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. LDAP is an {{ORG:IETF}} Standard Track protocol and is +specified in "Lightweight Directory Access Protocol (LDAP) Technical +Specification Road Map" {{REF:RFC4510}}. + +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 +{{TERM: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.png"; 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.png"; 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:RFC4514}}, "LDAP: 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 data security (integrity and confidentiality) +services. + + +H2: When should I use LDAP? + +This is a very good question. In general, you should use a Directory +server when you require data to be centrally managed, stored and accessible via +standards based methods. + +Some common examples found throughout the industry are, but not limited to: + +* Machine Authentication +* User Authentication +* User/System Groups +* Address book +* Organization Representation +* Asset Tracking +* Telephony Information Store +* User resource management +* E-mail address lookups +* Application Configuration store +* PBX Configuration store +* etc..... + +There are various {{SECT:Distributed Schema Files}} that are standards based, but +you can always create your own {{SECT:Schema Specification}}. + +There are always new ways to use a Directory and apply LDAP principles to address +certain problems, therefore there is no simple answer to this question. + +If in doubt, join the general LDAP forum for non-commercial discussions and +information relating to LDAP at: +{{URL:http://www.umich.edu/~dirsvcs/ldap/mailinglist.html}} and ask + +H2: When should I not use LDAP? + +When you start finding yourself bending the directory to do what you require, +maybe a redesign is needed. Or if you only require one application to use and +manipulate your data (for discussion of LDAP vs RDBMS, please read the +{{SECT:LDAP vs RDBMS}} section). + +It will become obvious when LDAP is the right tool for the job. + + +H2: How does LDAP work? + +LDAP utilizes a {{client-server model}}. One or more LDAP servers +contain the data making up the directory information tree ({{TERM: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. + + +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 Standalone 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 nor does it support the complete 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 Software does not include such a gateway. + + +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 and data security services via {{TERM:SASL}} + * Certificate authentication and data security services 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 {{so-called}} LDAPv2 +implementations (including {{slapd}}(8)) do not conform to the +LDAPv2 technical specification, interoperability amongst +implementations claiming LDAPv2 support is limited. As LDAPv2 +differs significantly from LDAPv3, deploying both LDAPv2 and LDAPv3 +simultaneously is quite problematic. LDAPv2 should be avoided. +LDAPv2 is disabled by default. + + +H2: LDAP vs RDBMS + +This question is raised many times, in different forms. The most common, +however, is: {{Why doesn't OpenLDAP use a relational database management + system (RDBMS) instead of an embedded key/value store like LMDB?}} In +general, expecting that the sophisticated algorithms implemented by +commercial-grade RDBMS would make {{OpenLDAP}} be faster or somehow better +and, at the same time, permitting sharing of data with other applications. + +The short answer is that use of an embedded database and custom indexing system +allows OpenLDAP to provide greater performance and scalability without loss of +reliability. OpenLDAP uses {{TERM:LMDB}} concurrent / transactional +database software. + +Now for the long answer. We are all confronted all the time with the choice +RDBMSes vs. directories. It is a hard choice and no simple answer exists. + +It is tempting to think that having a RDBMS backend to the directory solves all +problems. However, it is a pig. This is because the data models are very +different. Representing directory data with a relational database is going to +require splitting data into multiple tables. + +Think for a moment about the person objectclass. Its definition requires +attribute types objectclass, sn and cn and allows attribute types userPassword, +telephoneNumber, seeAlso and description. All of these attributes are multivalued, +so a normalization requires putting each attribute type in a separate table. + +Now you have to decide on appropriate keys for those tables. The primary key +might be a combination of the DN, but this becomes rather inefficient on most +database implementations. + +The big problem now is that accessing data from one entry requires seeking on +different disk areas. On some applications this may be OK but in many +applications performance suffers. + +The only attribute types that can be put in the main table entry are those that +are mandatory and single-value. You may add also the optional single-valued +attributes and set them to NULL or something if not present. + +But wait, the entry can have multiple objectclasses and they are organized in +an inheritance hierarchy. An entry of objectclass organizationalPerson now has +the attributes from person plus a few others and some formerly optional attribute +types are now mandatory. + +What to do? Should we have different tables for the different objectclasses? +This way the person would have an entry on the person table, another on +organizationalPerson, etc. Or should we get rid of person and put everything on +the second table? + +But what do we do with a filter like (cn=*) where cn is an attribute type that +appears in many, many objectclasses. Should we search all possible tables for +matching entries? Not very attractive. + +Once this point is reached, three approaches come to mind. One is to do full +normalization so that each attribute type, no matter what, has its own separate +table. The simplistic approach where the DN is part of the primary key is +extremely wasteful, and calls for an approach where the entry has a unique +numeric id that is used instead for the keys and a main table that maps DNs to +ids. The approach, anyway, is very inefficient when several attribute types from +one or more entries are requested. Such a database, though cumbersomely, +can be managed from SQL applications. + +The second approach is to put the whole entry as a blob in a table shared by all +entries regardless of the objectclass and have additional tables that act as +indices for the first table. Index tables are not database indices, but are +fully managed by the LDAP server-side implementation. However, the database +becomes unusable from SQL. And, thus, a fully fledged database system provides +little or no advantage. The full generality of the database is unneeded. +Much better to use something light and fast, like {{TERM:LMDB}}. + +A completely different way to see this is to give up any hopes of implementing +the directory data model. In this case, LDAP is used as an access protocol to +data that provides only superficially the directory data model. For instance, +it may be read only or, where updates are allowed, restrictions are applied, +such as making single-value attribute types that would allow for multiple values. +Or the impossibility to add new objectclasses to an existing entry or remove +one of those present. The restrictions span the range from allowed restrictions +(that might be elsewhere the result of access control) to outright violations of +the data model. It can be, however, a method to provide LDAP access to preexisting +data that is used by other applications. But in the understanding that we don't +really have a "directory". + +Existing commercial LDAP server implementations that use a relational database +are either from the first kind or the third. I don't know of any implementation +that uses a relational database to do inefficiently what LMDB does efficiently. +For those who are interested in "third way" (exposing EXISTING data from RDBMS +as LDAP tree, having some limitations compared to classic LDAP model, but making +it possible to interoperate between LDAP and SQL applications): + +OpenLDAP includes back-sql - the backend that makes it possible. It uses ODBC + +additional metainformation about translating LDAP queries to SQL queries in your +RDBMS schema, providing different levels of access - from read-only to full +access depending on RDBMS you use, and your schema. + +For more information on concept and limitations, see {{slapd-sql}}(5) man page, +or the {{SECT: Backends}} section. There are also several examples for several +RDBMSes in {{F:back-sql/rdbms_depend/*}} subdirectories. + + +H2: What is slapd and what can it do? + +{{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 {{TERM:IPv4}} and {{TERM:IPv6}} +and Unix {{TERM:IPC}}. + +{{B:{{TERM[expand]SASL}}}}: {{slapd}} supports strong authentication +and data security (integrity and confidentiality) services through +the use of SASL. {{slapd}}'s SASL implementation utilizes {{PRD:Cyrus +SASL}} software which supports a number of mechanisms including +{{TERM:DIGEST-MD5}}, {{TERM:EXTERNAL}}, and {{TERM:GSSAPI}}. + +{{B:{{TERM[expand]TLS}}}}: {{slapd}} supports certificate-based +authentication and data security (integrity and confidentiality) +services through the use of TLS (or SSL). {{slapd}}'s TLS +implementation can utilize {{PRD:OpenSSL}} or {{PRD:GnuTLS}}, +software. + +{{B:Topology control}}: {{slapd}} can be configured to restrict +access at the socket layer based upon network topology information. +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:MDB}}, a hierarchical high-performance transactional database backend; +and PASSWD, a simple backend interface to the {{passwd}}(5) file. +The MDB backend utilizes {{TERM:LMDB}}. + +{{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}}, and {{TERM:SQL}}). + +{{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 shadow +copies of directory information. This {{single-provider/multiple-consumer}} +replication scheme is vital in high-volume environments where a +single {{slapd}} installation just doesn't provide the necessary availability +or reliability. For extremely demanding environments where a +single point of failure is not acceptable, {{multi-provider}} replication +is also available. With {{multi-provider}} replication two or more nodes can +accept write operations allowing for redundancy at the provider level. + +{{slapd}} includes support for {{LDAP Sync}}-based +replication. + +{{B:Proxy Cache}}: {{slapd}} can be configured as a caching +LDAP proxy service. + +{{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. Configuration can +also be performed dynamically using LDAP itself, which greatly +improves manageability. + +H2: What is lloadd and what can it do? + +{{lloadd}}(8) is a daemon that provides an LDAPv3 load balancer service. +It is responsible for distributing requests across a set of {{slapd}} +instances. + +See the {{SECT:Load Balancing with lloadd}} chapter for information +about how to configure and run {{lloadd}}(8). + +Alternatively, the load balancer can run as a module embedded inside of +{{slapd}}. This is also described in the {{SECT:Load Balancing with lloadd}} chapter. + + -- cgit v1.2.3