From: Kurt Zeilenga Date: Mon, 4 Sep 2000 22:51:48 +0000 (+0000) Subject: ITS#708: Admin Guide -- more editing X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~2108 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=54248d8cbc15aec9c8509951d880cb0e1efb98cb;p=openldap ITS#708: Admin Guide -- more editing More spelling, grammar, and stylistic fixups. Submitted by Cedric Tefft --- diff --git a/doc/guide/admin/dbtools.sdf b/doc/guide/admin/dbtools.sdf index b734fc3f89..5d3cb4c3ba 100644 --- a/doc/guide/admin/dbtools.sdf +++ b/doc/guide/admin/dbtools.sdf @@ -28,14 +28,14 @@ H2: Creating a database over LDAP With this method, you use the LDAP client of your choice (e.g., the ldapadd(1)) to add entries, just like you would once the database is created. You should be sure to set the -following configuration options before starting slapd: +following options in the configuration file before starting slapd: > suffix -As described in the preceding section, this option says what -entries are to be held by this database. You should set this -to the DN of the root of the subtree you are trying to create. -For example +As described in the {{SECT:General Database Directives}} section, +this option defines which entries are to be held by this database. +You should set this to the DN of the root of the subtree you +are trying to create. For example: > suffix "dc=example, dc=com" @@ -51,8 +51,8 @@ For example: You need to create this directory with appropriate permissions such that slapd can write to it. -You need to make it so you can connect to slapd as directory user -with permission to add entries. You can configure the directory +You need to configure slapd so that you can connect to it as a directory +user with permission to add entries. You can configure the directory to support a special {{super-user}} or {{root}} user just for this purpose. This is done through the following two options in the database definition: @@ -79,7 +79,7 @@ contains the index definitions you want: > index { | default} [pres,eq,approx,sub,none] For example, to index the cn, sn, uid and objectclass -attributes the following index configuration lines could be +attributes, the following index configuration lines could be used. > index cn,sn,uid @@ -119,7 +119,7 @@ H2: Creating a database off-line The second method of database creation is to do it off-line, using the slapd database tools described below. This method is best if you have many thousands of entries to create, which -would take an unacceptably long time using +would take an unacceptably long time to add using the LDAP method described above. These tools read the slapd configuration file and an input file containing a text representation of the entries to add. For database types which @@ -130,10 +130,10 @@ file database definition first: > suffix -As described in the preceding section, this option says what -entries are to be held by this database. You should set this -to the DN of the root of the subtree you are trying to create. -For example +As described in the {{SECT:General Database Directives}} section, +this option defines which entries are to be held by this database. +You should set this to the DN of the root of the subtree you are +trying to create. For example: > suffix "dc=example, dc=com" @@ -191,18 +191,18 @@ the {{SECT:Command-Line Options}} section in {{SECT:Running slapd}}. > -n -An optional argument that specifies the configuration file -database for which to build. The first database listed +An optional argument that specifies which database to modify. +The first database listed in the configuration file is "1", the second "2", etc. By default, the first ldbm database in the configuration file is used. Should not be used in conjunction with {{EX:-b}}. > -b -An optional argument that specifies the configuration file -database for which to build. The provided suffix is matched -against database {{EX:suffix}} to determine the database -number. Should not be used in conjunction with {{EX:-n}}. +An optional argument that specifies which database to modify. +The provided suffix is matched against a database {{EX:suffix}} +directive to determine the database number. Should not be +used in conjunction with {{EX:-n}}. H3: The {{EX:slapindex}} program @@ -222,9 +222,9 @@ upon the current database contents. H3: The {{EX:slapcat}} program -The {{EX:slapcat}} program is used to dump the database to a {{TERM:LDIF}} +The {{EX:slapcat}} program is used to dump the database to an {{TERM:LDIF}} file. This can be useful when you want to make a human-readable -backup of your database or for editing your database off-line. +backup of your database or when you want to edit your database off-line. The program is invoked like this: > slapcat -l -f @@ -242,7 +242,7 @@ The {{ldif}}(1) program is used to convert arbitrary data values to {{TERM:LDIF}} format. This can be useful when writing a program or script to create the LDIF file you will feed into the {{slapadd}}(8) or {{ldapadd}}(1) program, or when writing a SHELL backend. {{ldif}}(1) -takes an attribute descriptin as an argument and reads the attribute +takes an attribute description as an argument and reads the attribute value(s) from standard input. It produces the LDIF formatted attribute line(s) on standard output. The usage is: @@ -257,7 +257,7 @@ value of the attribute. > # leading hash mark > EOF -The -b option can be used to force ldif to interpret its input +The {{EX:-b}} option can be used to force ldif to interpret its input as a single raw binary value. This option is useful when converting binary data such as a {{EX:jpegPhoto}} or {{EX:audio}} attribute. For example: @@ -282,7 +282,7 @@ The basic form of an entry is: > > ... -Lines starting with '{{EX:#}}' character are +Lines starting with a '{{EX:#}}' character are comments. An attribute description may be a simple attribute type like {{EX:cn}} or {{EX:objectClass}} or {{EX:1.2.3}} (an {{TERM:OID}} associated with an attribute type) or may include options such diff --git a/doc/guide/admin/referrals.sdf b/doc/guide/admin/referrals.sdf index 327b28ce7a..f469245de9 100644 --- a/doc/guide/admin/referrals.sdf +++ b/doc/guide/admin/referrals.sdf @@ -6,7 +6,7 @@ H1: Constructing a Distributed Directory Service For many sites, running one or more {{slapd}}(8) that hold an entire subtree of data is sufficient. But often it is desirable -to have one {{slapd}}} refer to other directory services for a +to have one {{slapd}} refer to other directory services for a certain part of the tree (which may or may not be running {{slapd}}). !if 0 @@ -28,7 +28,7 @@ together. This mechanism allows for hierarchical directory services to to be constructed. -A referral object has an structural object class of +A referral object has a structural object class of {{EX:referral}} and has the same {{TERM[expand]DN}} as the delegated subtree. Generally, the referral object will also provide the auxiliary object class {{EX:extensibleObject}}. @@ -106,7 +106,7 @@ is similar to an X.500 knowledge reference held in a H2: The ManageDsaIT Control -Adding, modify, and deleting referral objects is generally done +Adding, modifying, and deleting referral objects is generally done using {{ldapmodify}}(1) or similar tools which support the ManageDsaIT control. The ManageDsaIT control informs the server that you intend to manage the referral object as a regular diff --git a/doc/guide/admin/replication.sdf b/doc/guide/admin/replication.sdf index 6b9930e59e..9c557e3c7f 100644 --- a/doc/guide/admin/replication.sdf +++ b/doc/guide/admin/replication.sdf @@ -6,8 +6,8 @@ H1: Replication with slurpd In certain configurations, a single {{slapd}}(8) instance may be insufficient to handle the number of clients requiring directory service via LDAP. It may become necessary to -run more than one slapd instance. Many sites, -for instance, there are multiple slapd servers, one +run more than one slapd instance. At many sites, +for instance, there are multiple slapd servers: one master and one or more slaves. {{TERM:DNS}} can be setup such that a lookup of {{EX:ldap.example.com}} returns the {{TERM:IP}} addresses of these servers, distributing the load among them (or @@ -193,7 +193,7 @@ inappropriate. + Do not include a {{EX:replogfile}} directive. -+ Do include an updatedn line. The DN given should ++ Do include an {{EX:updatedn}} line. The DN given should match the DN given in the {{EX:binddn=}} parameter of the corresponding {{EX:replica=}} directive in the master slapd config file. @@ -237,8 +237,8 @@ Suffix Database {{EX:gdbm}} GNU DBM backend !endblock -In general, you should copy all files found in the database -{{EX: directory}} unless you know it not used by {{slapd}}(8). +In general, you should copy each file found in the database +{{EX: directory}} unless you know it is not used by {{slapd}}(8). Note: The copy process assumes homogeneous servers with identically configured OpenLDAP installations. @@ -261,7 +261,7 @@ standard LDAP port) on host slave.example.com. The slurpd process will bind to the slave slapd as "{{EX:cn=Replicator,dc=example,dc=com}}" using simple authentication with password "{{EX:secret}}". Note that the DN given by the {{EX:binddn=}} -directive must either exist in the slave slapd's database (or be +directive must exist in the slave slapd's database (or be the rootdn specified in the slapd config file) in order for the bind operation to succeed. The DN should also be listed as the {{EX:updatedn}} for the database in the slave's slapd.conf(5). @@ -296,7 +296,7 @@ H3: Replication errors When slurpd propagates a change to a slave slapd and receives an error return code, it writes the reason for the error and the replication record to a reject file. The reject -file is located in the same directory with the per-replica +file is located in the same directory as the per-replica replication logfile, and has the same name, but with the string "{{F:.rej}}" appended. For example, for a replica running on host {{EX:slave.example.com}}, port 389, the reject file, if it diff --git a/doc/guide/admin/schema.sdf b/doc/guide/admin/schema.sdf index f2c2ad0c57..0d3273f370 100644 --- a/doc/guide/admin/schema.sdf +++ b/doc/guide/admin/schema.sdf @@ -5,7 +5,7 @@ H1: Schema Specification This chapter describes how to extend the schema used by {{slapd}}(8). -The first section, {{SECT:Distribution Schema Files}} details optional +The first section, {{SECT:Distributed Schema Files}} details optional schema definitions provided in the distribution and where to obtain other definitions. The second section, {{SECT:Extending Schema}}, details how to define @@ -56,7 +56,7 @@ H2: Extending Schema Schema used by {{slapd}}(8) may be extended to support additional syntaxes, matching rules, attribute types, and object classes. This chapter details how to add attribute types and object classes -using the syntaxes and matching rules already support by slapd. +using the syntaxes and matching rules already supported by slapd. slapd can also be extended to support additional syntaxes and matching rules, but this requires some programming and hence is not discussed here. @@ -74,7 +74,7 @@ Each schema element is identified by a globally unique {{TERM[expand]OID}} (OID). OIDs are also used to identify other objects. They are commonly found in protocols described by {{TERM:ASN.1}}. In -particular, they are heavy used by {{TERM[expand]SNMP}} (SNMP). +particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP). As OIDs are hierarchical, your organization can obtain one OID and branch it as needed. For example, if your organization were assigned OID {{EX:1.1}}, you could branch @@ -105,7 +105,7 @@ service) see {{URL:http://www.alvestrand.no/harald/objectid/}}. .{{Under no circumstances should you use a fictious OID!}} To obtain a fully registered OID at {{no cost}}, apply for -a OID under {{ORG[expand]IANA}} (IANA) maintained +an OID under {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}} arch. Any private enterprise (organization) may request an OID to be assigned under this arch. Just fill out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} @@ -120,7 +120,7 @@ identifying LDAP schema elements. H3: Name Prefix -In addition to assign a unique object identifier to each schema +In addition to assigning a unique object identifier to each schema element, you should provide a least one textual name for each element. The name should be both descriptive and not likely to clash with names of other schema elements. In particular, @@ -197,7 +197,7 @@ where Attribute Type Description is defined by the following where whsp is a space ('{{EX: }}'), numericoid is a globally unique OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more -names, woid is either the name or OID, and noidlen is a optional length +names, woid is either the name or OID, and noidlen is an optional length specifier (e.g {{EX:{10}}}). For example, the attribute types {{EX:name}} and {{EX:cn}} are defined @@ -214,9 +214,9 @@ Notice that each defines the attribute's OID and descriptive names. Each name is an alias for the OID. {{slapd}}(8) returns the first listed name when returning results. -The first attribute, {{EX:name}}, has a syntax of directory string +The first attribute, {{EX:name}}, has a syntax of {{EX:directoryString}} (a UTF-8 encoded Unicode string) with a recommend maximun length. -Note that syntaxes is specified by OID. In addition, the equality +Note that syntaxes are specified by OID. In addition, the equality and substring matching uses case ignore rules. Below are tables listing commonly used supported syntax and matching rules. @@ -263,10 +263,10 @@ caseExactSubstringsIA5Match substrings case sensitive, space insensitive !endblock The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence -in inherits the syntax, matching rules, and usage of {{EX:name}}. +it inherits the syntax, matching rules, and usage of {{EX:name}}. {{EX:commonName}} is an alternative name. -Neither attributes is restricted to a single value and both are +Neither attribute is restricted to a single value and both are meant for usage by user applications. You likely won't need to specify other parameters such as {{EX:OBSOLETE}}. @@ -276,8 +276,8 @@ The following subsections provide a couple of examples. H4: myUniqueName Many organizations maintain a single unique name for each user. -Though one could use {{EX:displayName}} ({{REF:RFC2798}}), but this -attribute is meant to be controlled by the user, not the +Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this +attribute is really meant to be controlled by the user, not the organization. We could just copy the definition of {{EX:displayName}} from {{F:inetorgperson.schema}} and replace the OID, name, and description, e.g: @@ -289,7 +289,7 @@ description, e.g: > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 > SINGLE-VALUE ) -However, if we desire this name to included in +However, if we want this name to be included in {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute could alternatively be defined as a subtype of {{EX:name}}, e.g.: @@ -317,8 +317,8 @@ As noted in the description, LDAP has no knowledge of the format of the photo. It's assumed that all applications accessing this attribute agree on the handling of values. -If you want to support multiple photo format, one could define -a separate attributes type for each format, prefix the photo +If you wanted to support multiple photo formats, you could define +a separate attribute type for each format, prefix the photo with some typing information, or describe the value using {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option. @@ -353,7 +353,7 @@ where Object Class Description is defined by the following where whsp is a space ('{{EX: }}'), numericoid is a globally unique OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more -names, oids is one or more names and/or OIDs. +names, and oids is one or more names and/or OIDs. H4: myPhotoObject diff --git a/doc/guide/admin/slapdconfig.sdf b/doc/guide/admin/slapdconfig.sdf index 98892c8b10..41464615bf 100644 --- a/doc/guide/admin/slapdconfig.sdf +++ b/doc/guide/admin/slapdconfig.sdf @@ -308,7 +308,7 @@ authentication requires specification of {{EX:binddn}} and {{EX:credentials}} parameters. Kerberos authentication is deprecated in favor of SASL authentication -mechanisms, in particular the {EX:KERBEROS_V4}} and {{EX:GSSAPI}} +mechanisms, in particular the {{EX:KERBEROS_V4}} and {{EX:GSSAPI}} mechanisms. Kerberos authentication requires {{EX:binddn}} and {{EX:srvtab}} parameters. @@ -319,8 +319,8 @@ credentials can be specified using {{EX:authcid}} and {{EX:credentials}} respectively. The {{EX:authzid}} parameter may be used to specify an authorization identity. -See the {{SECT:Replication}} chapter for more information on how to -use this directive. +See the chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. H4: replogfile @@ -333,8 +333,8 @@ 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 the {{SECT:Replication}} chapter for more information on how to -use this directive. +See the chapter entitled {{SECT:Replication with slurpd}} for more +information on how to use this directive. H4: rootdn