Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
archiveopteryx.conf(5)	 Archiveopteryx	Documentation	archiveopteryx.conf(5)

NAME
       archiveopteryx.conf - configuration file	for Archiveopteryx.

SYNOPSIS
       /usr/local/etc/archiveopteryx/archiveopteryx.conf

DESCRIPTION
       The   archiveopteryx.conf   file	 contains  most	 global	 configuration
       settings	for Archiveopteryx. It is read	by  each  server  at  startup.
       Syntax  errors,	unknown	 variables,  and  other	 errors	are logged via
       logd(8).

       archiveopteryx.conf  and	 its  sibling  aoxsuper.conf(5)	 are   usually
       created	      at       installation	  time,	      by       running
       /usr/local/libexec/aox/installer.

       There is	only one required variable, namely db-password.

SECURITY NOTE
       Anyone who can read  archiveopteryx.conf	 can  see  the	database  user
       password, and use this password to read all mail	and in many cases even
       delete mail.

       By default, archiveopteryx.conf is readable only	by root.

SETTINGS
       All settings share a common format:

	      name = value # comment

       For the *-address variables, the	value may be  either  a	 hostname,  an
       IPv4  or	 IPv6  address,	the fully-qualified path to a Unix socket. For
       imap-address and	a few  other  variables,  the  empty  string  is  also
       allowed,	meaning	"all IPv4/6 addresses of this host".

   General Settings
       hostname
	      Most  of	the servers need to know the fully-qualified hostname.
	      The default is computed at runtime and is	normally acceptable.

	      Note that	if the name is "localhost", there may be problems with
	      TLS. An IMAP/POP/SMTP client may refuse a	server certificate for
	      "localhost" if it	already	has seen a different  certificate  for
	      "localhost". We strongly suggest using a different hostname.

       use-ipv4
	      decides  whether	the  various  servers accept IPv4 connections.
	      true by default.

       use-ipv6
	      decides whether the various  servers  accept  IPv6  connections.
	      true by default.

       undelete-time
	      is  the  number  of  days	a message can be undeleted after being
	      deleted, 49 by default.

       server-processes
	      is the number of processes started to  serve  IMAP/POP  clients.
	      This is 2	by default.

	      The  server-processes  setting  should  be about as large	as the
	      number of	CPU cores  available,  perhaps	a  little  larger.  We
	      advise asking info@aox.org in unusual cases.

   Database Access
       db     The  type	 of  database. The default, postgres, is currently the
	      only supported value.

       db-address
	      The address of the database server. The default is 127.0.0.1.

       db-port
	      The port number of the database server. The default is 5432.

       db-name
	      The name of the database to use. The default is archiveopteryx.

       db-schema
	      The name of the  schema  in  the	database  where	 the  database
	      objects  are  installed.	The  default is	public.	 It is safe to
	      ignore this setting.

       db-user
	      The name of the unprivileged  Postgres  user  that  the  servers
	      ordinarily use. The default is aox.

       db-password
	      The  database  password used for the db-user.  The default is an
	      empty string.

	      Unless  a	 password  is  specified,  Archiveopteryx  sets	 up  a
	      randomly-chosen password and writes it to	the configuration file
	      during installation.

       db-max-handles
	      The maximum number of database handles that  Archiveopteryx  may
	      open. The	default	is 4.

	      The  server creates one handle at	startup, and may create	others
	      if the load  justifies  it  (and	as  controlled	by  db-handle-
	      interval).   Note,  however, that	when running with security=on,
	      new database handles can be created only if you connect  to  the
	      server  using  TCP/IP, not via Unix sockets. In the latter case,
	      the server must use the first handle  throughout	its  lifetime,
	      since the	socket is no longer accessible after chroot.

       db-handle-interval
	      The  minimum  interval  (in seconds) between the creation	of new
	      database handles.	The default is 120.

   Logging
       log-address
	      The address of the log server. The default is 127.0.0.1.

       log-port
	      The port number at which logd(8) listens,	and to which the other
	      servers connect. The default is 2054.

       logfile
	      tells  logd(8)  where  to	 write log events. It may be set to an
	      absolute file name (starting with	'/'), or to  "syslog/category"
	      (e.g. "syslog/local2"), which logs via syslog(2),	or to -, which
	      causes everything	to be logged to	stdout.	 The default is	to log
	      to syslog/mail.

       logfile-mode
	      is  400  by default and controls the permissions used by logd(8)
	      if it creates logfile.  The format (three	octal digits)  is  the
	      same as that used	by chmod(1).

       log-level
	      may  be set to debug, info, significant, or error, in increasing
	      order of severity	(it is significant by default).	If  a  message
	      is  logged with this severity or above, the log server writes it
	      to the logfile immediately. Messages  with  lower	 severity  are
	      discarded.

   Security
       security
	      is   enabled   by	  default,  and	 should	 be  enabled  whenever
	      Archiveopteryx is	used in	production. It causes the  servers  to
	      lock  themselves	into  a	 chroot	jail and run with very limited
	      unix and database	privileges. Most  notably,  they  cannot  open
	      files or delete messages.

	      Turning  security	 off  has exactly one advantage: it simplifies
	      debugging.

       allow-plaintext-access
	      controls whether it is possible to read mail via an  unencrypted
	      connection.  The default value is	always.	 If this is changed to
	      localhost, plaintext connections are  permitted  only  from  the
	      host  itself.   If  it  is changed to never, TLS is necessary to
	      read mail.

       jail-directory
	      is /var/db/aox/jail by default. On startup, each	secure	server
	      uses  chroot(2) to jail themselves into this directory, to which
	      the jail-user should have	minimal	rights (only o+x permissions).

       jail-user
	      is the user name under which the servers	run,  and  is  aox  by
	      default.	On  startup, the servers change	UID to this user. This
	      user should not have read	or write access	to the jail directory.

       jail-group
	      is the group name	under which the	servers	run,  and  is  aox  by
	      default. On startup, the servers change GID to this user.

       entropy-source
	      is  the fully-qualified name of a	file that acts as a source for
	      random bytes, whenever they are needed (e.g.  SASL  challenges).
	      Set  to  /dev/urandom  by	 default.  If  this  is	instead	set to
	      /dev/random,  Archiveopteryx  never  uses	 anything  less	  than
	      perfectly	 random	 numbers. In this case,	make sure that there's
	      enough entropy, or else a	series of  rapid  login	 attempts  can
	      block the	entire server.

   User	Authentication
       http://archiveopteryx.org/sasl  describes  SASL	and  authentication in
       more detail.

       allow-plaintext-passwords
	      controls whether the servers permit plaintext passwords, and how
	      such  passwords are handled.  May	be set to always (which	is the
	      default) or never.   (Future  versions  of  Archiveopteryx  will
	      offer more settings.)

       auth-digest-md5
	      controls	 whether   the	 servers  offer	 the  digest-md5  SASL
	      mechanism.   Disabled  by	 default   due	 to   interoperability
	      problems.

       auth-cram-md5
	      controls	whether	the servers offer the cram-md5 SASL mechanism.
	      Enabled by default.

       auth-plain
	      controls	whether	 the  servers  offer   the   plain-text	  SASL
	      mechanism.  Enabled by default.

	      Note  that  disabling  auth-plain	 doesn't disable all plaintext
	      passwords, since SASL isn't always used.	To  disable  plaintext
	      passwords, use the allow-plaintext-passwords variable above.

       auth-anonymous
	      controls	whether	the servers offer anonymous login, disabled by
	      default.

   Mail	delivery
       use-lmtp
	      controls whether archiveopteryx(8) should	accept mail  via  LMTP
	      (RFC 2033). The default is enabled.

       lmtp-address
	      specifies	 the address where archiveopteryx(8) should listen for
	      LMTP connections,	and to which deliver(8)	 should	 connect.  The
	      default is 127.0.0.1.

       lmtp-port
	      specifies	 which	port  archiveopteryx(8)	 should	listen to, and
	      which port deliver(8) should connect to. The default is 2026.

       use-smtp
	      controls	whether	 archiveopteryx(8)  should  accept  mail   via
	      SMTP/ESMTP (RFC 2821/1869). SMTP is disabled by default.

       smtp-address
	      specifies	 the address where archiveopteryx(8) should listen for
	      SMTP connections The default is an empty string, which means all
	      available	IPv4 and IPv6 interfaces.

       smtp-port
	      specifies	 which	port  archiveopteryx(8)	 should	listen to. The
	      default is 25.

       use-subaddressing
	      controls whether messages	addressed to user+tag@example.org  are
	      accepted	for  delivery  to user@example.org (if the latter is a
	      valid recipient address).	The default is false.

       address-separator
	      is the character that separates the username from	the subaddress
	      in  a  localpart,	 e.g.  the  +  in  user+tag@example.org.   The
	      default, which you should	 not  need  to	change,	 is  +.	  This
	      setting is relevant only if use-subaddressing is true.

       soft-bounce
	      specifies	 whether  a  delivery  problem	causes a message to be
	      rejected permanently (soft-bounce	disabled) or queued at the MTA
	      (soft-bounce  enabled). This is enabled by default. We recommend
	      disabling	it when	you are	confident that mail delivery works.

       message-copy
	      specifies	whether	or not to keep filesystem copies  of  incoming
	      messages,	 e.g.  to  burn	 a  mail log to	CD/DVD regularly.  The
	      default value of none means that no copies are ever made.

	      Setting it to delivered keeps copies of all delivered  messages,
	      a	 value	of  errors keeps only those messages that could	not be
	      delivered	because	 of  errors,  and  all	keeps  copies  of  all
	      messages.

       message-copy-directory
	      specifies	 a  directory to which mail delivered via LMTP/SMTP is
	      copied,  if  message-copy	 is  set.   Its	  default   value   is
	      /var/db/aox/messages.   If  you  set use-security, message-copy-
	      directory	must be	a subdirectory of jail-directory.

	      If message-copy-directory	does not exist	or  is	not  writable,
	      Archiveopteryx logs an error at startup and exits.

	      Each  file in message-copy-directory contains one	or more	header
	      lines, namely Error, From	and To,	then an	empty line,  then  the
	      verbatim	received  mail message.	If there is an Error line, the
	      message was not delivered, and the rest of  the  line  describes
	      the problem.

	      The  file's  name	 is a unique string of numbers and hyphens. It
	      ends with	"-err" if there	was an	error  injecting  the  message
	      into the database.

   SMTP	Submission
       use-smtp-submit
	      controls	whether	archiveopteryx(8) should accept	mail via SMTP-
	      Submit (RFC 4409). The default is	enabled.

       check-sender-addresses
	      controls whether	archiveopteryx(8)  should  check  whether  the
	      sender  is authorised to use the addresses in the	message. From,
	      Sender, Return-Path  (SMTP  Mail	From)  and  Reply-To  are  all
	      checked. The default is disabled.

       submit-copy-to-sender
	      controls whether archiveopteryx(8) should	ensure that the	sender
	      receives a copy of outgoing mail.	The default is disabled.  This
	      can be used to ensure that all outgoing mail is archived.

	      If  the  sender  already receives	a copy of the message, submit-
	      copy-to-sender has no  effect.  Senders  will  not  receive  two
	      copies.  The  copy  is  always  sent  to	the user who sends the
	      message, even if the From	and/or Return-Path is  different.  The
	      sender's	 copy	will   be  delivered  through  the  configured
	      smarthost, as with any other outgoing message.

       smtp-submit-address
	      specifies	the address where archiveopteryx(8) should listen  for
	      Submit  connections.  The	 default,  an  empty  string, means to
	      listen on	all available IPv4 and IPv6 addresses.	127.0.0.1.

       smtp-submit-port
	      specifies	which port archiveopteryx(8)  should  listen  to.  The
	      default is 587.

       smarthost-address
	      specifies	 the address of	the SMTP server	which is used to relay
	      mail to remote recipients. The default is	127.0.0.1.

       smarthost-port
	      specifies	the port to use	when forwarding	mail to	 a  smarthost.
	      The  default  is	25.   (These  defaults	thus conflict with the
	      default values of	smtp-address and smtp-port  when  use-smtp  is
	      enabled.)

       use-smtps
	      controls	whether	 archiveopteryx(8)  should  accept SSL-wrapped
	      SMTP connections.	The default is false (and the use of  STARTTLS
	      with SMTP	Submit is strongly recommended instead).

       smtps-address
	      is  the  address	where  archiveopteryx(8)  listens for new SSL-
	      wrapped SMTP connections.	As for smtp-address, the default is an
	      empty string, which means	all available IPv4 and IPv6 addresses.

       smtps-port
	      is  the  port  where  archiveopteryx(8) accepts SSL-wrapped SMTP
	      connections, 465 by default.

   IMAP
       use-imap
	      must  be	enabled	  for	archiveopteryx(8)   to	 accept	  IMAP
	      connections. The default is true.

       imap-address
	      is   the	 address   where  archiveopteryx(8)  listens  for  new
	      connections. The default,	an empty string, means	to  listen  on
	      all available IPv4 and IPv6 addresses.

       imap-port
	      is  the port where archiveopteryx(8) accepts connections,	143 by
	      default.

       use-imaps
	      controls	whether	 archiveopteryx(8)  should  also  accept  SSL-
	      wrapped  IMAP  connections. The default is false (and the	use of
	      STARTTLS over the	standard IMAP  port  is	 strongly  recommended
	      instead).

       imaps-address
	      is  the  address	where  archiveopteryx(8)  listens for new SSL-
	      wrapped connections. As with imap-address,  the  default	is  an
	      empty string, which means	all available IPv4 and IPv6 addresses.

       imaps-port
	      is   the	 port	where  archiveopteryx(8)  accepts  SSL-wrapped
	      connections, 993 by default.

       use-imap-quota
	      must be enabled for archiveopteryx(8) to support the IMAP	 QUOTA
	      extension.  This	quota is not enforced and is recommended to be
	      disabled on large	mailboxes. The default is true.

   POP
       use-pop
	      must  be	enabled	  for	archiveopteryx(8)   to	 accept	  POP3
	      connections. The default is false.

       pop-address
	      is   the	 address   where  archiveopteryx(8)  listens  for  new
	      connections. The default,	an empty string, means	to  listen  on
	      all available IPv4 and IPv6 addresses.

       pop-port
	      is  the port where archiveopteryx(8) accepts connections,	110 by
	      default.

       use-pops
	      controls	whether	 archiveopteryx(8)  should  also  accept  SSL-
	      wrapped  POP  connections.  The default is false (and the	use of
	      STARTTLS over the	standard  POP  port  is	 strongly  recommended
	      instead).

       pops-address
	      is  the  address	where  archiveopteryx(8)  listens for new SSL-
	      wrapped connections. As with  pop-address,  the  default	is  an
	      empty string, which means	all available IPv4 and IPv6 addresses.

       pops-port
	      is   the	 port	where  archiveopteryx(8)  accepts  SSL-wrapped
	      connections, 995 by default.

   SIEVE
       use-sieve
	      controls whether or not the managesieve server is	 started.  The
	      default is enabled.

       managesieve-address
	      specifies	 the address where archiveopteryx(8) should listen for
	      connections. The default is an  empty  string,  which  means  to
	      listen on	all available IPv4 and IPv6 addresses.

       managesieve-port
	      specifies	 which	port  archiveopteryx(8)	 should	listen to. The
	      default is 2000.

   TLS
       use-tls
	      regulates	 whether  Archiveopteryx  supports  TLS	 at  all.  The
	      default is enabled.

       tls-certificate
	      is  the  absolute	 file  name  of	the TLS	private	key and	signed
	      certificate, e.g.	  /usr/local/etc/archiveopteryx/imap.p15.   If
	      tls-certificate  is  not specified, tlsproxy generates a private
	      key and a	self-signed certificate	at runtime and stores both  in
	      /usr/local/etc/archiveopteryx/automatic-key.pem.

       tls-certificate-label
	      is not used in 3.1.4.

