[Date Prev][Date Next] [Chronological] [Thread] [Top]
Admin Guide editing (ITS#695)

To: openldap-its@OpenLDAP.org
Subject: Admin Guide editing (ITS#695)
From: cedric@earthling.net
Date: Tue, 29 Aug 2000 18:25:13 GMT
Full_Name: Cedric Tefft
Version: CVS
OS: N/A
URL: ftp://ftp.openldap.org/incoming/
Submission from: (NULL) (205.138.230.85)


I have been doing some clean-up editing of the Admin Guide a today.  Here is a
patch against yesterday's CVS of the SDF source.  Mostly these are grammar,
punctuation, and spelling fixes.  Note these changes are only through section
section 6 (Running SLAPD).  I will do the rest of the manual later this week
(time permitting).



diff -ur admin.orig/install.sdf admin/install.sdf
--- admin.orig/install.sdf	Mon Aug 28 23:33:36 2000
+++ admin/install.sdf	Tue Aug 29 03:54:07 2000
@@ -93,14 +93,14 @@
 H3: Database software
 
 OpenLDAP's {{slapd}}(8) primary database backend, {{TERM:LDBM}},
-requires that a compatible database package for entry storage.  LDBM
+requires a compatible database package for entry storage.  LDBM
 is compatible with {{ORG[expand]Sleepy}}'s {{PRD:BerkeleyDB}} (recommended)
 or the {{ORG[expand]FSF}}'s {{PRD:GNU}} Database Manager ({{PRD:GDBM}}).
 If neither of these packages are available at configure time,
 you will not be able build slapd(8) with primary database backend.
 
 Your operating system may provide one of these two packages in
-in base system or as an optional software component.  You may
+the base system or as an optional software component.  You may
 need may need to obtain the software and install it yourself.
 
 {{PRD:BerkeleyDB}} is available from {{ORG[expand]Sleepy}}'s
@@ -127,20 +127,21 @@
 
 {{slapd}}(8) supports TCP wrappers (IP level access control filters)
 if preinstalled.  Use of TCP wrappers or other IP level access
-filters (such as those provided by a IP-level firewall) is recommended
+filters (such as those provided by an IP-level firewall) is recommended
 for servers containing non-public information.
 
 
 H2: Running configure
 
-If you haven't already done so, extra the distribution for the
+If you haven't already done so, extract the distribution from the
 compressed archive file and change directory to the top of the
 distribution:
 
 .{{EX:gunzip -c openldap-VERSION.tgz | tar xf -}}
 .{{EX:cd openldap-VERSION}}
 
-Replacing {{EX:VERSION}} with the appropriate version string.
+You'll have to replace {{EX:VERSION}} with the version name of the
+release.
 
 Note: If you intend to build OpenLDAP for multiple platforms from a
 single source tree you should consult the {{F: INSTALL}} file in the
@@ -166,13 +167,14 @@
 LIBS    	Specify additional libraries
 !endblock
 
-Now run the configure script with any desired configure options or
+Now run the configure script with any desired configuration options or
 environment variables.
 
 >	[[env] settings] ./configure [options]
 
-As an example, lets assume that we want a copy of OpenLDAP configured to use
the
-LDBM backend, and the shell backend.  The LDBM backend is turned on by default,
so we don't need to do anything special to enable it.
+As an example, let's assume that we want a copy of OpenLDAP configured to use
the
+LDBM backend and the shell backend.  The LDBM backend is turned on by default,
+so we don't need to do anything special to enable it.
 
 Additionally, we've installed the BerkeleyDB database package.  
 {{EX:configure}} is smart enough to use BerkeleyDB automatically
@@ -197,7 +199,7 @@
 
 The {{EX:configure}} script will normally auto-detect appropriate settings.
 If you have problems at this stage, consult any platform specific
-hints and check your {{EX:configure}} options if any.
+hints and check your {{EX:configure}} options, if any.
 
 
 H2: Building the Software
@@ -206,7 +208,8 @@
 should be:
 >	Please "make depend" to build dependencies
 
-If the last line of output does not match, {{EX:configure}} has failed.
+If the last line of output does not match, {{EX:configure}} has failed,
+and you will need to review its output to determine what went wrong.
 You should not proceed until {{EX:configure}} completes successfully.
 
 To build dependencies, run:
@@ -227,7 +230,7 @@
 
 >	make test
 
-The test will run a number of tests.
+This command will run a number of tests.
 
 
 H2: Installing the Software
@@ -239,8 +242,8 @@
 setting with the {{F:--prefix}} configure option, it will be installed
 in the location you provided.
 
-Typically, the installation is done as {{root}}. From the top level OpenLDAP
-source directory, type:
+Typically, the installation is done as the super-user: {{root}}. From the top
+level OpenLDAP source directory, type:
 
 >	make install
 
diff -ur admin.orig/intro.sdf admin/intro.sdf
--- admin.orig/intro.sdf	Mon Aug 28 23:33:36 2000
+++ admin/intro.sdf	Tue Aug 29 00:42:51 2000
@@ -82,7 +82,8 @@
 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.
+Figure 1.2 shows an example using this increasingly popular naming
+approach.
 
 !import "intro_dctree.gif"; align="center"; \
 	title="LDAP directory tree (Internet naming)"
@@ -191,13 +192,13 @@
 {{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
+communication with LDAP clients; and modules which handle 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
+{{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}}.
+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 
Binary files admin.orig/intro_tree.gif and admin/intro_tree.gif differ
diff -ur admin.orig/quickstart.sdf admin/quickstart.sdf
--- admin.orig/quickstart.sdf	Mon Aug 28 23:33:36 2000
+++ admin/quickstart.sdf	Tue Aug 29 03:54:01 2000
@@ -66,7 +66,7 @@
 
 . You will need to run the provided {{EX:configure}} script to
 {{configure}} to the distribution for building on your system.  The
-{{EX:configure}} accepts many command line options that enable or
+{{EX:configure}} script accepts many command line options that enable or
 disable optional software features.  Usually the defaults are okay,
 but you may want to change them.  To get a complete list of options
 that {{EX:configure}} accepts, use the {{EX:--help}} option:
@@ -173,13 +173,13 @@
 
 
 . To check to see if the server is running and configured correctly,
-you can run search it with {{ldapsearch}}(1).  By default, ldapsearch
-is installed as {{F:/usr/local/bin/ldapsearch}}:
+you can run a search against it with {{ldapsearch}}(1).  By default,
+ldapsearch is installed as {{F:/usr/local/bin/ldapsearch}}:
 
 ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}}
 
 . Note the use of single quotes around command parameters to prevent
-special characters from interpreted by the shell.  This should return:
+special characters from being interpreted by the shell.  This should return:
 
 ..{{EX:dn:}}
 ..{{EX:namingContexts: dc=example, dc=com}}
@@ -193,9 +193,9 @@
 +{{B:Add initial entries to your directory}}.
 
 . You can use {{ldapadd}}(1) to add entries to your LDAP directory.
-{{ldapadd}} expects input in LDIF form. We'll do it two steps:
+{{ldapadd}} expects input in LDIF form. We'll do it in two steps:
 
-^^ create LDIF file
+^^ create an LDIF file
 ++ run ldapadd
 
 . Use your favorite editor and create an LDIF file that contains:
diff -ur admin.orig/runningslapd.sdf admin/runningslapd.sdf
--- admin.orig/runningslapd.sdf	Mon Aug 28 23:33:36 2000
+++ admin/runningslapd.sdf	Tue Aug 29 14:09:11 2000
@@ -12,7 +12,7 @@
 H2: Command-Line Options
 
 {{slapd}}(8) supports a number of command-line options as detailed
-in manual page.  This section details a few commonly used options.
+in the manual page.  This section details a few commonly used options.
 
 >	-f <filename>
 
@@ -21,17 +21,17 @@
 
 >	-h <URLs>
 
-This option specifies alternative listener configuration.  The
-default is {{EX:ldap:///}} which implies LDAP over TCP, on all
-interfaces, on the default LDAP port 389.  You can specify
+This option specifies alternative listener configurations.  The
+default is {{EX:ldap:///}} which implies LDAP over TCP on all
+interfaces on the default LDAP port 389.  You can specify
 specific host-port pairs or other protocol schemes (such as
 ldaps:// or ldapi://).  For example,
 {{EX:-h "ldaps:// ldap://127.0.0.1:666"}} will create
-two listeners: one for LDAP over SSL, on all interfaces, on
-the default LDAP/SSL port 646 and one for LDAP over TCL, only
-the {{EX:localhost}} ({{loopback}}) interface, on port 666.
-Hosts may be specified using IPv4 dot-decimal form or
-using host names.  Ports values must be numeric.
+two listeners: one for LDAP over SSL on all interfaces on
+the default LDAP/SSL port 646, and one for LDAP over TCL on
+the {{EX:localhost}} ({{loopback}}) interface on port 666.
+Hosts may be specified using IPv4 dotted-decimal form or
+using host names.  Port values must be numeric.
 
 >	-n <service-name>
 
@@ -55,8 +55,8 @@
 
 This option specifies a run-time directory.  slapd will
 {{chroot}}(2) to this directory after opening listeners but
-before any reading any configuration file or initializing
-any backend.
+before reading any configuration files or initializing
+any backends.
 .
 
 >	-d <level> | ?
@@ -105,7 +105,7 @@
 
 >	/usr/local/etc/libexec/slapd [<option>]*
 
-where {{F:/usr/local/etc/libexec}} is determined by {{EX:configure}}.
+where {{F:/usr/local/etc/libexec}} is determined by {{EX:configure}}
 and <option> is one of the options described above (or in {{slapd}}(8)).
 Unless you have specified a debugging level (including level {{EX:0}}),
 slapd will automatically fork and detach itself from its controlling
@@ -119,5 +119,5 @@
 
 where {{F:/usr/local/var}} is determined by {{EX:configure}}.
 
-Killing slapd by a more drastic method may cause its information
+Killing slapd by a more drastic method may cause information
 loss or database corruption.
diff -ur admin.orig/slapdconfig.sdf admin/slapdconfig.sdf
--- admin.orig/slapdconfig.sdf	Mon Aug 28 23:33:36 2000
+++ admin/slapdconfig.sdf	Tue Aug 29 14:04:15 2000
@@ -18,8 +18,8 @@
 
 H2: Configuration File Format
 
-The {{slapd.conf}}(5) file consists three types of configuration
-information: global, backend specific, database specific.  Global
+The {{slapd.conf}}(5) file consists of three types of configuration
+information: global, backend specific, and database specific.  Global
 information is specified first, followed by information associated
 with a particular backend type, which is then followed by information
 associated with a particular database instance.  Global directives can
@@ -61,7 +61,7 @@
 
 The distribution contains an example configuration file that will
 be installed in the {{F: /usr/local/etc/openldap}} directory.
-A number of files containing schema definition (attribute types
+A number of files containing schema definitions (attribute types
 and object classes) are also provided in the
 {{F: /usr/local/etc/openldap/schema}} directory.
 
@@ -80,8 +80,8 @@
 H3: Global Directives
 
 Directives described in this section apply to all backends
-and databases, unless specifically overridden in a backend or
-database definition. Arguments to directives should be replaced
+and databases unless specifically overridden in a backend or
+database definition. Arguments that should be replaced
 by actual text are shown in brackets {{EX:<>}}.
 
 
@@ -107,9 +107,9 @@
 H4: defaultaccess { none | compare | search | read | write }
 
 This directive specifies the default access to grant requesters
-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).
+when no {{EX:access}} directives have been specified.  Any given
+access level implies all lesser access levels (e.g., read access
+implies search and compare but not write).
 
 Note: It is recommend that the {{EX:access}} directive be used
 to specify access control.  See the {{SECT:Access Control}}
@@ -124,7 +124,7 @@
 H4: idletimeout <integer>
 
 Specify the number of seconds to wait before forcibly closing
-an idle client connections.  A idletimeout of 0, the default,
+an idle client connection.  An idletimeout of 0, the default,
 disables this feature.
 
 
@@ -367,7 +367,7 @@
 Queries with a DN ending in "dc=example, dc=com"
 will be passed to this backend.
 
-Note: when the backend to pass a query to is selected, slapd
+Note: When the backend to pass a query to is selected, slapd
 looks at the suffix line(s) in each database definition in the
 order they appear in the file. Thus, if one database suffix is a
 prefix of another, it must appear after it in the config file.
@@ -469,11 +469,11 @@
 >	index objectClass,uid
 >	index cn,sn eq,sub,approx
 
-The first line sets the default to indices to maintain to present
+The first line sets the default set of indices to maintain to present
 and equality.  The second line causes the default (pres,eq) set
 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 {{EX:cn}} and {{EX:sn}} attribute types.
+indices to be maintained for {{EX:cn}} and {{EX:sn}} attribute types.
 
 H4: mode <integer>
 
@@ -486,13 +486,14 @@
 
 
 
-H3: Other Backend and Databases
+H3: Other Backend Databases
 
-{{slapd}}(8) supports a number of other backend database types.
+{{slapd}}(8) supports a number of backend database types besides the default
LDBM.
 
 !block table; align=Center; coltags="EX,N"; \
 	title="Table 5.2: Backend Database Types"
 Types	Description
+ldbm	Berkeley or GNU DBM compatible backend
 passwd	Provides read-only access to {{F:/etc/passwd}}
 shell	Shell (extern program) backend
 sql	SQL Programmable backend
@@ -576,7 +577,7 @@
 {{EX:entry}} attribute is also required. The complete examples at
 the end of this section should help clear things up.
 
-Lastly, there is a special entry selector {{EX:"*"}} is used to
+Lastly, there is a special entry selector {{EX:"*"}} that is used to
 select any entry.  It is used when no other {{EX:<what>}}
 selector has been provided.  It's equivalent to "{{EX:dn=.*}}"
 
@@ -585,7 +586,7 @@
 
 The <who> part identifies the entity or entities being granted
 access. Note that access is granted to "entities" not "entries."
-The follow table summaries entity specifiers:
+The following table summarizes entity specifiers:
 
 !block table; align=Center; coltags="EX,N"; \
 	title="Table 5.3: Access Entity Specifiers"
@@ -603,10 +604,10 @@
 >	dn=<regular expression>
 
 By "normalized", we mean that all extra spaces have been
-removed from the entities DN and commas are used to
+removed from the entity's DN and commas are used to
 separate RDN components.
 
-Other control factors forms are also supported.
+Other control factors are also supported.
 For example, a {{EX:<what>}} can be restricted by a
 regular expression matching the client's IP address or domain name:
 
@@ -632,7 +633,7 @@
 
 !block table; colaligns="LRL"; coltags="EX,EX,N"; align=Center; \
 	title="Table 5.4: Access Levels"
-Level	Privledges	Description
+Level	Privileges	Description
 none			no access
 auth	=x		needed to bind
 compare	=cx		needed to compare
@@ -642,9 +643,10 @@
 !endblock
 
 Each level implies all lower levels of access. So, for
-example, granting someone write access to an entry also
-grants them read, search, compare, and auth access.  However,
-one may use the privledges specify to grant specific permissions.
+example, granting someone {{EX:write}} access to an entry also
+grants them {{EX:read}}, {{EX:search}}, {{EX:compare}}, and 
+{{EX:auth}} access.  However, one may use the privileges specifier
+to grant specific permissions.
 
 
 H3: Access Control Evaluation
@@ -661,7 +663,7 @@
 the one slapd will use to evaluate access.
 
 Next, slapd compares the entity requesting access to the
-{{EX:<who>}} selectors within the access directive selected above,
+{{EX:<who>}} selectors within the access directive selected above
 in the order in which they appear. It stops with the first {{EX:<who>}}
 selector that matches the requester. This determines the
 access the entity requesting access has to the entry and/or
@@ -701,7 +703,7 @@
 allows authenticate, and allows authenticated users to read.
 Note that only the first {{EX:by <who>}} clause which matches applies.
 Hence, the anonymous users are granted {{EX:auth}}, not {{EX:read}}.
-The last clause just as well have been "{{EX:by users read}}".
+The last clause could just as well have been "{{EX:by users read}}".
 
 The following example shows the use of a regular expression
 to select the entries by DN in two access directives where
@@ -712,20 +714,20 @@
 >	access to dn=".*,dc=com"
 > 		by * read
 
-Read access is granted to entries under the {{EX:dc=com}}.
+Read access is granted to entries under the {{EX:dc=com}}
 subtree, except for those entries under the {{EX:dc=example,dc=com}}
 subtree, to which search access is granted.  No access to
-{{EX:dc=com}} as the neither access directive matches this DN.
+{{EX:dc=com}} will be granted as neither access directive matches this DN.
 If the order of these access directives was reversed, the
 trailing directive would never be reached, since all
 {{EX:dc=example,dc=com}} entries are also {{EX:dc=com}} entries.
 
 Also note that if no {{EX:access to}} directive matches or
 no {{EX:by <who>}} clause, {{B:access is denied}}.  That is, every
-{{EX:access to}} directive ends with a implicit {{EX:by * none}}
-clause and access list itself ends with {{EX:access to * by * none}}
-directive.  Only if no access controls are specified, is the
-{{EX:defaultaccess}} granted.
+{{EX:access to}} directive ends with an implicit {{EX:by * none}}
+clause and every access list ends with an implicit
+{{EX:access to * by * none}} directive.  Only if no access controls
+are specified is the {{EX:defaultaccess}} granted.
 
 The next example again shows the importance of ordering,
 both of the access directives and the {{EX:by <who>}} clauses.
@@ -754,7 +756,7 @@
 
 Sometimes it is useful to permit a particular DN to add or
 remove itself from an attribute. For example, if you would like to
-create a group and allow people too add and remove only
+create a group and allow people to add and remove only
 their own DN from the member attribute, you could accomplish
 it with an access directive like this:
 
@@ -788,7 +790,7 @@
 E:  3.	referral ldap://root.openldap.org
 E:  4.	access to * by * read
  
-Line 1 is a comment. Lines 2 include another config file
+Line 1 is a comment. Line 2 includes another config file
 which containing {{core}} schema definitions.
 The {{EX:referral}} directive on line 3
 means that queries not local to one of the databases defined
@@ -860,13 +862,14 @@
 Lines 20 through 22 indicate the indexes to maintain for
 various attributes.
 
-Lines 24 through 33 specify access control for entries in the
-database. For all entries, the {{EX:userPassword}} attribute is
-writable by the entry and the "admin" entry, may be used for
-authentication/authorization purposes, but is otherwise not
-readable.  All other attributes by writable by the entry and
-the "admin" entry, may be used for authentication/authorization
-purposes, but may be read by authenticated users.
+Lines 24 through 33 specify access control for entries in the 
+database. For all entries, the {{EX:userPassword}} attribute 
+is writable by the entry itself and by the "admin" entry.  It 
+may be used for authentication/authorization purposes, but is 
+otherwise not readable.  All other attributes are writable by 
+the entry and the "admin" entry, may be used for 
+authentication/authorization purposes, but may be read by 
+authenticated users.
 
 The next section of the example configuration file defines
 another LDBM database. This one handles queries involving
Prev by Date: Re: Admin Guide - new intro_tree.gif (ITS#694)
Next by Date: Re: Admin Guide editing (ITS#695)
Index(es):
- Chronological
- Thread