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 11Cyrus configuration file 12 13Description 14=========== 15 16**cyrus.conf** is the configuration file for the Cyrus 17:cyrusman:`master(8)` process. It defines the startup procedures, 18services, events and daemons to be spawned, managed and tended to by 19**master**. 20 21The ``/etc/cyrus.conf`` file consists of a series of entries divided 22into sections of the form 23 24 .. parsed-literal:: 25 26 *section* { 27 *name arguments 28 ... 29 ... 30 ...* 31 } 32 33 .. 34 35where *section* is the name of the section, *name* is the name of the 36entry and *arguments* is the whitespace-separated list of arguments for 37the entry. The *name* may be any sequence of alphabetic and numeric 38characters, but may not contain punctuation such as '-' or '_'. In the 39**SERVICES** section, names must be unique. 40 41Blank lines and lines beginning with \`\`#'' are ignored. 42 43Section Descriptions 44==================== 45 46The paragraphs below detail the four sections (**START**, **SERVICES**, 47**EVENTS**, **DAEMON**) that can be placed in the ``/etc/cyrus.conf`` 48file. The arguments that are available for each entry within the 49section are described, and each argument's default value is shown. 50 51An important distinction exists between **SERVICES** and **DAEMON** ; 52the former have sockets which :cyrusman:`master(8)` will listen on 53(either IP or Unix domain) while the latter do not. Similarly, 54processes 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 65Arguments can appear in any order. Some arguments have no default 66value, these are listed with \`\`<no default>''. For string arguments, 67the value MUST be enclosed in double quotes. 68 69START 70----- 71 72This section lists the processes to run before any **SERVICES** are 73spawned. This section is typically used to initialize databases. 74Master itself will not startup until all tasks in **START** have 75completed, 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 94SERVICES 95-------- 96 97This section is the heart of the **/etc/cyrus.conf** file. It lists 98the processes that should be spawned to handle client connections made 99on 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 restict 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 206EVENTS 207------ 208 209This section lists processes that should be run at specific intervals, 210similar to cron jobs. This section is typically used to perform 211scheduled 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 242DAEMON 243------ 244 245This section lists long running daemons to start before any 246**SERVICES** are spawned. They will be shutdown when 247:cyrusman:`master(8)` is exiting. 248 249.. parsed-literal:: 250 251 **cmd=**\ <no default> 252 253.. 254 255 The command (with options) to spawn as a child process. This 256 string argument is required. 257 258 259Examples 260======== 261 262:: 263 264 # example cyrus.conf 265 266 START { 267 recover cmd="ctl_cyrusdb -r" 268 } 269 270 SERVICES { 271 imap cmd="imapd" listen="imap" prefork=1 272 imaps cmd="imapd -s" listen="imaps" prefork=0 273 lmtpunix cmd="lmtpd" listen="/var/imap/socket/lmtp" 274 lmtp cmd="lmtpd" listen="localhost:lmtp" 275 } 276 277 EVENTS { 278 checkpoint cmd="ctl_cyrusdb -c" period=30 279 delprune cmd="cyr_expire -E 3" at=0400 280 tlsprune cmd="tls_prune" at=0400 281 } 282 283 DAEMON { 284 idled cmd="idled" 285 } 286 287Access Control 288============== 289 290When TCP Wrappers is used to control access to Cyrus services, the 291*name* of the service entry should be used as the process name in 292the :manpage:`hosts_access(5)` table. For instance, in the example above, 293"imap", "imaps", "lmtpunix" and "lmtp" would be used as the process 294names. This allows a single daemon such as imapd to be run in 295different modes or configurations (i.e., SSL and non-SSL enabled) yet 296still have separate access control rules. 297 298See Also 299======== 300 301:cyrusman:`master(8)`, 302:cyrusman:`imapd(8)`, 303:cyrusman:`pop3d(8)`, 304:cyrusman:`lmtpd(8)`, 305:cyrusman:`timsieved(8)`, 306:cyrusman:`idled(8)`, 307:cyrusman:`notifyd(8)`, 308:cyrusman:`ctl_cyrusdb(8)`, 309:cyrusman:`ctl_deliver(8)`, 310:cyrusman:`tls_prune(8)`, 311:manpage:`hosts_access(5)` 312