external/bsd/openldap/dist/doc/guide/admin/runningslapd.sdf

   1 # $OpenLDAP: pkg/openldap-guide/admin/runningslapd.sdf,v 1.16.2.5 2008/02/11 23:26:39 kurt Exp $
   2 # Copyright 1999-2008 The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4 H1: Running slapd
   5
   6 {{slapd}}(8) is designed to be run as a standalone service.  This
   7 allows the server to take advantage of caching, manage concurrency
   8 issues with underlying databases, and conserve system resources.
   9 Running from {{inetd}}(8) is {{NOT}} an option.
  10
  11
  12 H2: Command-Line Options
  13
  14 {{slapd}}(8) supports a number of command-line options as detailed
  15 in the manual page.  This section details a few commonly used options.
  16
  17 >       -f <filename>
  18
  19 This option specifies an alternate configuration file for slapd.
  20 The default is normally {{F:/usr/local/etc/openldap/slapd.conf}}.
  21
  22 >       -F <slapd-config-directory>
  23
  24 Specifies the slapd configuration directory. The default is {{F:/usr/local/etc/openldap/slapd.d}}
  25
  26 If both {{EX:-f}} and {{EX:-F}} are specified, the config file will be read and converted
  27 to config directory format and written to the specified directory.
  28 If neither option is specified, slapd will attempt to read the default config
  29 directory before trying to use the default config file. If a valid config
  30 directory exists then the default config file is ignored. All of the slap tools
  31 that use the config options observe this same behavior.
  32
  33 >       -h <URLs>
  34
  35 This option specifies alternative listener configurations.  The
  36 default is {{EX:ldap:///}} which implies {{TERM:LDAP}} over
  37 {{TERM:TCP}} on all interfaces on the default LDAP port 389.  You
  38 can specify specific host-port pairs or other protocol schemes (such
  39 as {{EX:ldaps://}} or {{EX:ldapi://}}).  For example, {{EX:-h
  40 "ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one
  41 for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on
  42 the default {{EX:ldaps://}} port 636, and one for the standard
  43 {{EX:ldap://}} scheme on the {{EX:localhost}} ({{loopback}}) interface
  44 on port 666.  Hosts may be specified using using hostnames or
  45 {{TERM:IPv4}} or {{TERM:IPv6}} addresses.  Port values must be
  46 numeric.
  47
  48 >       -n <service-name>
  49
  50 This option specifies the service name used for logging and
  51 other purposes. The default service name is {{EX:slapd}}.
  52
  53 >       -l <syslog-local-user>
  54
  55 This option specifies the local user for the {{syslog}}(8)
  56 facility.  Values can be {{EX:LOCAL0}}, {{EX:LOCAL1}}, {{EX:LOCAL2}}, ...,
  57 and {{EX:LOCAL7}}.  The default is {{EX:LOCAL4}}.  This option
  58 may not be supported on all systems.
  59
  60 >       -u user -g group
  61
  62 These options specify the user and group, respectively, to run
  63 as.  {{EX:user}} can be either a user name or uid.  {{EX:group}}
  64 can be either a group name or gid.
  65
  66 >       -r directory
  67
  68 This option specifies a run-time directory.  slapd will
  69 {{chroot}}(2) to this directory after opening listeners but
  70 before reading any configuration files or initializing
  71 any backends.
  72 .
  73
  74 >       -d <level> | ?
  75
  76 This option sets the slapd debug level to <level>. When level is a
  77 `?' character, the various debugging levels are printed and slapd
  78 exits, regardless of any other options you give it. Current
  79 debugging levels are
  80
  81 !block table; colaligns="RL"; align=Center; \
  82         title="Table 7.1: Debugging Levels"
  83 Level   Description
  84 -1      enable all debugging
  85 0       no debugging
  86 1       trace function calls
  87 2       debug packet handling
  88 4       heavy trace debugging
  89 8       connection management
  90 16      print out packets sent and received
  91 32      search filter processing
  92 64      configuration file processing
  93 128     access control list processing
  94 256     stats log connections/operations/results
  95 512     stats log entries sent
  96 1024    print communication with shell backends
  97 2048    print entry parsing debugging
  98 !endblock
  99
 100 You may enable multiple levels by specifying the debug option
 101 once for each desired level.  Or, since debugging levels are
 102 additive, you can do the math yourself. That is, if you want
 103 to trace function calls and watch the config file being
 104 processed, you could set level to the sum of those two levels
 105 (in this case, {{EX: -d 65}}).  Or, you can let slapd do the
 106 math, (e.g. {{EX: -d 1 -d 64}}).  Consult {{F: <ldap_log.h>}} for
 107 more details.
 108
 109 Note: slapd must have been compiled with {{EX:-DLDAP_DEBUG}}
 110 defined for any debugging information beyond the two stats levels
 111 to be available.
 112
 113
 114 H2: Starting slapd
 115
 116 In general, slapd is run like this:
 117
 118 >       /usr/local/libexec/slapd [<option>]*
 119
 120 where {{F:/usr/local/libexec}} is determined by {{EX:configure}}
 121 and <option> is one of the options described above (or in {{slapd}}(8)).
 122 Unless you have specified a debugging level (including level {{EX:0}}),
 123 slapd will automatically fork and detach itself from its controlling
 124 terminal and run in the background.
 125
 126 H2: Stopping slapd
 127
 128 To kill off {{slapd}}(8) safely, you should give a command like this
 129
 130 >       kill -INT `cat /usr/local/var/slapd.pid`
 131
 132 where {{F:/usr/local/var}} is determined by {{EX:configure}}.
 133
 134 Killing slapd by a more drastic method may cause information loss or
 135 database corruption.