]> git.sur5r.net Git - openldap/blob - doc/guide/admin/runningslapd.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / runningslapd.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 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.