Added LDAP_FILTER_EXT case to filter_free()

[openldap] / doc / guide / admin / quickstart.sdf

diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf
index 98d6fc42779db97989f87adb41c54f9153b5736d..29c01a52ecd281318ce91a492a23f26aec152678 100644 (file)
--- a/doc/guide/admin/quickstart.sdf
+++ b/doc/guide/admin/quickstart.sdf
@@ -1,209 +1,277 @@
 # $OpenLDAP$
 # $OpenLDAP$

-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2001, The OpenLDAP Foundation, All Rights Reserved.

 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 
 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
 

-H1: A Quick-Start Guide to Running slapd
+H1: A Quick-Start Guide

 
 

-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
-of this guide.
+The following is a quick start guide to OpenLDAP 2.1 software,
+including the stand-alone LDAP daemon, {{slapd}}(8).

 
 

+It is meant to step you through the basic steps needed to install
+and configure OpenLDAP software. It should be used in conjunction
+with the other chapters of this document, manual pages, and
+other materials provided with the distribution (e.g. the {{F:INSTALL}}
+document) or on the OpenLDAP web site (in particular, the
+OpenLDAP Software FAQ).

 
 

-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).
+If you intend to run OpenLDAP seriously, you should review the all
+of this document before attempt to install the software.

 
 

+Note: This quick start guide does not use strong authentication
+nor any integrity or confidential protection services.  These
+services are described in other chapters of the OpenLDAP Administrator's
+Guide.

 
 

-^{{B:Get the software}}.

 
 

