X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fquickstart.sdf;h=29c01a52ecd281318ce91a492a23f26aec152678;hb=50277c6abea63db90cf374b538215b4a63ae549e;hp=bac0729fea20659776bdb0e12a59d4bf57e94d24;hpb=9bf1190a20bae790de3ca9b8d43221b69e534d86;p=openldap diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf index bac0729fea..29c01a52ec 100644 --- a/doc/guide/admin/quickstart.sdf +++ b/doc/guide/admin/quickstart.sdf @@ -1,170 +1,277 @@ # $OpenLDAP$ -# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# Copyright 1999-2001, 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 section provides a quick step-by-step guide to building, -installing and running {{I:slapd}}. 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). -^ {{B:Get the software}}. -. {{I:Slapd}} is part of the OpenLDAP distribution, which -you can retrieve using this URL: +If you intend to run OpenLDAP seriously, you should review the all +of this document before attempt to install the software. -..{{URL: ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release.tgz}} +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. -.If you are reading this guide, you have probably already done this. +.{{S: }} +^{{B: Get the software}} -+ {{B:Untar the distribution}}. -.Pick a place for the LDAP source to live, cd -there, and untar it. For example: +. 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}}. -.{{EX:cd /usr/local/src}} -.{{EX:gunzip -c openldap-release.tgz | tar xvfB -}} -.{{EX:cd ldap}} -+ {{B: Configure the software}}. -. You will need to run the configure script to configure slapd. +.{{S: }} ++{{B: Unpack the distribution}} -.{{EX:./configure}} +.Pick a directory for the LDAP source to live under, change +directory to there, and unpack the distribution using the +following commands: -. Configure accepts many command line options that enable or disable -optional features in slapd. Usually the defaults are okay, but you -may want to change them. To get a complete list of options that configure -accepts, use the --help option. +..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}} -.{{EX:./configure --help}} +. then relocate yourself into the distribution directory: -. Once OpenLDAP has been configured, it needs to be compiled. -You'll need to make dependencies and then compile the software. -For example: +..{{EX:cd openldap-VERSION}} -.{{EX:make depend}} -.{{EX:make}} +. You'll have to replace {{F:VERSION}} with the version +name of the release. -. Once OpenLDAP is compiled you need to install it. By default OpenLDAP -is installed into /usr/local. This is typically done as root. -.{{EX:su root}} -.{{EX:make install}} +.{{S: }} ++{{B: Review documentation}} -+ {{B:Edit the configuration file}}. -. Use this section as a brief guide. For more details on the configuration -file, see chapter 5. +. 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. -. Now we need to edit the default configuration file that was installed -earlier. By default the configuration file for slapd is located at -{{FILE:/usr/local/etc/openldap/slapd.conf}}. If you specified the --prefix -option when you ran configure, then replace {{FILE:/usr/local}} with the -value you gave as the prefix. +.{{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. -. For example, if you ran configure as -.{{EX:./configure --prefix=/opt/ldap}} -. You would find your configuration file in {{FILE:/opt/ldap/etc/openldap/slapd.conf}}. -. Now look in the configuration file for a line that begins with -.{{EX:database ldbm}} +.{{S: }} ++{{B: Run {{EX:configure}}}} -. This marks the begining of the database configuration for slapd. Everything -you will need to change for this example is located after the line begining with -.{{EX:database ldbm}} +. 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 +that {{EX:configure}} accepts, use the {{EX:--help}} option: -. Listed below are the default settings for the database in {{FILE:slapd.conf}}. -Lines that begin with a # are considered to be comments by slapd, they have -been removed from the listing below to save space. +..{{EX:./configure --help}} -.{{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}} +. 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: -. Now we need to replace all of the references to my-domain with the correct -value. For example, if your domain is example.net we might use the following. +..{{EX:./configure}} -.{{EX:suffix "dc=example, dc=net"}} -.{{EX:rootdn "cn=Manager, dc=example, dc=net"}} -.{{EX:rootpw secret}} -.{{EX:directory /usr/local/var/openldap-ldbm}} +. 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. -+ {{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: dc=example, dc=net}} -.{{EX:objectclass: dcObject}} -.{{EX:objectclass: organization}} -.{{EX:o: Example Net Inc.}} -.{{EX:dc: example}} -. -.{{EX:dn: cn=Bob Smith, dc=example, dc=net}} -.{{EX:objectclass: person}} -.{{EX:cn: Bob Smith}} -.{{EX:sn: Smith}} +.{{S: }} ++{{B:Build the software}}. -.Remember to replace dc=example,dc=net with the correct values for your -site, and to put your name instead of Bob's. +. The next step is to build the software. This step has two +parts, first we construct dependencies and then we compile the +software: -.You can include additional entries and attributes in this file if you want, -or add them later via LDAP. +..{{EX:make depend}} +..{{EX:make}} -.Step B is to run this file through a tool to create the slapd database. -.First we'll need to start slapd. -To do this just run slapd. -.{{EX:/usr/local/libexec/slapd}} +. Both makes should complete without error. -.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 -{{I:ldapsearch}}(1). -By default ldapsearch is installed as {{FILE:/usr/local/bin/ldapsearch}}. -.{{EX:ldapsearch -x -b "" -s base '(objectclass=*)' namingContexts +.{{S: }} ++{{B:Test the build}}. -This should return: +. To ensure a correct build, you should run the test suite +(it only takes a few minutes): -.{{EX:dn:}} -.{{EX:namingContexts: dc=example, dc=net}} +..{{EX:make test}} -.We can use {{I:ldapadd}}(1) to populate the directory. -Again remember to replace dc=example,dc=net with the correct values for your -site. By default ldapadd is installed as {{FILE:/usr/local/bin/ldapadd}}. +. Tests which apply to your configuration will run and they +should pass. Some tests, such as the replication test, may +be skipped. -.{{EX:ldapadd -x -D"cn=Manager,dc=example,dc=net" -w secret -f myldif}} -.Where myldif is the file you made in step 7A above. By default, the database -files will be created in {{FILE:/usr/local/var/openldap-ldbm}}. -You may specify an alternate directory via the directory option in the -{{FILE:slapd.conf}} file. +.{{S: }} ++{{B:Install the software}}. -+ {{B:See if it works}}. -. Now we're ready to try everything out. +. You are now ready to install the software, this usually requires +{{super-user}} privledges: -. You can use any LDAP client to do this, but our -example uses the ldapsearch tool. Remember to replace dc=example,dc=net with -the correct values for your site. +..{{EX:su root -c 'make install'}} -.{{EX:ldapsearch -x -b 'dc=example,dc=net' '(objectclass=*)'}} +. Everything should now be installed under {{F:/usr/local}} (or +whatever installation prefix was used by {{EX:configure}}. -. 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}}(1) 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). +.{{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=,dc="}} +..{{EX:rootdn "cn=Manager,dc=,dc="}} +..{{EX:rootpw secret}} +..{{EX:directory /usr/local/var/openldap-ldbm}} + +. Be sure to replace {{EX:}} and {{EX:}} with +the appropriate domain components of your domain name. For +example, for {{EX:example.com}}, use: + +..{{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}} + +.If your domain contains additional components, such as +{{EX:eng.uni.edu.eu}}, use: + +..{{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:Start SLAPD}}. + +. You are now ready to start the stand-alone LDAP server, slapd(8), +by running the command: + +..{{EX:su root -c /usr/local/libexec/slapd}} + + +. 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 +special characters from being interpreted by the shell. This should return: + +..{{EX:dn:}} +..{{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. -The following sections provide more detailed information on making, -installing, and running slapd. +.{{S: }} ++{{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 + +. Use your favorite editor and create an LDIF file that contains: + +..{{EX:dn: dc=,dc=}} +..{{EX:objectclass: dcObject}} +..{{EX:objectclass: organization}} +..{{EX:o: }} +..{{EX:dc: }} +..{{EX:}} +..{{EX:dn: cn=Manager,dc=,dc=}} +..{{EX:objectclass: organizationalRole}} +..{{EX:cn: 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 and trailing 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=Manager,dc=example,dc=com}} +..{{EX:objectclass: organizationalRole}} +..{{EX:cn: Manager}} + +. Now, you may run {{ldapadd}}(1) to insert these entries into +your directory. + +..{{EX:ldapadd -x -D "cn=Manager,dc=,dc=" -W -f example.ldif}} + +. 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: + +..{{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. +You can use any LDAP client to do this, but our example uses the +{{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=com' '(objectclass=*)'}} + +. 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 {{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).