X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fquickstart.sdf;h=29c01a52ecd281318ce91a492a23f26aec152678;hb=50277c6abea63db90cf374b538215b4a63ae549e;hp=b102c54a98127c9becddbc7b11cb0a2263e01d75;hpb=e70eadc2c5ae0f8855ab3f27cd8fc57474bbc19f;p=openldap diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf index b102c54a98..29c01a52ec 100644 --- a/doc/guide/admin/quickstart.sdf +++ b/doc/guide/admin/quickstart.sdf @@ -1,209 +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 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: }} -+{{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: }} -+{{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 -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}}. -.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 beginning 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 preceding -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=,dc="}} +..{{EX:rootdn "cn=Manager,dc=,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 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=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 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=,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 Network}} +..{{EX:o: Example Company}} ..{{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=,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 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}}. -.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 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). -