Debian Codegraph @

doc/html/_sources/imap/reference/manpages/configs/cyrus.conf.rst.txt

raw
1 .. cyrusman:: cyrus.conf(5)
2
3 .. author: Nic Bernstein (Onlight)
4
5 .. _imap-reference-manpages-configs-cyrus.conf:
6
7 ==============
8 **cyrus.conf**
9 ==============
10
11 Cyrus configuration file
12
13 Description
14 ===========
15
16 **cyrus.conf** is the configuration file for the Cyrus
17 :cyrusman:`master(8)` process. It defines the startup procedures,
18 services, events and daemons to be spawned, managed and tended to by
19 **master**.
20
21 The ``/etc/cyrus.conf`` file consists of a series of entries divided
22 into sections of the form
23
24 .. parsed-literal::
25
26 *section* {
27 *name arguments
28 ...
29 ...
30 ...*
31 }
32
33 ..
34
35 where *section* is the name of the section, *name* is the name of the
36 entry and *arguments* is the whitespace-separated list of arguments for
37 the entry. The *name* may be any sequence of alphabetic and numeric
38 characters, but may not contain punctuation such as '-' or '_'. In the
39 **SERVICES** section, names must be unique.
40
41 Blank lines and lines beginning with \`\`#'' are ignored.
42
43 Section Descriptions
44 ====================
45
46 The paragraphs below detail the four sections (**START**, **SERVICES**,
47 **EVENTS**, **DAEMON**) that can be placed in the ``/etc/cyrus.conf``
48 file. The arguments that are available for each entry within the
49 section are described, and each argument's default value is shown.
50
51 An important distinction exists between **SERVICES** and **DAEMON** ;
52 the former have sockets which :cyrusman:`master(8)` will listen on
53 (either IP or Unix domain) while the latter do not. Similarly,
54 processes listed in **START** will be run to completion before any
55 **SERVICES** are started, while those in **DAEMON** will be managed by
56 :cyrusman:`master(8)`.
57
58 .. Note::
59
60 If :cyrusman:`master(8)` is started in debugging mode (**-D**) the
61 behavior of **DAEMON** will be altered, as :cyrusman:`master(8)`
62 will no longer be backgrounded. Thus, processes started under
63 DAEMON may not be terminated by :cyrusman:`master(8)`.
64
65 Arguments can appear in any order. Some arguments have no default
66 value, these are listed with \`\`<no default>''. For string arguments,
67 the value MUST be enclosed in double quotes.
68
69 START
70 -----
71
72 This section lists the processes to run before any **SERVICES** are
73 spawned. This section is typically used to initialize databases.
74 Master itself will not startup until all tasks in **START** have
75 completed, so put no blocking commands here.
76
77 .. parsed-literal::
78
79 **cmd=**\ <no default>
80
81 ..
82
83 The command (with options) to spawn as a child process. This
84 string argument is required.
85
86 .. Note::
87
88 Prior to v3, non-service daemons like ``idled`` were started from
89 **START** but would background themselves, thus not blocking. Post
90 v3 these are better managed through the **DAEMON** section, under
91 which master will provide life-cycle management (i.e. restarting
92 dead processes).
93
94 SERVICES
95 --------
96
97 This section is the heart of the **/etc/cyrus.conf** file. It lists
98 the processes that should be spawned to handle client connections made
99 on certain Internet/UNIX sockets.
100
101 .. parsed-literal::
102
103 **babysit=**\ 0
104
105 ..
106
107 Integer value - if non-zero, will make sure at least one process is
108 pre-forked, and will set the maxforkrate to 10 if it's zero.
109
110 .. parsed-literal::
111
112 **cmd=**\ <no default>
113
114 ..
115
116 The command (with options) to spawn as a child process. This string
117 argument is required.
118
119 .. parsed-literal::
120
121 **listen=**\ <no default>
122
123 ..
124
125 The UNIX or internet socket to listen on. This
126 string field is required and takes one of the following forms:
127
128 .. parsed-literal::
129
130 *path*
131 [ *host* **:** ] *port*
132
133 ..
134
135 where *path* is the explicit path to a UNIX socket, *host* is
136 either the hostname or bracket-enclosed IP address of a network
137 interface, and *port* is either a port number or service name
138 (as listed in ``/etc/services``).
139
140 If *host* is missing, 0.0.0.0 (all interfaces) is assumed. Use
141 localhost or 127.0.0.1 to restrict access, i.e. when a proxy
142 on the same host is front-ending Cyrus.
143
144 Note that on most systems UNIX socket paths are limited to around
145 100 characters. See your system documentation for specifics.
146
147 .. parsed-literal::
148
149 **proto=**\ tcp
150
151 ..
152
153 The protocol used for this service (*tcp*, *tcp4*, *tcp6*,
154 *udp*, *udp4*, *udp6*). This string argument is optional.
155
156 **tcp4**, **udp4**: These arguments are used to bind the
157 service to IPv4 only.
158
159 **tcp6**, **udp6**: These arguments are used to bind the
160 service to IPv6 only, if the operating system supports this.
161
162 **tcp**, **udp**: These arguments are used to bind to both IPv4
163 and IPv6 if possible.
164
165 .. parsed-literal::
166
167 **prefork=**\ 0
168
169 ..
170
171 The number of instances of this service to always have running
172 and waiting for a connection (for faster initial response
173 time). This integer value is optional. Note that if you are
174 listening on multiple network types (i.e. ipv4 and ipv6) then
175 one process will be forked for each address, causing twice as
176 many processes as you might expect.
177
178 .. parsed-literal::
179
180 **maxchild=**\ -1
181
182 ..
183
184 The maximum number of instances of this service to spawn. A
185 value of -1 means unlimited. This integer value is optional.
186
187 .. parsed-literal::
188
189 **maxfds=**\ 256
190
191 ..
192
193 The maximum number of file descriptors to which to limit this
194 process. This integer value is optional.
195
196 .. parsed-literal::
197
198 **maxforkrate=**\ 0
199
200 ..
201
202 Maximum number of processes to fork per second - the master
203 will insert sleeps to ensure it doesn't fork faster than this
204 on average.
205
206 EVENTS
207 ------
208
209 This section lists processes that should be run at specific intervals,
210 similar to cron jobs. This section is typically used to perform
211 scheduled cleanup/maintenance.
212
213 .. parsed-literal::
214
215 **cmd=**\ <no default>
216
217 ..
218
219 The command (with options) to spawn as a child process. This
220 string argument is required.
221
222 .. parsed-literal::
223
224 **period=**\ 0
225
226 ..
227
228 The interval (in minutes) at which to run the command. This
229 integer value is optional, but SHOULD be a positive integer >
230 10.
231
232 .. parsed-literal::
233
234 **at=**\ <hhmm>
235
236 ..
237
238 The time (24-hour format) at which to run the command each day.
239 If set to a valid time (0000-2359), period is automatically
240 set to 1440. This string argument is optional.
241
242 DAEMON
243 ------
244
245 This section lists long running daemons to start before any
246 **SERVICES** are spawned. :cyrusman:`master(8)` will ensure that
247 these processes are running, restarting any process which dies or
248 forks. All listed processes will be shutdown when :cyrusman:`master(8)`
249 is exiting.
250
251 .. parsed-literal::
252
253 **cmd=**\ <no default>
254
255 ..
256
257 The command (with options) to spawn as a child process. This
258 string argument is required.
259
260 .. parsed-literal::
261
262 **wait=**\ 0
263
264 ..
265
266 Switch: whether or not :cyrusman:`master(8)` should wait for this
267 daemon to successfully start before continuing to load.
268
269 If *wait=n* (the default), the daemon will be started asynchronously
270 along with the service processes. The daemon process will not have
271 file descriptor 3 open, and does not need to indicate its readiness.
272
273 If *wait=y*, the daemon MUST write "ok\\r\\n" to file descriptor 3
274 to indicate its readiness; if it does not do this, and master has
275 been told to wait, master will continue to wait.... If it writes
276 anything else to this descriptor, or closes it before writing
277 "ok\\r\\n", master will exit with an error.
278
279 Daemons with *wait=y* will be started sequentially in the order
280 they are listed in cyrus.conf, waiting for each to report readiness
281 before the next is started.
282
283 Service processes, and *wait=n* daemons, are not started until after
284 the *wait=y* daemons are all started and ready.
285
286 At shutdown, *wait=y* daemons will be terminated sequentially in the
287 reverse order they were started, commencing after all other services
288 and *wait=n* daemons have finished.
289
290 If a daemon that was started with *wait=y* exits unexpectedly, such
291 that master restarts it, master will restart it asynchronously,
292 without waiting for it to report its readiness. In this case, file
293 descriptor 3 will not be open and the daemon should not try to write
294 to it.
295
296 If master is told to reread its config with a SIGHUP, this signal
297 will be passed on to *wait=y* daemons like any other service. If the
298 daemon exits in response to the signal, master will restart it
299 asynchronously, without waiting for it to report its readiness. In
300 this case too, file descriptor 3 will not be open and the daemon
301 should not try to write to it.
302
303 Examples
304 ========
305
306 ::
307
308 # example cyrus.conf
309
310 START {
311 recover cmd="ctl_cyrusdb -r"
312 }
313
314 SERVICES {
315 imap cmd="imapd" listen="imap" prefork=1
316 imaps cmd="imapd -s" listen="imaps" prefork=0
317 lmtpunix cmd="lmtpd" listen="/var/imap/socket/lmtp"
318 lmtp cmd="lmtpd" listen="localhost:lmtp"
319 }
320
321 EVENTS {
322 checkpoint cmd="ctl_cyrusdb -c" period=30
323 delprune cmd="cyr_expire -E 3" at=0400
324 tlsprune cmd="tls_prune" at=0400
325 }
326
327 DAEMON {
328 idled cmd="idled"
329 }
330
331 Access Control
332 ==============
333
334 When TCP Wrappers is used to control access to Cyrus services, the
335 *name* of the service entry should be used as the process name in
336 the :manpage:`hosts_access(5)` table. For instance, in the example above,
337 "imap", "imaps", "lmtpunix" and "lmtp" would be used as the process
338 names. This allows a single daemon such as imapd to be run in
339 different modes or configurations (i.e., SSL and non-SSL enabled) yet
340 still have separate access control rules.
341
342 See Also
343 ========
344
345 :cyrusman:`master(8)`,
346 :cyrusman:`imapd(8)`,
347 :cyrusman:`pop3d(8)`,
348 :cyrusman:`lmtpd(8)`,
349 :cyrusman:`smmapd(8)`,
350 :cyrusman:`timsieved(8)`,
351 :cyrusman:`idled(8)`,
352 :cyrusman:`notifyd(8)`,
353 :cyrusman:`ctl_cyrusdb(8)`,
354 :cyrusman:`ctl_deliver(8)`,
355 :cyrusman:`tls_prune(8)`,
356 :manpage:`hosts_access(5)`