From 0d27b6df7439eb6d69ce7bee25982b7107ca0aa8 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Thu, 10 Aug 2000 22:31:41 +0000 Subject: [PATCH] Fix up hyperlinks and revamp slapdconfig and misc other sections --- doc/guide/admin/intro.sdf | 33 +++++---- doc/guide/admin/quickstart.sdf | 17 ++--- doc/guide/admin/referrals.sdf | 8 +-- doc/guide/admin/replication.sdf | 2 +- doc/guide/admin/slapdconfig.sdf | 119 ++++++++++++++++++-------------- 5 files changed, 102 insertions(+), 77 deletions(-) diff --git a/doc/guide/admin/intro.sdf b/doc/guide/admin/intro.sdf index a860b825d2..c216f5646e 100644 --- a/doc/guide/admin/intro.sdf +++ b/doc/guide/admin/intro.sdf @@ -1,11 +1,13 @@ # $OpenLDAP$ # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Introduction to slapd and slurpd +H1: Introduction to OpenLDAP Directory Services -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 +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). @@ -222,21 +224,20 @@ 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. +LDAP servers were gateway between LDAP and the X.500 {{TERM[expand]DAP}} +({{TERM:DAP}}). 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. 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. +DAP server is no small piece of software to operate. 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 +the burden from clients. 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, 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 @@ -245,7 +246,10 @@ 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. +service on a {{read-only}} basis. See the +{{SECT:Replication to an X.500 DSA}} +section in the +{{SECT:Replication with slurpd}} chapter of this document. 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 @@ -264,3 +268,6 @@ 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). diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf index 166300ea19..6d81197d2a 100644 --- a/doc/guide/admin/quickstart.sdf +++ b/doc/guide/admin/quickstart.sdf @@ -7,15 +7,13 @@ H1: A Quick-Start Guide to Running slapd This chapter provides a quick step-by-step guide to building, installing and running {{slapd}}(8). It is intended to provide users with a simple and quick way to get started only. -If you intend to run slapd seriously, you should read the rest +If you intend to run {{slapd}} seriously, you should read the rest of this guide. Note: This guide does not use strong authentication nor any privacy and integrity protection services. These services are -described in detail in later chapters. This guide should -only be used in isolated environments (such as on a single -host protected by a firewall). +described in detail in later chapters. ^{{B:Get the software}}. @@ -71,7 +69,8 @@ is installed into {{F:/usr/local}}. This is typically done as root. +{{B:Edit the configuration file}}. .Use this chapter as a brief tutorial. For more details on the -configuration file, see slapd.conf(5) and chapter 5. +configuration file, see slapd.conf(5) and the +{{SECT:The slapd Configuration File}} chapter of this document. .Now we need to edit the default configuration file that was installed earlier. The {{slapd}} configuration file {{slapd.conf}}(5) @@ -133,7 +132,7 @@ mechanisms. These are described in later chapters. . At this point the LDAP server is up and running, but there isn't any data in the directory. You can check to see if the server is running and your naming context (the {{EX:suffix}} you specified above) -by searching it with {{ldapsearch}}(1). By default ldapsearch is +by searching it with {{ldapsearch}}(1). By default, ldapsearch is installed as {{F:/usr/local/bin/ldapsearch}}. ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}} @@ -151,7 +150,8 @@ special characters from interpreted by the shell. This should return: . This is a two-step process. The first step is to create a file (we'll call it {{F:example.ldif}}) containing the entries you want your database to contain. Use the following example as a -guide, or see Section 7.3 for more details. +guide, or see {{Database Creation and Maintenance Tools}} section +of this document for more details. ..{{EX:dn: dc=example, dc=net}} ..{{EX:objectclass: dcObject}} @@ -203,7 +203,8 @@ database grants {{read access to everybody}} excepting the {{super-user}} (as specified by the {{EX:rootdn}} configuration directive). It is highly recommended that you establish controls to restrict access to authorized users. Access controls are discussed -in a later chapter. +in the {{SECT:Access Control}} section of the +{{SECT:The slapd Configuration File}} chapter. The following chapters provide more detailed information on making, installing, and running {{slapd}}(8). diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf index b7e7b35e09..f1989186b1 100644 --- a/doc/guide/admin/referrals.sdf +++ b/doc/guide/admin/referrals.sdf @@ -58,7 +58,7 @@ H2: Immediate Superior Knowledge Information Immediate superior knowledge information may be provided in the entry at the root of a delegated subtree. The knowledge information -is contained with {{ref}} operational attribute. +is contained with {{EX:ref}} operational attribute. Extending the example above, a {{ref}} attribute can be added to the entry {{EX:dc=subtree,dc=example,dc=net}} in server B indicating @@ -72,7 +72,7 @@ that A holds the immediate superior naming context. The server uses this information to generate referrals to management operations. -For those familiar with X.500, this use of the {{ref}} attribute +For those familiar with X.500, this use of the {{EX:ref}} attribute is similar to an X.500 knowledge reference held in a {{immSupr}} {{TERM:DSE}}. !endif @@ -100,11 +100,11 @@ The server uses this information to generate referrals to operations acting upon operations not within or subordinate to any of the naming contexts held by the server. -For those familiar with X.500, this use of the {{ref}} attribute +For those familiar with X.500, this use of the {{EX:ref}} attribute is similar to an X.500 knowledge reference held in a {{Supr}} {{TERM:DSE}}. -H2: ManageDSAit +H2: The ManageDsaIT Control Adding, modify, and deleting referral objects is generally done using {{ldapmodify}}(1) or similar tools which support the diff --git a/doc/guide/admin/replication.sdf b/doc/guide/admin/replication.sdf index 422cbf36e4..ea9ebd5894 100644 --- a/doc/guide/admin/replication.sdf +++ b/doc/guide/admin/replication.sdf @@ -348,7 +348,7 @@ and exit, use the command > slurpd -r /usr/tmp/replog.slave.example.com:389 -o -H2: Replication from a slapd directory server to an X.500 DSA +H2: Replication to an X.500 DSA In mixed environments where both X.500 DSAs and slapd are used, it may be desirable to replicate changes from a diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 8e74a4f0af..f2b96989b0 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -4,16 +4,15 @@ H1: The slapd Configuration File -Once the software has been built and installed, you are ready to configure it -for use at your site. All slapd runtime configuration is accomplished through -the {{I:slapd.conf}}(5) file, normally installed in the -{{EX:/usr/local/etc/openldap}} directory. +Once the software has been built and installed, you are ready +to configure it for use at your site. The slapd runtime configuration +is primarily accomplished through the {{I:slapd.conf}}(5) file, +normally installed in the {{EX:/usr/local/etc/openldap}} directory. An alternate configuration file can be specified via a -command-line option to slapd or slurpd (see Sections 5 and 8, -respectively). This section describes the general format of the config file, -followed by a detailed description of each config file directive. - +command-line option to {{slapd}}(8) or {{slurpd}}(8). This chapter +describes the general format of the config file, followed by a +detailed description of commonly used config file directives. H2: Configuration File Format @@ -89,31 +88,40 @@ H4: access to [ by ]+ This directive grants access (specified by ) to a set of entries and/or attributes (specified by ) by one or -more requesters (specified by ). See Section 5.3 on -access control for more details and examples. +more requesters (specified by ). +See the {{SECT:Access Control}} section of this chapter for more +details and examples. H4: attributetype This directive defines an attribute type. + H4: defaultaccess { none | compare | search | read | write } This directive specifies the default access to grant requesters -not matched by any other access line (see Section 5.3). Note -that an access level implies all lesser access levels (e.g., -write access implies read, search and compare). +when no {{EX:access}} directives have been specified. Access +levels implies all lesser access levels (e.g., read access +implies search and compare but no write). + +Note: It is recommend that the {{EX:access}} directive be used +to specify access control. See the {{SECT:Access Control}} +section of this chapter for information regarding the {{EX:access}} +directive. \Default: E: defaultaccess read + H4: include This directive specifies that slapd should read additional configuration information from the given file before continuing with the next line of the current file. The included file should -follow the normal slapd config file format. +follow the normal slapd config file format. The file is commonly +used to include files containing schema specifications. Note: You should be careful when using this directive - there is no small limit on the number of nested include directives, and no @@ -201,19 +209,6 @@ from a search operation. > sizelimit 500 -H4: srvtab - -This directive specifies the srvtab file in which slapd can find the -Kerberos keys necessary for authenticating clients using -Kerberos. This directive is only meaningful if you are using -Kerberos authentication, which must be enabled at compile -time by including the appropriate definitions in the -{{EX:Make-common}} file. - -\Default: - -> srvtab /etc/srvtab - H4: timelimit This directive specifies the maximum number of seconds (in real @@ -289,8 +284,8 @@ updatedn directive in the slave slapd's config file. Since DNs are likely to contain embedded spaces, the entire {{EX:"binddn="}} string should be enclosed in double quotes. -The {{EX:bindmethod}} is either simple or kerberos, depending on -whether simple password-based authentication or kerberos +The {{EX:bindmethod}} is either simple or Kerberos, depending on +whether simple password-based authentication or Kerberos authentication is to be used when connecting to the slave slapd. Simple authentication requires a valid password be given. Kerberos authentication requires a valid srvtab file. @@ -299,11 +294,12 @@ The {{EX:credentials=}} parameter, which is only required if using simple authentication, gives the password for {{EX:binddn}} on the slave slapd. -The {{EX:srvtab=}} parameter, which is only required if using -kerberos, specifies the filename which holds the kerberos key -for the slave slapd. If omitted, {{F:/etc/srvtab}} is used. +The {{EX:srvtab=}} parameter is deprecated in favor of SASL +based authentication services. + +See the {{SECT:Replication}} chapter for more information on how to +use this directive. -See Section 10 for more details on replication. H4: replogfile @@ -315,42 +311,51 @@ However, you can also use it to generate a transaction log, if slurpd is not running. In this case, you will need to periodically truncate the file, since it will grow indefinitely otherwise. -See Section 10 for more details on replication. +See the {{SECT:Replication}} chapter for more information on how to +use this directive. + H4: rootdn -This directive specifies the DN of an entry that is not subject to +This directive specifies the DN that is not subject to access control or administrative limit restrictions for -operations on this database. +operations on this database. The DN need not refer to +an entry in the directory. The DN may refer to a SASL +identity. -\Example: +Entry-based Example: > rootdn "cn=Manager, dc=example, dc=com" +SASL-based Example: + +> rootdn "uid=root@EXAMPLE.COM" + + H4: rootkrbname -This directive specifies a kerberos name for the DN given above +This directive specifies a Kerberos name for the DN given above that will always work, regardless of whether an entry with the -given DN exists or has a {{EX:krbName}} attribute. This directive is -useful when creating a database and also when using slurpd -to provide replication service (see Section 10). +given DN exists or has a {{EX:krbName}} attribute. +This directive is deprecated in favor of SASL based authentication. \Example: > rootkrbname admin@EXAMPLE.COM + H4: rootpw This directive specifies a password for the DN given above that will always work, regardless of whether an entry with the given -DN exists or has a password. This directive is useful when -creating a database and also when using slurpd to provide -replication service (see Section 10). +DN exists or has a password. +This directive is deprecated in favor of SASL based authentication. \Example: > rootpw secret + H4: suffix This directive specifies the DN suffix of queries that will be @@ -373,9 +378,20 @@ prefix of another, it must appear after it in the config file. H4: updatedn This directive is only applicable in a slave slapd. It specifies the -DN allowed to make changes to the replica (typically, this is -the DN slurpd binds as when making changes to the replica). +DN allowed to make changes to the replica. This may be the +the DN slurpd binds as when making changes to the replica or +the DN associated with a SASL identity. +Entry-based Example: + +> updatedn "cn=Update Daemon, dc=example, dc=com" + +SASL-based Example: + +> updatedn "uid=slurpd@EXAMPLE.COM" + +See the {{SECT:Replication}} chapter for more information on how to +use this directive. H3: LDBM Backend-Specific Directives @@ -421,8 +437,9 @@ containing the database and associated indexes live. H4: index { | default} [pres,eq,approx,sub,none] This directive specifies the indexes to maintain for the given -attribute. If only an is given, all possible indexes are -maintained. +attribute. If only an {{EX:}} is given, the default +indexes are maintained. + \Example: @@ -432,9 +449,9 @@ maintained. The first line sets the default to indices to maintain to present and equality. The second line causes the default (pres,eq) set -of indices to be maintained for objectClass and uid attribute +of indices to be maintained for {{EX:objectClass}} and {{EX:uid}} attribute types. The third line causes equality, substring, and approximate -filters to be maintained for cn and sn attribute types. +filters to be maintained for {{EX:cn}} and {{EX:sn}} attribute types. H4: mode @@ -954,7 +971,7 @@ through 13 specify the hostname and port for a replicated host, the DN to bind as when performing updates, the bind method (simple) and the credentials (password) for the binddn. Lines 14 through 17 specify a second replication site, -using kerberos instead of simple authentication. See Section +using Kerberos instead of simple authentication. See Section 10 on slurpd for more information on these directives. Lines 19 through 21 indicate the indexes to maintain for -- 2.39.5