# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Running slapd
-Slapd can be run in two different modes, stand-alone or from
-inetd(8). Stand-alone operation is recommended, especially if you
-are using the LDBM backend. This allows the backend to take
-advantage of caching and avoids concurrency problems with the
-LDBM index files. If you are running only a PASSWD or SHELL
-backend, running from inetd is an option. How to do this is
-described in the next section, after the command-line options and
-stand-alone daemon operation are described.
-
+{{slapd}}(8) is designed to be run as a standalone service. This
+allows the server to take advantage of caching, manage concurrency
+issues with underlying databases, and conserve system resources.
+Running from {{inetd}}(8) is {{NOT}} an option.
H2: Command-Line Options
-{{I:Slapd}} supports the following command-line options.
+{{slapd}}(8) supports a number of command-line options as detailed
+in the manual page. This section details a few commonly used options.
-E: -d <level> | ?
+> -f <filename>
-This option sets the slapd debug level to <level>. When level is a
-`?' character, the various debugging levels are printed and slapd
-exits, regardless of any other options you give it. Current
-debugging levels are
+This option specifies an alternate configuration file for slapd.
+The default is normally {{F:/usr/local/etc/openldap/slapd.conf}}.
-E: 1 trace function calls
-E: 2 debug packet handling
-E: 4 heavy trace debugging
-E: 8 connection management
-E: 16 print out packets sent and received
-E: 32 search filter processing
-E: 64 configuration file processing
-E: 128 access control list processing
-E: 256 stats log connections/operations/results
-E: 512 stats log entries sent
-E: 1024 print communication with shell backends
-E: 2048 print entry parsing debugging
-E: 65535 enable all debugging
-
-Debugging levels are additive. That is, if you want to trace function
-calls and watch the config file being processed, you would set
-level to the sum of those two levels (in this case, 65). Consult
-{{EX: <ldap.h>}} for more details.
-
-Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}}
-defined for any debugging information beyond the two stats levels
-to be available.
+> -F <slapd-config-directory>
-E: -f <filename>
+Specifies the slapd configuration directory. The default is {{F:/usr/local/etc/openldap/slapd.d}}.
-This option specifies an alternate configuration file for slapd.
+If both {{EX:-f}} and {{EX:-F}} are specified, the config file will be read and converted
+to config directory format and written to the specified directory.
+If neither option is specified, slapd will attempt to read the default config
+directory before trying to use the default config file. If a valid config
+directory exists then the default config file is ignored. All of the slap tools
+that use the config options observe this same behavior.
-E: -i
+> -h <URLs>
-This option tells slapd that it is running from inetd instead of as a
-stand-alone server. See the next section on running slapd from
-inetd for more details.
+This option specifies alternative listener configurations. The
+default is {{EX:ldap:///}} which implies {{TERM:LDAP}} over
+{{TERM:TCP}} on all interfaces on the default LDAP port 389. You
+can specify specific host-port pairs or other protocol schemes (such
+as {{EX:ldaps://}} or {{EX:ldapi://}}).
-E: -p <port>
+!block table
+URL Protocol Transport
+ldap:/// LDAP TCP port 389
+ldaps:/// LDAP over SSL TCP port 636
+ldapi:/// LDAP IPC (Unix-domain socket)
+!endblock
-This option specifies an alternate TCP port on which slapd should
-listen for connections. The default port is 389.
+For example, {{EX:-h
+"ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one
+for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on
+the default {{EX:ldaps://}} port 636, and one for the standard
+{{EX:ldap://}} scheme on the {{EX:localhost}} ({{loopback}}) interface
+on port 666. Hosts may be specified using using hostnames or
+{{TERM:IPv4}} or {{TERM:IPv6}} addresses. Port values must be
+numeric.
+For LDAP over IPC, the pathname of the Unix-domain socket can be encoded
+in the URL. Note that directory separators must be
+URL-encoded, like any other characters that are special to URLs.
+Thus the socket {{EX:/usr/local/var/ldapi}} must be encoded as
+> ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
-H2: Running slapd as a Stand-Alone Daemon
+ldapi: is described in detail in {{Using LDAP Over IPC Mechanisms}} [{{REF:Chu-LDAPI}}]
-In general, slapd is run like this:
+Note that the ldapi:/// transport is not widely implemented: non-OpenLDAP clients
+may not be able to use it.
+
+> -n <service-name>
-E: $(ETCDIR)/slapd [<option>]*
+This option specifies the service name used for logging and
+other purposes. The default service name is {{EX:slapd}}.
-where ETCDIR has the value you gave in the Make-common file
-during the pre-build configuration, and <option> is one of the
-options described below. Unless you have specified a debugging
-level, slapd will automatically fork and detach itself from its
-controlling terminal and run in the background. Any of the options
-given above can be given to slapd to point it at a different
-configuration file, listen on another port, etc.
+> -l <syslog-local-user>
-To kill off slapd safely, you should give a command like this
+This option specifies the local user for the {{syslog}}(8)
+facility. Values can be {{EX:LOCAL0}}, {{EX:LOCAL1}}, {{EX:LOCAL2}}, ...,
+and {{EX:LOCAL7}}. The default is {{EX:LOCAL4}}. This option
+may not be supported on all systems.
-E: kill -TERM `cat $(ETCDIR)/slapd.pid`
+> -u user -g group
-Killing slapd by a more drastic method may cause its LDBM
-databases to be corrupted, as it may need to flush various buffers
-before it exits. Note that slapd writes its pid to a file called
-{{EX: slapd.pid}} in the {{EX: ETCDIR}} you configured in
-{{EX: Make-common}}. You can change
-the location of this pid file by changing the {{EX: SLAPD_PIDFILE}}
-variable in {{EX: include/ldapconfig.h.edit}}.
+These options specify the user and group, respectively, to run
+as. {{EX:user}} can be either a user name or uid. {{EX:group}}
+can be either a group name or gid.
-{{I: Slapd}} will also write its arguments to a file called
-{{EX: slapd.args}} in the {{EX: ETCDIR}} you configured
-in {{EX: Make-common}}. You can change the
-location of the args file by changing the {{EX: SLAPD_ARGSFILE}}
-variable in {{EX: include/ldapconfig.h.edit}}.
+> -r directory
+This option specifies a run-time directory. slapd will
+{{chroot}}(2) to this directory after opening listeners but
+before reading any configuration files or initializing
+any backends.
+.
+> -d <level> | ?
-H2: Running slapd from inetd
+This option sets the slapd debug level to <level>. When level is a
+`?' character, the various debugging levels are printed and slapd
+exits, regardless of any other options you give it. Current
+debugging levels are
+
+!block table; colaligns="RL"; align=Center; \
+ title="Table 7.1: Debugging Levels"
+Level Keyword Description
+-1 any enable all debugging
+0 no debugging
+1 (0x1 trace) trace function calls
+2 (0x2 packets) debug packet handling
+4 (0x4 args) heavy trace debugging
+8 (0x8 conns) connection management
+16 (0x10 BER) print out packets sent and received
+32 (0x20 filter) search filter processing
+64 (0x40 config) configuration processing
+128 (0x80 ACL) access control list processing
+256 (0x100 stats) stats log connections/operations/results
+512 (0x200 stats2) stats log entries sent
+1024 (0x400 shell) print communication with shell backends
+2048 (0x800 parse) print entry parsing debugging
+16384 (0x4000 sync) syncrepl consumer processing
+32768 (0x8000 none) only messages that get logged whatever log level is set
+!endblock
+
+You may enable multiple levels by specifying the debug option once for each desired level. Or, since debugging levels are additive, you can do the math yourself. That is, if you want to trace function calls and watch the config file being processed, you could set level to the sum of those two levels (in this case, {{EX: -d 65}}). Or, you can let slapd do the math, (e.g. {{EX: -d 1 -d 64}}). Consult {{F: <ldap_log.h>}} for more details.
+
+Note: slapd must have been compiled with {{EX:--enable-debug}}
+defined for any debugging information beyond the two stats levels
+to be available (the default).
+
+
+H2: Starting slapd
+
+In general, slapd is run like this:
-First, make sure that running from {{I: inetd}}(8) is a good idea. If you
-are using the LDBM backend, it is not. If you are in a high-volume
-environment, the overhead of running from inetd also makes it a
-bad idea. Otherwise, you may proceed with the two steps
-necessary.
+> /usr/local/libexec/slapd [<option>]*
-Step 1 is to add a line like this to your {{EX: /etc/services}} file:
+where {{F:/usr/local/libexec}} is determined by {{EX:configure}}
+and <option> is one of the options described above (or in {{slapd}}(8)).
+Unless you have specified a debugging level (including level {{EX:0}}),
+slapd will automatically fork and detach itself from its controlling
+terminal and run in the background.
-E: ldap 389 # ldap directory service
+H2: Stopping slapd
-Step 2 is to add a line like this to your /etc/inetd.conf file:
+To kill off {{slapd}}(8) safely, you should give a command like this
-E: ldap stream tcp nowait nobody $(ETCDIR)/slapd slapd -i
+> kill -INT `cat /usr/local/var/slapd.pid`
-where {{EX: ETCDIR}} has the value you gave it in the
-{{EX: Make-common}} file
-during pre-build configuration. Finally, send inetd a HUP signal,
-and you should be all set.
+where {{F:/usr/local/var}} is determined by {{EX:configure}}.
+Killing slapd by a more drastic method may cause information loss or
+database corruption.
projects / openldap / blobdiff