SYNTAX
       The name	is case	insensitive, as	shown:

	      hostname = test1.example.com
	      HOSTNAME = mailserver.example.org

       The  value  is  case insensitive	wherever possible. (Exceptions include
       logfile,	db-user	and db-password.)

       There are three datatypes: Strings, numbers and toggles.

       Strings may be written as a single unquoted word	or quoted with	either
       single or double	quotes,	as shown in these three	examples:

	      db-password = single.word
	      db-password = "rock'n'roll" # a 12-character password
	      db-password = 'two words,	quoted'	# a 17-character one

       Only  single-line  strings can be used. Single-word strings may contain
       the characters a-z, A-Z,	0-9, dot, hyphen and slash.

       Numbers are integers not	smaller	than 0 and not larger than  2147483647
       (ie. 31-bit unsigned integers).

       Toggles	are  written  as a single word.	 Yes, true, on,	1, and enabled
       all mean	that the toggle	is enabled,  while  no,	 false,	 off,  0,  and
       disabled	unsurprisingly mean disabled. Toggles are case-insensitive.

	      use-lmtp = yes
	      crash-and-delete-all-the-mail = off

       Spaces  are allowed at the start	of the line, before and	after '=', and
       after the value.	Comments extend	from '#' to the	end of the line.

	      #	this is	a comment
	      hostname=stuff.nonsense.example.com # also a comment
	       logfile	  =   /dev/null# and this is a comment
	      #	empty lines are	ignored

AUTHOR
       The Archiveopteryx Developers, info@aox.org.

VERSION
       This man	page covers Archiveopteryx version 3.2.0, released 2014-03-10,
       http://archiveopteryx.org/3.2.0

SEE ALSO
       archiveopteryx(8), deliver(8), logd(8), http://archiveopteryx.org

aox.org				  2014-03-10		archiveopteryx.conf(5)

NAME | SYNOPSIS | DESCRIPTION | SECURITY NOTE | SETTINGS | SYNTAX | AUTHOR | VERSION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=archiveopteryx.conf&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help