1CYRUS.CONF(5)                     Cyrus IMAP                     CYRUS.CONF(5)
2
3
4

NAME

6       cyrus.conf - Cyrus IMAP documentation
7
8       Cyrus configuration file
9

DESCRIPTION

11       cyrus.conf  is  the configuration file for the Cyrus master(8) process.
12       It defines the startup procedures, services, events and daemons  to  be
13       spawned, managed and tended to by master.
14
15       The  /etc/cyrus.conf  file consists of a series of entries divided into
16       sections of the form
17
18              section {
19                  name arguments
20                      ...
21                      ...
22                      ...
23              }
24
25       where section is the name of the section, name is the name of the entry
26       and arguments is the whitespace-separated list of arguments for the en‐
27       try.  The name may be any sequence of alphabetic  and  numeric  charac‐
28       ters,  but may not contain punctuation such as '-' or '_'.  In the SER‐
29       VICES section, names must be unique.
30
31       Blank lines and lines beginning with ``#'' are ignored.
32

SECTION DESCRIPTIONS

34       The paragraphs below detail the four sections (START, SERVICES, EVENTS,
35       DAEMON)  that can be placed in the /etc/cyrus.conf file.  The arguments
36       that are available for each entry within the section are described, and
37       each argument's default value is shown.
38
39       An  important distinction exists between SERVICES and DAEMON ; the for‐
40       mer have sockets which master(8) will listen on (either IP or Unix  do‐
41       main)  while  the  latter do not.  Similarly, processes listed in START
42       will be run to completion before any SERVICES are started, while  those
43       in DAEMON will be managed by master(8).
44
45       NOTE:
46          If  master(8) is started in debugging mode (-D) the behavior of DAE‐
47          MON will be altered, as master(8) will no  longer  be  backgrounded.
48          Thus,  processes  started under DAEMON may not be terminated by mas‐
49          ter(8).
50
51       Arguments can appear in any  order.  Some  arguments  have  no  default
52       value,  these  are listed with ``<no default>''.  For string arguments,
53       the value MUST be enclosed in double quotes.
54
55   START
56       This section lists  the  processes  to  run  before  any  SERVICES  are
57       spawned.  This section is typically used to initialize databases.  Mas‐
58       ter itself will not startup until all tasks in START have completed, so
59       put no blocking commands here.
60
61          cmd=<no default>
62          The command (with options) to spawn as a child process.  This string
63          argument is required.
64
65       NOTE:
66          Prior to v3, non-service daemons like idled were started from  START
67          but  would  background themselves, thus not blocking.  Post v3 these
68          are better managed through the DAEMON section,  under  which  master
69          will provide life-cycle management (i.e. restarting dead processes).
70
71   SERVICES
72       This  section  is  the heart of the /etc/cyrus.conf file.  It lists the
73       processes that should be spawned to handle client connections  made  on
74       certain Internet/UNIX sockets.
75
76          babysit=0
77          Integer  value - if non-zero, will make sure at least one process is
78          pre-forked, and will set the maxforkrate to 10 if it's zero.
79
80          cmd=<no default>
81          The command (with options) to spawn as a child process.  This string
82          argument is required.
83
84          listen=<no default>
85          The  UNIX or internet socket to listen on.  This string field is re‐
86          quired and takes one of the following forms:
87
88              path
89              [ host : ] port
90
91          where path is the explicit path to a UNIX socket, host is either the
92          hostname  or bracket-enclosed IP address of a network interface, and
93          port is either a port number or service name (as listed in /etc/ser‐
94          vices).
95
96          If host is missing, 0.0.0.0 (all interfaces) is assumed.  Use local‐
97          host or 127.0.0.1 to restrict access, i.e. when a proxy on the  same
98          host is front-ending Cyrus.
99
100          Note  that  on  most systems UNIX socket paths are limited to around
101          100 characters.  See your system documentation for specifics.
102
103          proto=tcp
104          The protocol used for this service  (tcp,  tcp4,  tcp6,  udp,  udp4,
105          udp6).  This string argument is optional.
106
107          tcp4,  udp4:  These  arguments  are used to bind the service to IPv4
108          only.
109
110          tcp6, udp6: These arguments are used to bind  the  service  to  IPv6
111          only, if the operating system supports this.
112
113          tcp,  udp: These arguments are used to bind to both IPv4 and IPv6 if
114          possible.
115
116          prefork=0
117          The number of instances of this service to always have  running  and
118          waiting  for  a connection (for faster initial response time).  This
119          integer value is optional.  Note that if you are listening on multi‐
120          ple  network  types  (i.e.  ipv4  and ipv6) then one process will be
121          forked for each address, causing twice  as  many  processes  as  you
122          might expect.
123
124          maxchild=-1
125          The  maximum  number of instances of this service to spawn.  A value
126          of -1 means unlimited.  This integer value is optional.
127
128          maxfds=256
129          The maximum number of  file  descriptors  to  which  to  limit  this
130          process. This integer value is optional.
131
132          maxforkrate=0
133          Maximum number of processes to fork per second - the master will in‐
134          sert sleeps to ensure it doesn't fork faster than this on average.
135
136   EVENTS
137       This section lists processes that should be run at specific  intervals,
138       similar to cron jobs.  This section is typically used to perform sched‐
139       uled cleanup/maintenance.
140
141          cmd=<no default>
142          The command (with options) to spawn as a child process.  This string
143          argument is required.
144
145          period=0
146          The interval (in minutes) at which to run the command.  This integer
147          value is optional, but SHOULD be a positive integer > 10.
148
149          at=<hhmm>
150          The time (24-hour format) at which to run the command each day.   If
151          set  to  a  valid  time  (0000-2359), period is automatically set to
152          1440. This string argument is optional.
153
154   DAEMON
155       This section lists long running daemons to start  before  any  SERVICES
156       are  spawned.  master(8)  will ensure that these processes are running,
157       restarting any process which dies or forks. All listed  processes  will
158       be shutdown when master(8) is exiting.
159
160          cmd=<no default>
161          The command (with options) to spawn as a child process.  This string
162          argument is required.
163
164          wait=0
165          Switch: whether or not master(8) should wait for this daemon to suc‐
166          cessfully start before continuing to load.
167
168          If  wait=n  (the default), the daemon will be started asynchronously
169          along with the service processes.  The daemon process will not  have
170          file descriptor 3 open, and does not need to indicate its readiness.
171
172          If  wait=y,  the  daemon MUST write "ok\r\n" to file descriptor 3 to
173          indicate its readiness; if it does not do this, and master has  been
174          told to wait, master will continue to wait.... If it writes anything
175          else to this descriptor, or closes it before writing "ok\r\n",  mas‐
176          ter will exit with an error.
177
178          Daemons  with  wait=y will be started sequentially in the order they
179          are listed in cyrus.conf, waiting for each to report  readiness  be‐
180          fore the next is started.
181
182          Service  processes,  and wait=n daemons, are not started until after
183          the wait=y daemons are all started and ready.
184
185          At shutdown, wait=y daemons will be terminated sequentially  in  the
186          reverse order they were started, commencing after all other services
187          and wait=n daemons have finished.
188
189          If a daemon that was started with wait=y  exits  unexpectedly,  such
190          that  master  restarts  it,  master  will restart it asynchronously,
191          without waiting for it to report its readiness.  In this case,  file
192          descriptor 3 will not be open and the daemon should not try to write
193          to it.
194
195          If master is told to reread its config with a  SIGHUP,  this  signal
196          will  be passed on to wait=y daemons like any other service.  If the
197          daemon exits in response to the signal, master will restart it asyn‐
198          chronously,  without waiting for it to report its readiness. In this
199          case too, file descriptor 3 will not be open and the  daemon  should
200          not try to write to it.
201

