From 3c82fc8025886821f67c7245fe5937f46caeb821 Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Fri, 11 Aug 2000 08:17:34 +0000 Subject: [PATCH] Align with current quick start guide --- doc/guide/admin/quickstart.sdf | 297 ++++++++++++++++++++------------- 1 file changed, 179 insertions(+), 118 deletions(-) diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf index 6d81197d2a..b7c47971be 100644 --- a/doc/guide/admin/quickstart.sdf +++ b/doc/guide/admin/quickstart.sdf @@ -2,138 +2,179 @@ # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. # 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 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. +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 privacy and integrity 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 either the (latest) +{{release}} or the (most) {{stable}} release. + .{{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.tgz}} + +. You'll have to replace {{F:VERSION}} with the version name of the release. .{{S: }} -+{{B: Configure the software}}. ++{{B: Review the release documents}} -.You will need to run the {{EX:configure}} script to configure slapd. +. You should 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. The {{F:README}} and {{F:INSTALL}} documents provide +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}} 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. +that {{EX:configure}} accepts, use the {{EX:--help}} option: ..{{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}} -. 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: }} -+{{B:Edit the configuration file}}. ++{{B:Test the build}}. + +. To ensure a correct build, you should run the test suite +(it only takes a few minutes): + +..{{EX:make test}} + +. Tests which apply to your configuration will run and they +should pass. Some tests, such as the replication test, may +be skipped. + -.Use this chapter as a brief tutorial. For more details on the -configuration file, see slapd.conf(5) and the -{{SECT:The slapd Configuration File}} chapter of this document. +.{{S: }} ++{{B:Install the software}}. -.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 +. You are now ready to install the software, this usually requires +{{super-user}} privledges: -..{{EX:./configure --prefix=/opt/ldap}} +..{{EX:su root -c 'make install'}} -.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 +. Everything should now be installed under {{F:/usr/local}} (or +whatever installation prefix was used by {{EX:configure}}. -..{{EX:database ldbm}} -.This marks the beginning of the database configuration for {{slapd}}. -Everything you will need to change for this example is located -after this line. +.{{S: }} ++{{B:Edit the configuration file}}. -.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 preceding -line. +. Use your favorite editor to edit the provided {{slapd.conf}}(5) +example (usually installed as {{F:/usr/local/etc/slapd.conf}}) to +contain an LDBM database definition of the form: -..{{EX:suffix "dc=my-domain, dc=com"}} -..{{EX:rootdn "cn=Manager, dc=my-domain, dc=com"}} +..{{EX:database ldbm}} +..{{EX:suffix "dc=, dc="}} +..{{EX:rootdn "cn=Manager, dc="}} ..{{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:}} and {{EX:}} 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}} -. 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: }} -+{{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 search it with {{ldapsearch}}(1). By default, ldapsearch +is installed as {{F:/usr/local/bin/ldapsearch}}: ..{{EX:ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts}} @@ -141,71 +182,91 @@ installed as {{F:/usr/local/bin/ldapsearch}}. special characters from interpreted by the shell. This should return: ..{{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: }} -+{{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 two steps: + +^^ create 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 {{Database Creation and Maintenance Tools}} section -of this document for more details. +. Use your favorite editor and create an LDIF file that contains: -..{{EX:dn: dc=example, dc=net}} +..{{EX:dn: dc=, dc=}} ..{{EX:objectclass: dcObject}} ..{{EX:objectclass: organization}} -..{{EX:o: Example Network}} +..{{EX:o: }} +..{{EX:dc: }} +..{{EX: }} +..{{EX:dn: cn=Manager, dc=, dc=}} +..{{EX:objectclass: person}} +..{{EX:cn: Manager}} +..{{EX:sn: Manager}} + +. Be sure to replace and with the appropriate domain +components of your domain name. should be replaced +with the name of your organization. If you cut and paste, be sure +to trim any leading whitespace from the example: + +..{{EX:dn: dc=example, dc=com}} +..{{EX:objectclass: dcObject}} +..{{EX:objectclass: organization}} +..{{EX:o: Example Company}} ..{{EX:dc: example}} ..{{EX: }} -..{{EX:dn: cn=Bob Smith, dc=example, dc=net}} +..{{EX:dn: cn=Bob Smith, dc=example, dc=com}} ..{{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. - -.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 -D "cn=Manager, dc=, dc=" -W -f example.ldif}} -.Where {{F:example.ldif}} is the file you created above. +. Be sure to replace {{EX:}} and {{EX:}} 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 strong authentication and transport security services -is highly 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}}. -.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 -{{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, -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 +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. The following chapters provide more detailed information on making, installing, and running {{slapd}}(8). - -- 2.39.5