doc/archiveopteryx.man

   1 .\" Copyright 2009 The Archiveopteryx Developers <info@aox.org>
   2 .TH archiveopteryx 7 2009-07-13 aox.org "Archiveopteryx Documentation"
   3 .SH NAME
   4 Overview of Archiveopteryx.
   5 .SH SYNOPSIS
   6 .B /etc/init.d/archiveopteryx {start,stop}
   7 .PP
   8 .B $CONFIGDIR/*.conf
   9 .SH DESCRIPTION
  10 .nh
  11 .PP
  12 Archiveopteryx is a mail server system optimised for long-term storage
  13 and heavy access. It comprises a set of server programs that provide
  14 access to mail stored in a relational database (PostgreSQL).
  15 .SH "GETTING STARTED"
  16 The following five steps should suffice to install Archiveopteryx. If they
  17 don't, or if anything is unclear, more detailed instructions are
  18 available at http://www.archiveopteryx.org/installation
  19 .SS "1. Install Archiveopteryx"
  20 Usually, this is as simple as:
  21 .IP
  22 .B "apt-get install archiveopteryx"
  23 (on Debian)
  24 .br
  25 .B "portinstall archiveopteryx"
  26 (on FreeBSD)
  27 .PP
  28 http://www.archiveopteryx.org/installation explains what to do in
  29 other cases.
  30 .PP
  31 Use
  32 .IP
  33 .B $LIBDIR/archiveopteryx start
  34 .PP
  35 to start Archiveopteryx using the default configuration from
  36 .BR archiveopteryx.conf ,
  37 which tries hard to be sensible.
  38 .SS "2. Add a user"
  39 Run
  40 .IP
  41 aox add user
  42 .I name
  43 .I password
  44 .I address@domain
  45 .PP
  46 to create a username and password.
  47 .SS "3. Inject some test mail"
  48 You can use
  49 .BR deliver (8)
  50 to inject some mail you already have.
  51 .PP
  52 This command injects all the messages from a berkeley mbox file:
  53 .IP
  54 formail -s deliver yourname@domain < mbox
  55 .PP
  56 .SS "4. Check that you can read mail"
  57 The mail you just delivered is in your inbox, and you can read it with
  58 any IMAP or POP3 client.
  59 .SS "5. Configure your MTA"
  60 The normal way to deliver mail from your MTA into Archiveopteryx is via LMTP.
  61 By default, Archiveopteryx listens on 127.0.0.1 port 2026.
  62 .PP
  63 On aox.org we describe how to configure some common MTAs to work with
  64 Archiveopteryx. See e.g. http://www.archiveopteryx.org/postfix for
  65 .BR postfix (1).
  66 .SH ARCHITECTURE
  67 .PP
  68 Archiveopteryx consists of a number of frontend servers, each of which uses
  69 four backend servers:
  70 .IP RDBMS
  71 The RDBMS is where all the mail is stored. At present only PostgreSQL
  72 is supported.
  73 .IP logd
  74 The log server is an internal server which filters log entries so
  75 useful messages are logged while noise is suppressed.
  76 .IP tlsproxy
  77 This proxy performs TLS certificate and encryption services for the
  78 other servers. It's based on Cryptlib.
  79 .PP
  80 Each server is described more fully in its own man page:
  81 .BR logd (8),
  82 .BR postgres (1)
  83 and
  84 .BR tlsproxy (8)
  85 for the backends, and
  86 .BR archiveopteryx (8)
  87 for the frontend server, which serves IMAP, POP3, LMTP and/or SMTP and
  88 perhaps webmail.
  89 .PP
  90 Normally, there is one
  91 .BR logd (8)
  92 process running. In addition there will be at least one
  93 .BR postgres (1)
  94 process running. There may be an arbitrary number of frontend server
  95 and tlsproxy processes.
  96 .PP
  97 The servers use TCP to communicate internally, so they can be
  98 distributed across a server cluster. Generally, one host will run the
  99 database backend, one host (perhaps the same) will run
 100 .BR logd (8)
 101 and as many as required will run frontends.
 102 .PP
 103 The man pages for each server explain the use and configuration of
 104 each. See
 105 .BR archiveopteryx.conf (5)
 106 for more about configuring Archiveopteryx in general.
 107 .SH SECURITY
 108 All Archiveopteryx servers run in chroot directories.
 109 .PP
 110 The user-facing servers run in a special jail directory. They have
 111 neither read nor write access to this directory.
 112 .PP
 113 The internal servers, ie.
 114 .BR logd (8)
 115 and
 116 .BR tlsproxy (8),
 117 run chrooted to other directories. All of the servers close all open
 118 files at startup and drop root privileges. By default they run as user
 119 .IR $AOXUSER ,
 120 group
 121 .IR $AOXGROUP ,
 122 although these names can be changed using
 123 .BR archiveopteryx.conf (5).
 124 .PP
 125 The servers check that they lose prvileges as expected, and refuse to
 126 start if they're too privileged.
 127 .PP
 128 Note that
 129 .BR logd (8)
 130 must have permission to create the
 131 .IR logfile .
 132 .SH MAIL STORAGE
 133 Archiveopteryx does not store mail in the RFC-822 format. It parses each
 134 message upon delivery, and stores a normalized representation, optimized
 135 for fast and reliable search and categorization.
 136 .PP
 137 This offers the following advantages, among others:
 138 .IP Performance
 139 One example: Each address is stored exactly once, as Unicode and with
 140 RFC-2047 encoding undone. Finding all messages sent from/to a given
 141 name is extremely fast, because only a single SQL SELECT is necessary,
 142 and it accesses just two small tables.
 143 .IP "Long-term Stability"
 144 Archiveopteryx handles today's common syntax problems and stores the
 145 correct form in the database. Because of that, the mail reader which
 146 looks at old mail in the year 2020 will not need to be bug compatible
 147 with today's version of Microsoft Outlook.
 148 .IP "Scalability and Flexibility"
 149 Only the database size limits Archiveopteryx's capacity. Many other servers
 150 limit individual folders to 2GB (or less), or cannot support more than
 151 a few thousand subfolders/messages in a folder. With Archiveopteryx, you
 152 don't need to invent workarounds for such artificial limitations.
 153 .IP Robustness
 154 Because mail is stored normalized and parsed, large attachments are
 155 generally stored only once, and mail parsing exploits are rendered
 156 harmless before reaching the MUA. A movie clip sent to a hundred
 157 recipients is not a problem, because it's stored just once.
 158 .SH LICENSING
 159 Archiveopteryx is available under two
 160 licences, namely the OSL 3.0 license and a commercial software license.
 161 .PP
 162 The OSL 3.0 (see http://www.archiveopteryx.org/opensource) is a fairly
 163 restrictive open source license similar to the more well-known GNU
 164 licenses. It includes a disclaimer of responsibility.
 165 .PP
 166 Our commercial license offers more flexibility than the OSL and a full
 167 warranty. There are also extra services. Contact info@aox.org for
 168 more details, or see http://www.archiveopteryx.org/commercial
 169 .SH DEFAULTS
 170 The configurable file and directory names in this build are as follows:
 171 .IP SBINDIR
 172 (where servers live) is
 173 .IR $SBINDIR .
 174 .IP BINDIR
 175 (where other executables live) is
 176 .IR $BINDIR .
 177 .IP INITDIR
 178 (where the startup script lives) is
 179 .IR $INITDIR .
 180 .IP MANDIR
 181 (where manpages live) is
 182 .IR $MANDIR .
 183 .IP PIDFILEDIR
 184 (where pidfiles live) is
 185 .IR $PIDFILEDIR .
 186 .IP LIBDIR
 187 (where supporting files live) is
 188 .IR $LIBDIR .
 189 .IP JAILDIR
 190 (the working directory of the user-facing servers) is
 191 .IR $JAILDIR ,
 192 and can be overridden using the
 193 .I jail-directory
 194 variable in
 195 .BR archiveopteryx.conf (5).
 196 .IP CONFIGDIR
 197 (where the configuration files live) is
 198 .IR $CONFIGDIR .
 199 .IP LOGFILE
 200 (the full name of the logfile) is
 201 .IR $LOGFILE ,
 202 and can be overridden using the
 203 .I logfile
 204 variable in
 205 .BR archiveopteryx.conf (5).
 206 .PP
 207 These variables can be changed only by editing the file Jamsettings
 208 and recompiling Archiveopteryx. Jamsettings also contains some variables
 209 used only during compilation and/or installation, and some which
 210 provide defaults for
 211 .BR archiveopteryx.conf (5)
 212 settings.
 213 .SH FILES
 214 .IP $CONFIGDIR/archiveopteryx.conf
 215 contains the Archiveopteryx configuration.
 216 .IP $LIBDIR/automatic-key.p15
 217 contains a private key and self-signed certificate used by
 218 .BR tlsproxy (8)
 219 (and indirectly by the other servers).
 220 .SH AUTHOR
 221 The Archiveopteryx Developers, info@aox.org.
 222 .SH VERSION
 223 This man page covers Archiveopteryx version 3.1.2, released 2009-07-13,
 224 http://www.archiveopteryx.org/3.1.2
 225 .SH SEE ALSO
 226 .BR archiveopteryx (8),
 227 .BR archiveopteryx.conf (5),
 228 .BR deliver (8),
 229 .BR logd (8),
 230 .BR tlsproxy (8),
 231 http://www.archiveopteryx.org