EXAMPLES

203          # example cyrus.conf
204
205          START {
206              recover       cmd="ctl_cyrusdb -r"
207          }
208
209          SERVICES {
210              imap          cmd="imapd" listen="imap" prefork=1
211              imaps         cmd="imapd -s" listen="imaps" prefork=0
212              lmtpunix      cmd="lmtpd" listen="/var/imap/socket/lmtp"
213              lmtp          cmd="lmtpd" listen="localhost:lmtp"
214          }
215
216          EVENTS {
217              checkpoint    cmd="ctl_cyrusdb -c" period=30
218              delprune      cmd="cyr_expire -E 3" at=0400
219              tlsprune      cmd="tls_prune" at=0400
220          }
221
222          DAEMON {
223              idled         cmd="idled"
224          }
225

ACCESS CONTROL

227       When TCP Wrappers is used to control access to Cyrus services, the name
228       of the service entry  should  be  used  as  the  process  name  in  the
229       hosts_access(5)  table.   For  instance,  in the example above, "imap",
230       "imaps", "lmtpunix" and "lmtp" would be  used  as  the  process  names.
231       This  allows a single daemon such as imapd to be run in different modes
232       or configurations (i.e., SSL and non-SSL enabled) yet still have  sepa‐
233       rate access control rules.
234

SEE ALSO

236       master(8),   imapd(8),  pop3d(8),  lmtpd(8),  smmapd(8),  timsieved(8),
237       idled(8),  notifyd(8),  ctl_cyrusdb(8),  ctl_deliver(8),  tls_prune(8),
238       hosts_access(5)
239

AUTHOR

241       The Cyrus Team, Nic Bernstein (Onlight)
242
244       1993–2023, The Cyrus Team
245
246
247
248
2493.8.1                            Sep 11, 2023                    CYRUS.CONF(5)
Impressum