diff options
Diffstat (limited to 'doc/guide/admin/quickstart.sdf')
| -rw-r--r-- | doc/guide/admin/quickstart.sdf | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/guide/admin/quickstart.sdf b/doc/guide/admin/quickstart.sdf new file mode 100644 index 0000000..047d8a9 --- /dev/null +++ b/doc/guide/admin/quickstart.sdf @@ -0,0 +1,300 @@ +# $OpenLDAP$ +# Copyright 1999-2022 The OpenLDAP Foundation, All Rights Reserved. +# COPYING RESTRICTIONS APPLY, see COPYRIGHT. + +H1: A Quick-Start Guide + +The following is a quick start guide to [[DOC_NAME]], +including the Standalone {{TERM:LDAP}} Daemon, {{slapd}}(8). + +It is meant to walk you through the basic steps needed to install +and configure {{PRD: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 {{PRD:OpenLDAP}} web site +({{URL: http://www.OpenLDAP.org}}), in particular the OpenLDAP +Software {{TERM:FAQ}} ({{URL: http://www.OpenLDAP.org/faq/?file=2}}). + +If you intend to run OpenLDAP Software seriously, you should review +all of this document before attempting 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. + + +.{{S: }} +^{{B: Get the software}} + +. You can obtain a copy of the software by following the +instructions on the OpenLDAP Software 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}} + +.Pick a directory for the source to live under, change +directory to there, and unpack the distribution using the +following commands: + +..{{EX:gunzip -c openldap-VERSION.tgz | tar xvfB -}} + +. 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: Review documentation}} + +. 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. + + +.{{S: }} ++{{B: Run {{EX:configure}}}} + +. You will need to run the provided {{EX:configure}} script to +{{configure}} 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: + +..{{EX:./configure --help}} + +. However, given that you are using this guide, we'll assume you +are brave enough to just let {{EX:configure}} 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 Software FAQ +{{Installation}} section ({{URL:http://www.openldap.org/faq/?file=8}}) +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}} + + +. Both makes should complete without error. + + +.{{S: }} ++{{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. + + +.{{S: }} ++{{B:Install the software}}. + +. You are now ready to install the software; this usually requires +{{super-user}} privileges: + +..{{EX:su root -c 'make install'}} + +. 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.ldif}} +example (usually installed as {{F:/usr/local/etc/openldap/slapd.ldif}}) +to contain a MDB database definition of the form: + +..{{EX:dn: olcDatabase=mdb,cn=config}} +..{{EX:objectClass: olcDatabaseConfig}} +..{{EX:objectClass: olcMdbConfig}} +..{{EX:olcDatabase: mdb}} +..{{EX:OlcDbMaxSize: 1073741824}} +..{{EX:olcSuffix: dc=<MY-DOMAIN>,dc=<COM>}} +..{{EX:olcRootDN: cn=Manager,dc=<MY-DOMAIN>,dc=<COM>}} +..{{EX:olcRootPW: secret}} +..{{EX:olcDbDirectory: /usr/local/var/openldap-data}} +..{{EX:olcDbIndex: objectClass eq}} + +. 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:dn: olcDatabase=mdb,cn=config}} +..{{EX:objectClass: olcDatabaseConfig}} +..{{EX:objectClass: olcMdbConfig}} +..{{EX:olcDatabase: mdb}} +..{{EX:OlcDbMaxSize: 1073741824}} +..{{EX:olcSuffix: dc=example,dc=com}} +..{{EX:olcRootDN: cn=Manager,dc=example,dc=com}} +..{{EX:olcRootPW: secret}} +..{{EX:olcDbDirectory: /usr/local/var/openldap-data}} +..{{EX:olcDbIndex: objectClass eq}} + +.If your domain contains additional components, such as +{{EX:eng.uni.edu.eu}}, use: + +..{{EX:dn: olcDatabase=mdb,cn=config}} +..{{EX:objectClass: olcDatabaseConfig}} +..{{EX:objectClass: olcMdbConfig}} +..{{EX:olcDatabase: mdb}} +..{{EX:OlcDbMaxSize: 1073741824}} +..{{EX:olcSuffix: dc=eng,dc=uni,dc=edu,dc=eu}} +..{{EX:olcRootDN: cn=Manager,dc=eng,dc=uni,dc=edu,dc=eu}} +..{{EX:olcRootPW: secret}} +..{{EX:olcDbDirectory: /usr/local/var/openldap-data}} +..{{EX:olcDbIndex: objectClass eq}} + +. Details regarding configuring {{slapd}}(8) can be found +in the {{slapd-config}}(5) manual page and the {{SECT:Configuring +slapd}} chapter of this document. Note that the +specified olcDbDirectory must exist prior to starting {{slapd}}(8). + + +.{{S: }} ++{{B:Import the configuration database}} +. You are now ready to import your configuration database for use by +{{slapd}}(8), by running the command: + +..{{EX: su root -c /usr/local/sbin/slapadd -n 0 -F /usr/local/etc/slapd.d -l /usr/local/etc/openldap/slapd.ldif}} + +.{{S: }} ++{{B:Start SLAPD}}. + +. You are now ready to start the Standalone LDAP Daemon, {{slapd}}(8), +by running the command: + +..{{EX:su root -c /usr/local/libexec/slapd -F /usr/local/etc/slapd.d}} + + +. 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. + + +.{{S: }} ++{{B:Add initial entries to your directory}}. + +. You can use {{ldapadd}}(1) to add entries to your LDAP directory. +{{ldapadd}} expects input in {{TERM: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=<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 {{EX:<MY-DOMAIN>}} and {{EX:<COM>}} with the +appropriate domain components of your domain name. {{EX:<MY +ORGANIZATION>}} should be replaced with the name of your organization. +When 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=<MY-DOMAIN>,dc=<COM>" -W -f example.ldif}} + +. 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: + +..{{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 information 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}} chapter. +You are also encouraged to read the {{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). |