git.sur5r.net Git - openldap/blob - doc/guide/admin/runningslapd.sdf

   1 # $OpenLDAP$
   2 # Copyright 1999-2015 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://}}).
  40
  41 !block table
  42 URL        Protocol        Transport
  43 ldap:///   LDAP            TCP port 389
  44 ldaps:///  LDAP over SSL   TCP port 636
  45 ldapi:///  LDAP            IPC (Unix-domain socket)
  46 !endblock
  47
  48 For example, {{EX:-h
  49 "ldaps:// ldap://127.0.0.1:666"}} will create two listeners: one
  50 for the (non-standard) {{EX:ldaps://}} scheme on all interfaces on
  51 the default {{EX:ldaps://}} port 636, and one for the standard
  52 {{EX:ldap://}} scheme on the {{EX:localhost}} ({{loopback}}) interface
  53 on port 666.  Hosts may be specified using using hostnames or
  54 {{TERM:IPv4}} or {{TERM:IPv6}} addresses.  Port values must be
  55 numeric.
  56
  57 For LDAP over IPC, the pathname of the Unix-domain socket can be encoded
  58 in the URL. Note that directory separators must be
  59 URL-encoded, like any other characters that are special to URLs.
  60 Thus the socket {{EX:/usr/local/var/ldapi}} must be encoded as
  61
  62 >       ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi
  63
  64 ldapi: is described in detail in {{Using LDAP Over IPC Mechanisms}} [{{REF:Chu-LDAPI}}]
  65
  66 Note that the ldapi:/// transport is not widely implemented: non-OpenLDAP clients
  67 may not be able to use it.
  68
  69 >       -n <service-name>
  70
  71 This option specifies the service name used for logging and
  72 other purposes. The default service name is {{EX:slapd}}.
  73
  74 >       -l <syslog-local-user>
  75
  76 This option specifies the local user for the {{syslog}}(8)
  77 facility.  Values can be {{EX:LOCAL0}}, {{EX:LOCAL1}}, {{EX:LOCAL2}}, ...,
  78 and {{EX:LOCAL7}}.  The default is {{EX:LOCAL4}}.  This option
  79 may not be supported on all systems.
  80
  81 >       -u user -g group
  82
  83 These options specify the user and group, respectively, to run
  84 as.  {{EX:user}} can be either a user name or uid.  {{EX:group}}
  85 can be either a group name or gid.
  86
  87 >       -r directory
  88
  89 This option specifies a run-time directory.  slapd will
  90 {{chroot}}(2) to this directory after opening listeners but
  91 before reading any configuration files or initializing
  92 any backends.
  93 .
  94
  95 >       -d <level> | ?
  96
  97 This option sets the slapd debug level to <level>. When level is a
  98 `?' character, the various debugging levels are printed and slapd
  99 exits, regardless of any other options you give it. Current
 100 debugging levels are
 101
 102 !block table; colaligns="RL"; align=Center; \
 103         title="Table 7.1: Debugging Levels"
 104 Level   Keyword         Description
 105 -1      any             enable all debugging
 106 0                       no debugging
 107 1       (0x1 trace)     trace function calls
 108 2       (0x2 packets)   debug packet handling
 109 4       (0x4 args)      heavy trace debugging
 110 8       (0x8 conns)     connection management
 111 16      (0x10 BER)      print out packets sent and received
 112 32      (0x20 filter)   search filter processing
 113 64      (0x40 config)   configuration processing
 114 128     (0x80 ACL)      access control list processing
 115 256     (0x100 stats)   stats log connections/operations/results
 116 512     (0x200 stats2)  stats log entries sent
 117 1024    (0x400 shell)   print communication with shell backends
 118 2048    (0x800 parse)   print entry parsing debugging
 119 16384   (0x4000 sync)   syncrepl consumer processing
 120 32768   (0x8000 none)   only messages that get logged whatever log level is set
 121 !endblock
 122
 123 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.
 124
 125 Note: slapd must have been compiled with {{EX:--enable-debug}}
 126 defined for any debugging information beyond the two stats levels
 127 to be available (the default).
 128
 129
 130 H2: Starting slapd
 131
 132 In general, slapd is run like this:
 133
 134 >       /usr/local/libexec/slapd [<option>]*
 135
 136 where {{F:/usr/local/libexec}} is determined by {{EX:configure}}
 137 and <option> is one of the options described above (or in {{slapd}}(8)).
 138 Unless you have specified a debugging level (including level {{EX:0}}),
 139 slapd will automatically fork and detach itself from its controlling
 140 terminal and run in the background.
 141
 142 H2: Stopping slapd
 143
 144 To kill off {{slapd}}(8) safely, you should give a command like this
 145
 146 >       kill -INT `cat /usr/local/var/slapd.pid`
 147
 148 where {{F:/usr/local/var}} is determined by {{EX:configure}}.
 149
 150 Killing slapd by a more drastic method may cause information loss or
 151 database corruption.