Commit b7b1f8e3 authored by Kurt Zeilenga's avatar Kurt Zeilenga
Browse files

Cleanup formatting. Reorganization preamble information for sharing

between documents.  Add -2topics navigation.
parent c7cd8394
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# OpenLDAP Administrator's Guide: Abstract
......@@ -72,7 +72,3 @@ This configuration can be used in conjunction with the first two
configurations in situations where a single slapd does not provide the
required reliability or availability.
PB:
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Database Creation and Maintenance Tools
This section tells you how to create a slapd database from
......@@ -19,11 +20,8 @@ want to ensure the database is not accessed while it is
being created.
H2: Creating a database over LDAP
With this method, you use the LDAP client of your choice
(e.g., the ldapadd(1) tool) to add entries, just like you would
once the database is created. You should be sure to set the
......@@ -101,13 +99,13 @@ E: description=OpenLDAP Postmaster <Postmaster@OpenLDAP.org>
and then use a command like this to actually create the
entry:
E: ldapadd -f /tmp/newentry -D \
"cn=Manager, dc=OpenLDAP, dc=org" -w secret
E: ldapadd -f /tmp/newentry -D "cn=Manager, dc=OpenLDAP, dc=org" -w secret
The above command assumes that you have set {{EX: rootdn}} to
"cn=Manager, dc=OpenLDAP, dc=org" and {{EX: rootpw}}
to "secret".
H2: Creating a database off-line
The second method of database creation is to do it off-line,
......@@ -492,19 +490,19 @@ The basic steps to follow when converting your EDB format
data to an LDIF file are:
^ Locate the directory at the top of the EDB file hierarchy
.that your QUIPU DSA masters. The EDB file located there
.should contain the entries for the first level of your
.organization or organizational unit. If you are using an
.indexed database with QUIPU, you may need to create EDB
.files from your index files (using the synctree or qb2edb
.tools).
.
+If you do not have a file named EDB.root in the same
.directory that contains your organizational or organizational
.unit entry, create it now by hand. Its contents should look
.something like this:
.
that your QUIPU DSA masters. The EDB file located there
should contain the entries for the first level of your
organization or organizational unit. If you are using an
indexed database with QUIPU, you may need to create EDB
files from your index files (using the synctree or qb2edb
tools).
+ If you do not have a file named EDB.root in the same
directory that contains your organizational or organizational
unit entry, create it now by hand. Its contents should look
something like this:
.{{EX: MASTER}}
.{{EX: 000001}}
.{{EX: }}
......@@ -520,35 +518,34 @@ data to an LDIF file are:
.{{EX: }}
+ (Optional) Create a global add file and/or local .add files to
.take care of adding any attribute values that do not appear in
.the EDB files. For example, if all entries in a particular EDB
.are person entries and you want to add the appropriate
.objectClass attribute value for them, create a file called .add
.in the same directory as the person EDB that contains the
.single line:
.
take care of adding any attribute values that do not appear in
the EDB files. For example, if all entries in a particular EDB
are person entries and you want to add the appropriate
objectClass attribute value for them, create a file called .add
in the same directory as the person EDB that contains the
single line:
.{{EX: objectClass: person }}
.
+ Run the edb2ldif program to do the actual conversion.
.Make sure you are in the directory that contains the root of
.the EDB hierarchy (the one where the EDB.root file resides).
.Include a -b flag with a base DN one level above your
.organizational entry, and include -i flags to ignore any
.attributes that are not useful to slapd. E.g., the command:
.
Make sure you are in the directory that contains the root of
the EDB hierarchy (the one where the EDB.root file resides).
Include a -b flag with a base DN one level above your
organizational entry, and include -i flags to ignore any
attributes that are not useful to slapd. E.g., the command:
.{{EX: edb2ldif -v -r -b "c=US" -i iattr -i acl -i xacl -i sacl}}
.{{EX: -i lacl -i masterDSA -i slaveDSA > ldif}}
.
.will convert the entire EDB hierarchy to LDIF format and
.write the result to a file named ldif. Some attributes that are
.not useful when running slapd are ignored. The EDB
.hierarchy is assumed to reside logically below the base DN
."c=US".
.
will convert the entire EDB hierarchy to LDIF format and
write the result to a file named ldif. Some attributes that are
not useful when running slapd are ignored. The EDB
hierarchy is assumed to reside logically below the base DN
"c=US".
+ Follow the steps outlined in section 8.2 above to produce
.an LDBM database from your new LDIF file.
an LDBM database from your new LDIF file.
......@@ -646,9 +643,7 @@ type of index and what it contains. For more detailed
information see the paper "An X.500 and LDAP Database:
Design and Implementation," available in postscript format
from
{{CMD[jump="ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps"]ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps}}
{{URL:ftp://terminator.rs.itd.umich.edu/ldap/papers/xldbm.ps}}
H3: Attribute index format
......@@ -704,7 +699,3 @@ The {{EX: id2children}} index stores EIDs as keys. The data stored
is a list of EIDs, just as for the attribute indexes.
PB:
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# guide.sdf
#
!include "master.sdf"
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# index.sdf
#
!include "master.sdf"
......@@ -8,15 +8,12 @@ detail. If you are reading this guide, chances are you have already
obtained the software, but just in case, here's where you can get the
latest version of the OpenLDAP package, which includes all of the
software discussed in this guide:
{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
There is also an OpenLDAP homepage accessible from the World
Wide Web. This page contains the latest OpenLDAP news, release
announcements, and pointers to other resources. You can access it
at:
{{CMD[jump="http://www.OpenLDAP.org/"]http://www.OpenLDAP.org/}}
There is also an OpenLDAP Project has an extensive site on the
World Wide Web. This sites contains the latest OpenLDAP news,
release announcements, and pointers to other resources.
You can access the site at: {{URL: http://www.OpenLDAP.org/}}
H2: Pre-Build Configuration
......@@ -31,7 +28,6 @@ requires before making. The next sections discuss these steps in
more detail.
H3: Editing the {{EX: Make-common}} file
All of the general Make-common configuration variables (e.g.,
......@@ -82,35 +78,28 @@ option selects which package it will use. The currently supported
options in order of preference are:
*{{EX: DLDBM_USE_DBBTREE}}
.
.This option enables the Berkeley DB package btree database as the
.LDBM backend. You can get this package from
.
.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
.
LDBM backend. You can get this package from:
{{URL: ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
*{{EX: DLDBM_USE_DBHASH}}
.
.This option enables the Berkeley DB package hash database as the
.LDBM backend. You can get this package from
.
.{{CMD[jump="ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z"]ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
.
LDBM backend. You can get this package from
{{URL ftp://ftp.cs.berkeley.edu/ucb/4bsd/db.tar.Z}}
*{{EX: DLDBM_USE_GDBM}}
.
.This option enables GNU dbm as the LDBM backend. You can get this
.package from
.
.{{CMD[jump="ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz"]ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz}}
.
package from
{{URL: ftp://prep.ai.mit.edu/pub/gnu/gdbm-1.7.3.tar.gz}}
*{{EX: DLDBM_USE_NDBM}}
.
.This option enables the standard UNIX ndbm(3) package as the
.LDBM backend. This package should come standard on your UNIX
.system. man ndbm for details.
.
LDBM backend. This package should come standard on your UNIX
system. man ndbm for details.
Example to enable the Berkeley DB Btree backend:
......@@ -158,7 +147,8 @@ This option is normally set automatically in the {{EX: Make-platform}} file,
based on the platform on which you are building. You do not normally
need to set it. If you have set {{EX: THREADS}} to a non-default threads
package as described above, you can specify the appropriate
{{EX: -Ldirectory}} flag and {{EX: -llibname}} flag needed to link the package here.
{{EX: -Ldirectory}} flag and {{EX: -llibname}} flag needed to link
the package here.
H4: PHONETIC
......@@ -264,7 +254,3 @@ dash '-' appended, e.g., {{EX: slapd.conf}} is moved to {{EX: slapd.conf-}}.
If you install things twice, however, you can lose your existing configuration
files.
PB:
......@@ -31,7 +31,8 @@ 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
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
......@@ -47,7 +48,8 @@ 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
{{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
......@@ -59,7 +61,8 @@ 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
{{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
......@@ -80,7 +83,8 @@ 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
{{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
......@@ -88,7 +92,8 @@ 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
{{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
......@@ -105,7 +110,8 @@ 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
{{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
......@@ -197,8 +203,9 @@ 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,
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
......
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# SDF master file for the OpenLDAP Administrator's guide
# master.sdf
# master file for the OpenLDAP Administrator's Guide
#
#
# To generate guide for distribution:
# sdf -2html guide.sdf
# sdf -2txt guide.sdf
# cp guide.{html,txt} $distribution/doc/guide
#
# To generate pages for web
# sdf -2topics index.sdf
#
!include "../preamble.sdf"; plain
# title information
!include "title.sdf"
# Document copyright, publishing info, acknowledgements, preface
!include "preamble.sdf"; plain
!include "preface.sdf"; about
# Chapters
!include "intro.sdf"; chapter
......
......@@ -108,7 +108,3 @@ information. Here's how you might do it using the
E: ldapsearch -s base -b cn=monitor 'objectclass=*'
PB:
......@@ -8,8 +8,8 @@
# acknowledge U-M. Probably should be placed in a separate file.
P1: Acknowledgements
The OpenLDAP Project would like to thank the University of Michigan
LDAP Team for building the foundation of LDAP software and information
The OpenLDAP Project would like to thank the {{University of Michigan
LDAP Team}} for building the foundation of LDAP software and information
to which we build upon.
......
......@@ -9,71 +9,70 @@ simple and quick way to get started only. If you intend to run slapd
seriously, you should read the rest of this guide.
^ {{B:Get the software}}. {{I:Slapd}} is part of the OpenLDAP distribution, which
^ {{B:Get the software}}.
. {{I:Slapd}} is part of the OpenLDAP distribution, which
you can retrieve using this URL:
.
.{{CMD[jump="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz"]ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
.
..{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}
.If you are reading this guide, you have probably already done this.
.
+ {{B:Untar the distribution}}. Pick a place for the LDAP source to live, cd
there, and untar it. For example:
.
.{{EX: cd /usr/local/src}}
.{{EX: gunzip -c openldap-release.tgz | tar xvfB -}}
.{{EX: cd ldap}}
+{{B: Configure the software}}.
.
.You will have to edit two files to configure things for your site.
.
.{{EX: vi Make-common}}
+ {{B: Configure the software}}.
. You will have to edit two files to configure things for your site.
.{{EX:vi Make-common}}
.{{EX:vi include/ldapconfig.h.edit}}
.
.Read the comments in Make-common and configure things
.appropriately. If you have the Berkeley DB package installed, or the
.GDBM package, you should set the LDBMBACKEND variable
.accordingly. Otherwise, the defaults should be OK to get you started.
.
.In the include/ldapconfig.h.edit file, be sure to set the DEFAULT_BASE
.and LDAPHOST variables to something appropriate for your site.
.Other than that, the defaults should work OK.
. Read the comments in Make-common and configure things
appropriately. If you have the Berkeley DB package installed, or the
GDBM package, you should set the LDBMBACKEND variable
accordingly. Otherwise, the defaults should be OK to get you started.
. In the include/ldapconfig.h.edit file, be sure to set the DEFAULT_BASE
and LDAPHOST variables to something appropriate for your site.
Other than that, the defaults should work OK.
+ {{B:Install the software}}.
. From the top level LDAP source directory, type:
+{{B:Install the software}}. From the top level LDAP source directory,
type:
.
.{{EX: su}}
.{{EX: make install}}
.
.Examine the output of this command carefully to ensure everything is
.installed properly.
.
. Examine the output of this command carefully to ensure everything is
installed properly.
+ {{B:Make a configuration file}}.
. Create a file called myslapd.conf and
enter the following lines into it. See Section 5 for more details on this
file.
+{{B:Make a configuration file}}. Create a file called myslapd.conf and
.enter the following lines into it. See Section 5 for more details on this
.file.
.
.{{EX:referral ldap://ldap.openldap.org}}
.{{EX:database ldbm}}
.{{EX:suffix "o=<YOUR ORGANIZATION>, c=US"}}
.{{EX:rootdn "cn=<YOUR NAME>, o=<YOUR ORGANIZATION>, c=US"}}
.{{EX:rootpw secret}}
.
.Be sure to replace "<YOUR ORGANIZATION>" with the name of your
.organization and "<YOUR NAME>" with your name. If you are not in
.the US, replace "US" with your two-letter country code. The rootdn
.and rootpw lines are only required if later you want to easily add or
.modify entries via LDAP.
.
organization and "<YOUR NAME>" with your name. If you are not in
the US, replace "US" with your two-letter country code. The rootdn
and rootpw lines are only required if later you want to easily add or
modify entries via LDAP.
+ {{B:Create a database}}.
. This is a two-step process. Step A is to create
a file (we'll call it myldif) containing the entries you want your database
to contain. Use the following example as a guide, or see Section 7.3 for
more details.
+{{B:Create a database}}. This is a two-step process. Step A is to create
.a file (we'll call it myldif) containing the entries you want your database
.to contain. Use the following example as a guide, or see Section 7.3 for
.more details.
.
.{{EX:dn: o=<YOUR ORGANIZATION>, c=US}}
.{{EX:o: <YOUR ORGANIZATION>}}
.{{EX:objectclass: organization}}
......@@ -83,43 +82,38 @@ type:
.{{EX:sn: <YOUR LAST NAME>}}
.{{EX:mail: <YOUR EMAIL ADDRESS>}}
.{{EX:objectclass: person}}
.
.You can include additional entries and attributes in this file if you want,
.or add them later via LDAP.
.
or add them later via LDAP.
.Step B is to run this file through a tool to create the slapd database.
.
.{{EX:$(ETCDIR)/ldif2ldbm -f myslapd.conf -i myldif}}
.
.Where myslapd.conf is the configuration file you made in step 6, and
.myldif is the file you made in step 7A above. By default, the database
.files will be created in /usr/tmp. You may specify an alternate directory
.via the directory option in the slapd.conf file.
.
myldif is the file you made in step 7A above. By default, the database
files will be created in /usr/tmp. You may specify an alternate directory
via the directory option in the slapd.conf file.
+ {{B:See if it works}}.
. You can use any LDAP client to do this, but our
example uses the ldapsearch tool.
+{{B:See if it works}}.You can use any LDAP client to do this, but our
.example uses the ldapsearch tool.
.
.{{EX:ldapsearch -h 127.0.0.1 -b 'o=<YOUR ORGANIZATION>, c=US' 'objectclass=*'}}
.
.This command will search for and retrieve every entry in the database.
.Note the use of single quotes around the filter, which prevents the "*"
.from being interpreted by the shell.
.
.You are now ready to add more entries (e.g., using {{I:ldapadd}}(3) or
.another LDAP client), experiment with various configuration options,
.backend arrangements, etc. Note that by default, the {{I:slapd}} database
.grants {{EX:READ}} access to everybody. So if you want to add or modify
.entries over LDAP, you will have to bind as the rootdn specified in the
.config file (see Section 5.2.2), or change the default access control
.(see Section 5.3).
.
. This command will search for and retrieve every entry in the database.
Note the use of single quotes around the filter, which prevents the "*"
from being interpreted by the shell.
The following sections provide more detailed information on making,
installing, and running slapd.
. You are now ready to add more entries (e.g., using {{I:ldapadd}}(3) or
another LDAP client), experiment with various configuration options,
backend arrangements, etc. Note that by default, the {{I:slapd}} database
grants {{EX:READ}} access to everybody. So if you want to add or modify
entries over LDAP, you will have to bind as the rootdn specified in the
config file (see Section 5.2.2), or change the default access control
(see Section 5.3).
PB:
The following sections provide more detailed information on making,
installing, and running slapd.
......@@ -38,6 +38,3 @@ will continue the search at the new company's server.
A mechanism similar to this is used to support distributed
indexing, described in Appendix C.
PB:
......@@ -119,7 +119,3 @@ where {{EX: ETCDIR}} has the value you gave it in the
during pre-build configuration. Finally, send inetd a HUP signal,
and you should be all set.
PB:
......@@ -908,7 +908,3 @@ Note the use of `\' to escape the quotes necessary in the
distinguished names given on lines 3 and 5. By default, all
indexes are maintained for every attribute in an entry.
PB:
......@@ -5,11 +5,7 @@
# Master: master.sdf
#
!define DOC_NAME "OpenLDAP Administrators Guide"
!define DOC_AUTHOR "OpenLDAP <{{URL:http://www.openldap.org/}}>"
!define DOC_LOGO "../images/LDAPwww.gif"
!define DOC_LOF_TITLE "Figures"
!define DOC_LOF
!build_title
!define DOC_TYPE "OpenLDAP Administrators Guide"
!build_title
......@@ -85,5 +85,3 @@ So, take a look at the index lines in your slapd configuration file to
ensure that only those indices that make sense and are needed
are being maintained.
PB:
# Copyright 1999, The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
#
# Preamble for all OpenLDAP SDF documents
#
#
# Paths are relative to the main subdirectories
#
!define DOC_AUTHOR "OpenLDAP <{{URL:http://www.openldap.org/}}>"
!define DOC_TYPE "OpenLDAP"
!define DOC_LOGO "../images/LDAPwww.gif"
#!define DOC_HTML_LOGO "../images/LDAPwww.gif"
#!define DOC_TOPIC_LOGO "../images/LDAPwww.gif"
!define DOC_LOF_TITLE "Figures"
!define DOC_LOF
!define HTML_URL_HOME "http://www.openldap.org/"
!define HTML_URL_CATALOG "../index.html"
#
# Plain Copyright for Software Distribution
#
!define NO_C