Update release date.
[aox:aox.git] / doc / archiveopteryx.conf.man
1 .\" Copyright 2009 The Archiveopteryx Developers <info@aox.org>
2 .TH archiveopteryx.conf 5 2009-07-13 aox.org "Archiveopteryx Documentation"
3 .SH NAME
4 archiveopteryx.conf - configuration file for Archiveopteryx.
5 .SH SYNOPSIS
6 .B $CONFIGDIR/archiveopteryx.conf
7 .br
8 .SH DESCRIPTION
9 .nh
10 .PP
11 The
12 .I archiveopteryx.conf
13 file contains most global configuration settings for Archiveopteryx. It
14 is read by each server at startup. Syntax errors, unknown variables,
15 and other errors are logged via
16 .BR logd (8).
17 .PP
18 .I archiveopteryx.conf
19 and its sibling
20 .BR aoxsuper.conf (5)
21 are usually created at installation time, by running
22 .BR $LIBDIR/installer .
23 .PP
24 There is only one required variable, namely
25 .IR db-password .
26 .SH "SECURITY NOTE"
27 Anyone who can read
28 .I archiveopteryx.conf
29 can see the database user password, and use this password to read all
30 mail and in many cases even delete mail.
31 .PP
32 By default,
33 .I archiveopteryx.conf
34 is readable only by root.
35 .SH SETTINGS
36 .PP
37 All settings share a common format:
38 .IP
39 name = value # comment
40 .PP
41 For the
42 .I *-address
43 variables, the value may be either a hostname, an IPv4 or IPv6
44 address, the fully-qualified path to a Unix socket. For
45 .I imap-address
46 and a few other variables, the empty string is also allowed, meaning
47 "all IPv4/6 addresses of this host".
48 .SS "General Settings"
49 .IP hostname
50 Most of the servers need to know the fully-qualified hostname. The
51 default is computed at runtime and is normally acceptable.
52 .IP
53 Note that if the name is "localhost", there may be problems with
54 TLS. An IMAP/POP/SMTP/HTTP client may refuse a server certificate for
55 "localhost" if it already has seen a different certificate for
56 "localhost". We strongly suggest using a different
57 .IR hostname .
58 .IP use-ipv4
59 decides whether the various servers accept IPv4 connections.
60 .I true
61 by default.
62 .IP use-ipv6
63 decides whether the various servers accept IPv6 connections.
64 .I true
65 by default.
66 .IP undelete-time
67 is the number of days a message can be undeleted after being deleted,
68 .I 49
69 by default.
70 .IP server-processes
71 is the number of processes started to serve IMAP/POP/HTTP clients. This is
72 .I 1
73 by default. 1 is suitable for a small server.
74 .IP
75 The
76 .I server-processes
77 setting should be about as large as the number of CPUs available,
78 perhaps a little larger. We advise asking info@aox.org in unusual
79 cases.
80 .SS "Database Access"
81 .IP db
82 The type of database. The default,
83 .IR postgres ,
84 is currently the only supported value.
85 .IP db-address
86 The address of the database server. The default is
87 .IR $DBADDRESS .
88 .IP db-port
89 The port number of the database server. The default is
90 .IR 5432 .
91 .IP db-name
92 The name of the database to use. The default is
93 .IR $DBNAME .
94 .IP db-schema
95 The name of the schema in the database where the database objects are
96 installed. The default is
97 .IR $DBSCHEMA .
98 It is safe to ignore this setting.
99 .IP db-user
100 The name of the unprivileged Postgres user that the servers ordinarily
101 use. The default is
102 .IR $AOXUSER .
103 .IP db-password
104 The database password used for the
105 .IR db-user .
106 The default is an empty string.
107 .IP
108 Unless a password is specified, Archiveopteryx sets up a randomly-chosen
109 password and writes it to the configuration file during installation.
110 .IP db-max-handles
111 The maximum number of database handles that Archiveopteryx may open. The
112 default is
113 .IR 4 .
114 .IP
115 The server creates one handle at startup, and may create others if the
116 load justifies it (and as controlled by
117 .IR db-handle-interval ).
118 Note, however, that when running with
119 .IR security=on ,
120 new database handles can be created only if you connect to the server
121 using TCP/IP, not via Unix sockets. In the latter case, the server must
122 use the first handle throughout its lifetime, since the socket is no
123 longer accessible after
124 .IR chroot .
125 .IP db-handle-interval
126 The minimum interval (in seconds) between the creation of new database
127 handles. The default is
128 .IR 120 .
129 .SS Logging
130 .IP log-address
131 The address of the log server. The default is
132 .IR 127.0.0.1 .
133 .IP log-port
134 The port number at which
135 .BR logd (8)
136 listens, and to which the other servers connect. The default is
137 .IR 2054 .
138 .IP logfile
139 tells
140 .BR logd (8)
141 where to write log events. It may be set to an absolute file name
142 (starting with '/'), or to "syslog/category" (e.g. "syslog/local2"),
143 which logs via
144 .BR syslog (2),
145 or to
146 .IR "-" ,
147 which causes everything to be logged to
148 .IR stdout .
149 The default is to log to
150 .IR $LOGFILE .
151 .IP logfile-mode
152 is
153 .I $LOGFILEMODE
154 by default and controls the permissions used by
155 .BR logd (8)
156 if it creates
157 .IR logfile .
158 The format (three octal digits) is the same as that used by
159 .BR chmod (1).
160 .IP log-level
161 may be set to
162 .IR debug ,
163 .IR info ,
164 .IR significant ,
165 or
166 .IR error ,
167 in increasing order of severity (it is
168 .I significant
169 by default). If a message is logged with this severity or above, the log
170 server writes it to the logfile immediately. Messages with lower severity
171 are discarded.
172 .SS Security
173 .IP security
174 is
175 .I enabled
176 by default, and should be enabled whenever Archiveopteryx is
177 used in production. It causes the servers to lock themselves into a
178 .I chroot
179 jail and run with very limited unix and database privileges. Most
180 notably, they cannot open files or delete messages.
181 .IP
182 Turning security off has exactly one advantage: it simplifies
183 debugging.
184 .IP allow-plaintext-access
185 controls whether it is possible to read mail via an unencrypted
186 connection. The default value is
187 .IR always .
188 If this is changed to
189 .IR localhost ,
190 plaintext connections are permitted only from the host itself.
191 If it is changed to
192 .IR never ,
193 TLS is necessary to read mail.
194 .IP jail-directory
195 is
196 .I $JAILDIR
197 by default. On startup, each secure server uses
198 .BR chroot (2)
199 to jail themselves into this directory, which should be empty and
200 unreadable to
201 .IR jail-user .
202 .IP jail-user
203 is the user name under which the servers run, and is
204 .I $AOXUSER
205 by default. On startup, the servers change UID to this user. This user
206 should not have read or write access to the jail directory.
207 .IP jail-group
208 is the group name under which the servers run, and is
209 .I $AOXGROUP
210 by default. On startup, the servers change GID to this user.
211 .IP entropy-source
212 is the fully-qualified name of a file that acts as a source for random
213 bytes, whenever they are needed (e.g. SASL challenges). Set to
214 .I /dev/urandom
215 by default. If this is instead set to
216 .IR /dev/random ,
217 Archiveopteryx never uses anything less than perfectly random
218 numbers. In this case, make sure that there's enough entropy, or else
219 a series of rapid login attempts can block the entire server.
220 .SS "User Authentication"
221 http://www.archiveopteryx.org/sasl describes SASL and
222 authentication in more detail.
223 .IP allow-plaintext-passwords
224 controls whether the servers permit plaintext passwords, and how such
225 passwords are handled.
226 May be set to
227 .I always
228 (which is the default) or
229 .IR never .
230 (Future versions of Archiveopteryx will offer more settings.)
231 .IP auth-digest-md5
232 controls whether the servers offer the digest-md5 SASL mechanism.
233 .I Disabled
234 by default due to interoperability problems.
235 .IP auth-cram-md5
236 controls whether the servers offer the cram-md5 SASL mechanism.
237 .I Enabled
238 by default.
239 .IP auth-plain
240 controls whether the servers offer the plain-text SASL
241 mechanism.
242 .I Enabled
243 by default.
244 .IP
245 Note that disabling auth-plain doesn't disable all plaintext
246 passwords, since SASL isn't always used. To disable plaintext
247 passwords, use the
248 .I allow-plaintext-passwords
249 variable above.
250 .IP auth-anonymous
251 controls whether the servers offer anonymous login,
252 .I disabled
253 by default.
254 .SS "Mail delivery"
255 .IP use-lmtp
256 controls whether
257 .BR archiveopteryx (8)
258 should accept mail via LMTP (RFC 2033). The default is
259 .IR enabled .
260 .IP lmtp-address
261 specifies the address where
262 .BR archiveopteryx (8)
263 should listen for LMTP connections, and to which
264 .BR deliver (8)
265 should connect. The default is
266 .IR 127.0.0.1 .
267 .IP lmtp-port
268 specifies which port
269 .BR archiveopteryx (8)
270 should listen to, and which port
271 .BR deliver (8)
272 should connect to. The default is
273 .IR 2026 .
274 .IP use-smtp
275 controls whether
276 .BR archiveopteryx (8)
277 should accept mail via SMTP/ESMTP (RFC 2821/1869). SMTP is
278 .I disabled
279 by default.
280 .IP smtp-address
281 specifies the address where
282 .BR archiveopteryx (8)
283 should listen for SMTP connections The default is an empty string,
284 which means all available IPv4 and IPv6 interfaces.
285 .IP smtp-port
286 specifies which port
287 .BR archiveopteryx (8)
288 should listen to. The default is
289 .IR 25 .
290 .IP use-subaddressing
291 controls whether messages addressed to
292 .I user+tag@example.org
293 are accepted for delivery to
294 .I user@example.org
295 (if the latter is a valid recipient address). The default is
296 .IR false .
297 .IP address-separator
298 is the character that separates the username from the subaddress in a
299 localpart, e.g. the
300 .I +
301 in
302 .IR user+tag@example.org .
303 The default, which you should not need to change, is
304 .IR + .
305 This setting is relevant only if
306 .I use-subaddressing
307 is true.
308 .IP soft-bounce
309 specifies whether a delivery problem causes a message to be rejected
310 permanently (soft-bounce disabled) or queued at the MTA (soft-bounce
311 enabled). This is
312 .I enabled
313 by default. We recommend disabling it when you are confident that mail
314 delivery works.
315 .IP message-copy
316 specifies whether or not to keep filesystem copies of incoming
317 messages, e.g. to burn a mail log to CD/DVD regularly.
318 The default value of
319 .I none
320 means that no copies are ever made.
321 .IP
322 Setting it to
323 .I delivered
324 keeps copies of all delivered messages, a value of
325 .I errors
326 keeps only those messages that could not be delivered because of errors, and
327 .I all
328 keeps copies of all messages.
329 .IP message-copy-directory
330 specifies a directory to which mail delivered via LMTP/SMTP is copied, if
331 .I message-copy
332 is set. Its default value is
333 .IR $MESSAGEDIR .
334 .IP
335 If
336 .I message-copy-directory
337 does not exist or is not writable,
338 Archiveopteryx logs an error at startup and exits.
339 .IP
340 Each file in
341 .I message-copy-directory
342 contains one or more header lines, namely
343 .BR Error ,
344 .B From
345 and
346 .BR To ,
347 then an empty line, then the verbatim received mail message. If there is an
348 .B Error
349 line, the message was not delivered, and the rest of the line
350 describes the problem.
351 .IP
352 The file's name is a unique string of numbers and hyphens. It ends with
353 "-err" if there was an error injecting the message into the database.
354 .SS "SMTP Submission"
355 .IP use-smtp-submit
356 controls whether
357 .BR archiveopteryx (8)
358 should accept mail via SMTP-Submit (RFC 4409). The default is
359 .IR enabled .
360 .IP check-sender-addresses
361 controls whether
362 .BR archiveopteryx (8)
363 should check whether the sender is authorised to use the addresses in
364 the message. From, Sender, Return-Path (SMTP Mail From) and Reply-To
365 are all checked. The default is
366 .IR disabled .
367 .IP submit-copy-to-sender
368 controls whether
369 .BR archiveopteryx (8)
370 should ensure that the sender receives a copy of outgoing mail. The default
371 is
372 .IR disabled .
373 This can be used to ensure that all outgoing mail is archived.
374 .IP
375 If the sender already receives a copy of the message,
376 .I submit-copy-to-sender
377 has no effect. Senders will not receive two copies. The copy is
378 always sent to the user who sends the message, even if the From and/or
379 Return-Path is different. The sender's copy will be delivered through
380 the configured
381 .IR smarthost ,
382 as with any other outgoing message.
383 .IP smtp-submit-address
384 specifies the address where
385 .BR archiveopteryx (8)
386 should listen for Submit connections. The
387 default, an empty string, means to listen on all available IPv4 and
388 IPv6 addresses.
389 .IR 127.0.0.1 .
390 .IP smtp-submit-port
391 specifies which port
392 .BR archiveopteryx (8)
393 should listen to. The default is
394 .IR 587 .
395 .IP smarthost-address
396 specifies the address of the SMTP server which is used to relay mail to
397 remote recipients. The default is
398 .IR 127.0.0.1 .
399 .IP smarthost-port
400 specifies the port to use when forwarding mail to a smarthost. The
401 default is
402 .IR 25 .
403 (These defaults thus conflict with the default values of
404 .I smtp-address
405 and
406 .I smtp-port
407 when
408 .I use-smtp
409 is enabled.)
410 .IP use-smtps
411 controls whether
412 .BR archiveopteryx (8)
413 should accept SSL-wrapped SMTP connections. The default is
414 .IR false
415 (and the use of STARTTLS with SMTP Submit is strongly recommended
416 instead).
417 .IP smtps-address
418 is the address where
419 .BR archiveopteryx (8)
420 listens for new SSL-wrapped SMTP connections. As for
421 .IR smtp-address ,
422 the default is an empty string, which means all available IPv4 and
423 IPv6 addresses.
424 .IP smtps-port
425 is the port where
426 .BR archiveopteryx (8)
427 accepts SSL-wrapped SMTP connections,
428 .I 465
429 by default.
430 .SS IMAP
431 .IP use-imap
432 must be enabled for
433 .BR archiveopteryx (8)
434 to accept IMAP connections. The default is
435 .IR true .
436 .IP imap-address
437 is the address where
438 .BR archiveopteryx (8)
439 listens for new connections. The
440 default, an empty string, means to listen on all available IPv4 and
441 IPv6 addresses.
442 .IP imap-port
443 is the port where
444 .BR archiveopteryx (8)
445 accepts connections,
446 .I 143
447 by default.
448 .IP use-imaps
449 controls whether
450 .BR archiveopteryx (8)
451 should also accept SSL-wrapped IMAP connections. The default is
452 .I false
453 (and the use of STARTTLS over the standard IMAP port is strongly
454 recommended instead).
455 .IP imaps-address
456 is the address where
457 .BR archiveopteryx (8)
458 listens for new SSL-wrapped connections. As for
459 .IR imap-address ,
460 the default is an empty string, which means all available IPv4 and
461 IPv6 addresses.
462 .IP imaps-port
463 is the port where
464 .BR archiveopteryx (8)
465 accepts SSL-wrapped connections,
466 .I 993
467 by default.
468 .SS POP
469 .IP use-pop
470 must be enabled for
471 .BR archiveopteryx (8)
472 to accept POP3 connections. The default is
473 .IR false .
474 .IP pop-address
475 is the address where
476 .BR archiveopteryx (8)
477 listens for new connections. The default, an empty string, means to
478 listen on all available IPv4 and IPv6 addresses.
479 .IP pop-port
480 is the port where
481 .BR archiveopteryx (8)
482 accepts connections,
483 .I 110
484 by default.
485 .SS HTTP
486 .IP use-http
487 decides whether Archiveopteryx offers HTTP service at all, and is
488 .I no
489 by default.
490 .IP http-address
491 is the address where
492 .BR archiveopteryx (8)
493 listens for new connections. The default is
494 .IR 127.0.0.1 .
495 .IP http-port
496 is the port where
497 .BR archiveopteryx (8)
498 accepts connections,
499 .I 8808
500 by default.
501 .IP use-https
502 decides whether Archiveopteryx offers HTTPS (SSL-wrapped HTTP) service,
503 and is
504 .I no
505 by default.
506 .IP https-address
507 is the address where
508 .BR archiveopteryx (8)
509 listens for new HTTPS connections. The default is
510 .IR 127.0.0.1 .
511 .IP https-port
512 is the port where
513 .BR archiveopteryx (8)
514 accepts connections,
515 .I 8443
516 by default.
517 .IP accept-any-http-host
518 decides whether
519 .BR archiveopteryx (8)
520 accepts any hostname supplied by the client, and is
521 .I enabled
522 by default. Properly speaking, it would be better to disable this, but
523 that would add complexity without giving anything in return.
524 .IP use-web-archive
525 decides whether archiveopteryx provides web-visible archives of
526 world-readable mailboxes. The default is
527 .I false
528 and for the moment we recommend leaving it at false. This code is not
529 ready for production use.
530 .IP archive-prefix
531 is the common prefix for all URLs offering archive access to mailboxes
532 via the web. These mailboxes must be readable by the anonymous user.
533 The default value is empty.
534 .IP use-webmail
535 ldecides whether archiveopteryx provides webmail access. The default is
536 .I false
537 and we strongly recommend leaving it at false. Don't enable this.
538 .IP webmail-prefix
539 is the common prefix for all URLs offering authenticated webmail access
540 to mailboxes via the web. The default value is
541 .IR /webmail .
542 .IP webmail-css-url
543 points to the style sheet used for webmail and archive pages.
544 The default value is
545 .IR http://www.archiveopteryx.org/webmail/default.css .
546 By using a different URL you can change the appearance of the pages
547 completely.
548 .IP webmail-js-url
549 points to a javascript which will be included in all webmail and
550 archive pages. The default is an empty string, which means to not
551 include any external javascript. This can be used together with
552 .I webmail-css-url
553 to change the behaviour of the webmail and archive pages.
554 .IP favicon-url
555 is the URL of the favicon displayed for your site by many web browsers.
556 The default value is
557 .IR http://www.archiveopteryx.org/favicon.ico ,
558 but you can change it to anything. When the browser requests the favicon,
559 .BR archiveopteryx (8)
560 responds with a redirect to this URL.
561 .SS SIEVE
562 .IP use-sieve
563 controls whether or not the
564 .I managesieve
565 server is started. The default is
566 .IR enabled .
567 .IP managesieve-address
568 specifies the address where
569 .BR archiveopteryx (8)
570 should listen for connections. The default is an empty string, which
571 means to listen on all available IPv4 and IPv6 addresses.
572 .IR an empt
573 .IP managesieve-port
574 specifies which port
575 .BR archiveopteryx (8)
576 should listen to. The default is
577 .IR 2000 .
578 .SS TLS
579 .IP use-tls
580 regulates whether Archiveopteryx supports TLS at all. The default is
581 .IR enabled .
582 .IP tls-certificate
583 is the absolute file name of the TLS private key and signed certificate,
584 e.g.
585 .IR $CONFIGDIR/imap.p15 .
586 If
587 .I tls-certificate
588 is not specified, tlsproxy generates a private key and a self-signed
589 certificate at runtime and stores both in
590 .IR $CONFIGDIR/automatic-key.p15 .
591 .IP tls-certificate-label
592 is a label that uniquely identifies the key and certificate to use in
593 the PKCS #15 key file identified by
594 .I tls-certificate
595 (which can contain multiple key pairs). By default, this
596 is empty, and the current hostname is used as a label.
597 .IP tls-certificate-secret
598 is a secret password used to access the appropriate key and certificate
599 in the PKCS #15 key file identified by
600 .IR tls-certificate .
601 .IP tlsproxy-address
602 is the address where
603 .BR tlsproxy (8)
604 listens for new connections. The default is
605 .IR 127.0.0.1 .
606 .IP tlsproxy-port
607 is the port where
608 .BR tlsproxy (8)
609 accepts connections,
610 .I 2061
611 by default.
612 .SH SYNTAX
613 .PP
614 The name is case insensitive, as shown:
615 .IP
616 hostname = test1.example.com
617 .br
618 HOSTNAME = mailserver.example.org
619 .PP
620 The value is case insensitive wherever possible. (Exceptions
621 include logfile, db-user and db-password.)
622 .PP
623 There are three datatypes: Strings, numbers and toggles.
624 .PP
625 Strings may be written as a single unquoted word or quoted with either
626 single or double quotes, as shown in these three examples:
627 .IP
628 db-password = single.word
629 .br
630 db-password = "rock'n'roll" # a 12-character password
631 .br
632 db-password = 'two words, quoted' # a 17-character one
633 .PP
634 Only single-line strings can be used. Single-word strings may contain
635 the characters a-z, A-Z, 0-9, dot, hyphen and slash.
636 .PP
637 Numbers are integers not smaller than 0 and not larger than 2147483647
638 (ie. 31-bit unsigned integers).
639 .PP
640 Toggles are written as a single word.
641 .IR Yes ,
642 .IR true ,
643 .IR on ,
644 .IR 1 ,
645 and
646 .I enabled
647 all
648 mean that the toggle is enabled, while
649 .IR no ,
650 .IR false ,
651 .IR off ,
652 .IR 0 ,
653 and
654 .I disabled
655 unsurprisingly mean disabled. Toggles are case-insensitive.
656 .IP
657 use-lmtp = yes
658 .br
659 crash-and-delete-all-the-mail = off
660 .PP
661 Spaces are allowed at the start of the line, before and after '=', and
662 after the value. Comments extend from '#' to the end of the line.
663 .IP
664 # this is a comment
665 .br
666 hostname=stuff.nonsense.example.com # also a comment
667 .br
668  logfile    =   /dev/null# and this is a comment
669 .br
670 # empty lines are ignored
671 .SH AUTHOR
672 The Archiveopteryx Developers, info@aox.org.
673 .SH VERSION
674 This man page covers Archiveopteryx version 3.1.2, released 2009-07-13,
675 http://www.archiveopteryx.org/3.1.2
676 .SH SEE ALSO
677 .BR archiveopteryx (8),
678 .BR deliver (8),
679 .BR logd (8),
680 .BR tlsproxy (8),
681 http://www.archiveopteryx.org