-.{{slapd}} is part of the {{PRD:OpenLDAP}} distribution, which
-you can retrieve from {{URL: http://www.openldap.org/software/download/}}
-or {{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}}.
-If you are reading this guide, you have probably already done this.
+.{{S: }}
+^{{B: Get the software}}
+
+. You can obtain a copy of the software by following the
+instructions on the OpenLDAP download
+page ({{URL: http://www.openldap.org/software/download/}}).
+It is recommended that new users start with the (latest)
+{{release}}.
+

 
 .{{S: }}
 
 .{{S: }}

-+{{B:Unpack the distribution}}.
++{{B: Unpack the distribution}}

 
 

-.Pick a directory for the LDAP source to live under and change
-directory there, and untar it. For example:
+.Pick a directory for the LDAP source to live under, change
+directory to there, and unpack the distribution using the
+following commands:

 
 

-..{{EX:cd /usr/local/src}}
-..{{EX:gunzip -c openldap-release.tgz | tar xvfB -}}
-..{{EX:cd openldap-release}}
+..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}}

 
 

-. You'll have to replace {{F:openldap-release}} with the full
+. then relocate yourself into the distribution directory:
+
+..{{EX:cd openldap-VERSION}}
+
+. You'll have to replace {{F:VERSION}} with the version

 name of the release.
 
 
 .{{S: }}
 name of the release.
 
 
 .{{S: }}

-+{{B: Configure the software}}.
++{{B: Review documentation}}

 
 

-.You will need to run the {{EX:configure}} script to configure slapd.
+. You should now review the {{F:COPYRIGHT}}, {{F:LICENSE}},
+{{F:README}} and {{F:INSTALL}} documents provided with the distribution.
+The {{F:COPYRIGHT}} and {{F:LICENSE}} provide information on
+acceptable use, copying, and limitation of warranty of OpenLDAP
+software. 
+
+.{{S: }}
+. You should also review other chapters of this document.
+In particular, the {{SECT:Building and Installing OpenLDAP Software}}
+chapter of this document provides detailed information on prerequisite
+software and installation procedures.

 
 

-..{{EX:./configure}}

 
 

-. The {{EX:configure}} accepts many command line options that enable
-or disable optional software features.  Usually the defaults are okay,
+.{{S: }}
++{{B: Run {{EX:configure}}}}
+
+. You will need to run the provided {{EX:configure}} script to
+{{configure}} to the distribution for building on your system.  The
+{{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
 but you may want to change them.  To get a complete list of options

-that {{EX:configure}} accepts, use the {{EX:--help}} option.
+that {{EX:configure}} accepts, use the {{EX:--help}} option:

 
 ..{{EX:./configure --help}}
 
 
 ..{{EX:./configure --help}}
 

-. Once OpenLDAP has been configured, it needs to be compiled.  
-You'll need to construct dependencies and then compile the software
-using {{make}}(1) utility.
-For example:
+. However, given that you using this guide, we'll assume you'll
+are brave enough to just let {{EX:configure}} to determine
+what's best:
+
+..{{EX:./configure}}
+
+. Assuming {{EX:configure}} doesn't dislike your system, you can
+proceed with building the software.  If {{EX:configure}} did
+complain, well, you'll likely need to go to the FAQ Installation
+Section ({{URL:http://www.openldap.org/faq/}} and/or actually
+read the {{SECT:Building and Installing OpenLDAP Software}}
+chapter of this document.
+
+
+.{{S: }}
++{{B:Build the software}}.
+
+. The next step is to build the software.  This step has two
+parts, first we construct dependencies and then we compile the
+software:

 
 ..{{EX:make depend}}
 ..{{EX:make}}
 
 
 ..{{EX:make depend}}
 ..{{EX:make}}
 

-. Once OpenLDAP is compiled you need to install it.  By default OpenLDAP 
-is installed into {{F:/usr/local}}.  This is typically done as root.

 
 

-..{{EX:su root -c 'make install'}}
+. Both makes should complete without error.

 
 
 .{{S: }}
 
 
 .{{S: }}

-+{{B:Edit the configuration file}}.
++{{B:Test the build}}.

 
 

-.Use this chapter as a brief tutorial.  For more details on the
-configuration file, see slapd.conf(5) and chapter 5.
+. To ensure a correct build, you should run the test suite
+(it only takes a few minutes):

 
 

-.Now we need to edit the default configuration file that was
-installed earlier.  The {{slapd}} configuration file {{slapd.conf}}(5)
-for is normally located at {{F:/usr/local/etc/openldap/slapd.conf}}.
-If you specified the {{EX:--prefix}} option when you ran {{EX:configure}},
-then replace {{F:/usr/local}} with the value you gave as the
-prefix.  For example, if you ran {{EX:configure}} as
+..{{EX:make test}}

 
 

-..{{EX:./configure --prefix=/opt/ldap}}
+. Tests which apply to your configuration will run and they
+should pass.  Some tests, such as the replication test, may
+be skipped.

 
 

-.You would find your configuration file in
-{{F:/opt/ldap/etc/openldap/slapd.conf}}. 
-Now look in the configuration file for a line that begins with 

 
 

-..{{EX:database          ldbm}}
+.{{S: }}
++{{B:Install the software}}.

 
 

-.This marks the begining of the database configuration for {{slapd}}.
-Everything you will need to change for this example is located
-after this line.
+. You are now ready to install the software, this usually requires
+{{super-user}} privledges: 

 
 

-.Listed below are the default settings for the database in
-{{F:slapd.conf}}(5).  Lines that begin with a sharp sign ('{{EX:#}}')
-are considered to be comments by slapd, they have been removed
-from the listing below to save space.  If a line starts with
-white space it is considered a continuation of the preceeding
-line.
+..{{EX:su root -c 'make install'}}

 
 

-..{{EX:suffix          "dc=my-domain, dc=com"}}
-..{{EX:rootdn          "cn=Manager, dc=my-domain, dc=com"}}
+. Everything should now be installed under {{F:/usr/local}} (or
+whatever installation prefix was used by {{EX:configure}}.
+
+
+.{{S: }}
++{{B:Edit the configuration file}}.
+
+. Use your favorite editor to edit the provided {{slapd.conf}}(5)
+example (usually installed as {{F:/usr/local/etc/openldap/slapd.conf}})
+to contain an LDBM database definition of the form:
+
+..{{EX:database        ldbm}}
+..{{EX:suffix          "dc=<MY-DOMAIN>,dc=<COM>"}}
+..{{EX:rootdn          "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>"}}

 ..{{EX:rootpw          secret}}
 ..{{EX:directory       /usr/local/var/openldap-ldbm}}
 
 ..{{EX:rootpw          secret}}
 ..{{EX:directory       /usr/local/var/openldap-ldbm}}
 

-. Now we need to replace all of the references to {{EX:my-domain}}
-and {{EX:com}} with the correct value.  For example, if your domain
-is {{EX:example.net}} we might use the following.
+. Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with
+the appropriate domain components of your domain name.  For
+example, for {{EX:example.com}}, use:

 
 

-..{{EX:suffix          "dc=example, dc=net"}}
-..{{EX:rootdn          "cn=Manager, dc=example, dc=net"}}
+..{{EX:database        ldbm}}
+..{{EX:suffix          "dc=example,dc=com"}}
+..{{EX:rootdn          "cn=Manager,dc=example,dc=com"}}

 ..{{EX:rootpw          secret}}
 ..{{EX:directory       /usr/local/var/openldap-ldbm}}
 
 ..{{EX:rootpw          secret}}
 ..{{EX:directory       /usr/local/var/openldap-ldbm}}
 

-. By default, the database files will be created in
-{{F:/usr/local/var/openldap-ldbm}}.
-You may specify an alternate directory via the directory option
-in the {{F:slapd.conf}} file.  The directory must exist before
-you start the server.
+.If your domain contains additional components, such as
+{{EX:eng.uni.edu.eu}}, use:

 
 

-Note: Use of rootpw is deprecated in favor of strong authentication
-mechanisms.  These are described in later chapters.
+..{{EX:database        ldbm}}
+..{{EX:suffix          "dc=eng,dc=uni,dc=edu,dc=eu"}}
+..{{EX:rootdn          "cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu"}}
+..{{EX:rootpw          secret}}
+..{{EX:directory       /usr/local/var/openldap-ldbm}}
+
+. Details regarding configuring {{slapd}}(8) can be found
+in the {{slapd.conf}}(5) manual page and the
+{{SECT:The slapd Configuration File}} chapter of this
+document.

 
 .{{S: }}
 
 .{{S: }}

-+{{B:Starting the server}}.
++{{B:Start SLAPD}}.
+
+. You are now ready to start the stand-alone LDAP server, slapd(8),
+by running the command:

 
 

-.You are now ready to start the server by running the command
-{{slapd}}(8):
+..{{EX:su root -c /usr/local/libexec/slapd}}

 
 

-..{{EX:/usr/local/libexec/slapd}}

 
 

-. 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
-installed as {{F:/usr/local/bin/ldapsearch}}.
+. To check to see if the server is running and configured correctly,
+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
 
 ..{{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:dn:}}

-..{{EX:namingContexts: dc=example, dc=net}}
+..{{EX:namingContexts: dc=example,dc=com}}
+
+. Details regarding running {{slapd}}(8) can be found
+in the {{slapd}}(8) manual page and the
+{{SECT:Running slapd}} chapter of this document.

 
 
 .{{S: }}
 
 
 .{{S: }}

-+{{B:Create a database}}.
++{{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 in two steps:
+
+^^ create an LDIF file
+++ run ldapadd

 
 

-. 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.
+. Use your favorite editor and create an LDIF file that contains:

 
 

-..{{EX:dn: dc=example, dc=net}}
+..{{EX:dn: dc=<MY-DOMAIN>,dc=<COM>}}
+..{{EX:objectclass: dcObject}}
+..{{EX:objectclass: organization}}
+..{{EX:o: <MY ORGANIZATION>}}
+..{{EX:dc: <MY-DOMAIN>}}
+..{{EX:}}
+..{{EX:dn: cn=Manager,dc=<MY-DOMAIN>,dc=<COM>}}
+..{{EX:objectclass: organizationalRole}}
+..{{EX:cn: Manager}}
+
+. Be sure to replace <MY-DOMAIN> and <COM> with the appropriate domain
+components of your domain name.  <MY ORGANIZATION> should be replaced
+with the name of your organization.  If you cut and paste, be sure
+to trim any leading and trailing whitespace from the example.
+
+..{{EX:dn: dc=example,dc=com}}

 ..{{EX:objectclass: dcObject}}
 ..{{EX:objectclass: organization}}
 ..{{EX:objectclass: dcObject}}
 ..{{EX:objectclass: organization}}

-..{{EX:o: Example Network}}
+..{{EX:o: Example Company}}

 ..{{EX:dc: example}}
 ..{{EX:dc: example}}

-..{{EX: }}
-..{{EX:dn: cn=Bob Smith, dc=example, dc=net}}
-..{{EX:objectclass: person}}
-..{{EX:cn: Bob Smith}}
-..{{EX:sn: Smith}}
-
-.Remember to replace {{EX:dc=example, dc=net}} with the correct
-values for your site, and to put your name instead of Bob's.  You can
-include additional entries and attributes in this file if you want,
-or add them later via LDAP.
+..{{EX:}}
+..{{EX:dn: cn=Manager,dc=example,dc=com}}
+..{{EX:objectclass: organizationalRole}}
+..{{EX:cn: Manager}}

 
 

-.The second step is to run a tool to add the contents of this file to the
-your directory.  We use the tool {{ldapadd}}(1) to populate the directory.
-Again remember to replace {{EX:dc=example, dc=net}} with the correct values
-for your site.  By default ldapadd is installed as
-{{F:/usr/local/bin/ldapadd}}.
+. Now, you may run {{ldapadd}}(1) to insert these entries into
+your directory.

 
 

-..{{EX:ldapadd -x -D 'cn=Manager,dc=example,dc=net' -w secret -f example.ldif}}
+..{{EX:ldapadd -x -D "cn=Manager,dc=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}}

 
 

-.Where {{F:example.ldif}} is the file you created above.
+. Be sure to replace {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the
+appropriate domain components of your domain name.  You will be
+prompted for the "{{EX:secret}}" specified in {{F:slapd.conf}}. 
+For example, for {{EX:example.com}}, use:

 
 

-Note: Use of transport security services is recommended when updating
-the directory.  These services are described in later chapters.
+..{{EX:ldapadd -x -D "cn=Manager,dc=example,dc=com" -W -f example.ldif}}

 
 

+. where {{F:example.ldif}} is the file you created above.
+..{{EX: }}
+. Additional informaton regarding directory creation can be found
+in the {{SECT:Database Creation and Maintenance Tools}} chapter of
+this document.

 
 .{{S: }}
 +{{B:See if it works}}.
 
 
 .{{S: }}
 +{{B:See if it works}}.
 

-.Now we're ready to verify the added entries are in your directory.  
+. Now we're ready to verify the added entries are in your directory.  

 You can use any LDAP client to do this, but our example uses the
 You can use any LDAP client to do this, but our example uses the

-{{ldapsearch}}(1) tool.  Remember to replace {{EX:dc=example,dc=net}}
-with the correct values for your site.
+{{ldapsearch}}(1) tool.  Remember to replace {{EX:dc=example,dc=com}}
+with the correct values for your site:

 
 

-..{{EX:ldapsearch -x -b 'dc=example,dc=net' '(objectclass=*)'}}
+..{{EX:ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'}}

 
 

-.This command will search for and retrieve every entry in the database.
+. This command will search for and retrieve every entry in the database.

 
 You are now ready to add more entries using {{ldapadd}}(1) or
 another LDAP client, experiment with various configuration options,
 
 You are now ready to add more entries using {{ldapadd}}(1) or
 another LDAP client, experiment with various configuration options,

-backend arrangements, etc. Note that by default, the {{slapd}}(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.
+backend arrangements, etc.
+
+Note that by default, the {{slapd}}(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 the {{SECT:Access Control}} section
+of the {{SECT:The slapd Configuration File}} chapter.  You are also
+encouraged to read {{SECT:Security Considerations}}, {{SECT:Using
+SASL}} and {{SECT:Using TLS}} sections.

 
 The following chapters provide more detailed information on making,
 installing, and running {{slapd}}(8).
 
 The following chapters provide more detailed information on making,
 installing, and running {{slapd}}(8).

-