doc/aox.man

   1 .\" Copyright 2009 The Archiveopteryx Developers <info@aox.org>
   2 .TH aox 8 2009-07-13 aox.org "Archiveopteryx Documentation"
   3 .SH NAME
   4 aox - management tool for Archiveopteryx.
   5 .SH SYNOPSIS
   6 .B $BINDIR/aox
   7 .I verb
   8 .I noun
   9 [
  10 .I options
  11 ] [
  12 .I arguments
  13 ]
  14 .PP
  15 .B aox help commands
  16 .PP
  17 .B aox help
  18 .I command
  19 .SH DESCRIPTION
  20 .nh
  21 .PP
  22 .B aox
  23 is a command-line program to perform various system administration
  24 tasks for Archiveopteryx.
  25 .PP
  26 Examples of such tasks are adding users, changing the access control
  27 for mailboxes, etc. In principle, everything one would want to do
  28 using a shell script should be doable using
  29 .BR aox .
  30 .SH COMMANDS
  31 .IP "aox start [-v]"
  32 Starts the Archiveopteryx servers in the correct order.
  33 .IP "aox stop [-v]"
  34 Stops the running Archiveopteryx servers in the correct order.
  35 .IP "aox restart [-v]"
  36 Restarts the servers in the correct order (currently equivalent to start
  37 && stop).
  38 .IP "aox show status [-v]"
  39 Displays a summary of the running Archiveopteryx servers.
  40 .IP "aox show configuration [-p -v] [variable-name]"
  41 Displays variables configured in
  42 .IR archiveopteryx.conf .
  43 .IP
  44 If a
  45 .I variable-name
  46 is specified, only that variable is displayed.
  47 .IP
  48 The -v flag displays only the value of the variable.
  49 .IP
  50 The -p flag restricts the results to variables whose value has been
  51 changed from the default.
  52 .IP
  53 .I configuration
  54 may be abbreviated as
  55 .IR cf .
  56 .IP "aox show build"
  57 Displays the build settings used for this installation (as configured
  58 in Jamsettings).
  59 .IP "aox show counts [-f]"
  60 Displays the number of rows in the most important tables, as well as the
  61 total size of the mail stored.
  62 .IP
  63 The -f flag causes it to collect slow-but-accurate statistics. Without
  64 it, by default, you get quick estimates (more accurate after VACUUM
  65 ANALYSE).
  66 .IP "aox show queue"
  67 Displays a list of all mail queued for delivery to a smarthost.
  68 .IP "aox show schema"
  69 Displays the revision of the existing database schema.
  70 .IP "aox upgrade schema [-n]"
  71 Checks that the database schema is one that this version of
  72 Archiveopteryx is compatible with, and updates it if needed.
  73 .IP
  74 The -n flag causes aox to perform the SQL statements for the schema
  75 upgrade and report on their status without COMMITing the transaction
  76 (i.e. see what the upgrade would do, without doing anything).
  77 .IP "aox update database"
  78 Performs any updates to the database contents which are too slow for
  79 inclusion in
  80 .IR "aox upgrade schema" .
  81 This command is meant to be used while the server is running. It does
  82 its work in small chunks, so it can be restarted at any time, and is
  83 tolerant of interruptions.
  84 .IP "aox tune database <mostly-writing|mostly-reading|advanced-reading>"
  85 Adjusts the database indices and configuration to suit expected usage
  86 patterns.
  87 .IP "aox list mailboxes [-d] [-o username] [pattern]"
  88 Displays a list of mailboxes matching the specified shell glob pattern.
  89 Without a pattern, all mailboxes are listed.
  90 .IP
  91 The -d flag includes deleted mailboxes in the list.
  92 .IP
  93 The "-o username" flag restricts the list to mailboxes owned by the
  94 specified user.
  95 .IP
  96 The -s flag shows a count of messages and the total size of the messages
  97 in each mailbox.
  98 .IP
  99 .I ls
 100 is an acceptable abbreviation for
 101 .IR list .
 102 .IP "aox list users [pattern]"
 103 Displays a list of users matching the specified shell glob pattern.
 104 Without a pattern, all users are listed.
 105 .IP "aox list aliases [pattern]"
 106 Displays a list of aliases where either the address or the target
 107 mailbox matches the specified shell glob pattern. Without a pattern,
 108 all aliases are listed.
 109 .IP "aox list rights <mailbox> [username]"
 110 Displays a list of users and the rights they have been granted to the
 111 specified mailbox. If a username is given, only that user's rights are
 112 displayed.
 113 .IP "aox add user <username> <password> <email-address>"
 114 .IP "aox add user -p <username> <email-address>"
 115 Creates a new Archiveopteryx user with the specified username, password, and
 116 email address. If the
 117 .I -p
 118 flag is specified, the password is read interactively, instead of from
 119 the command-line.
 120 .IP
 121 .I create
 122 and
 123 .I new
 124 are acceptable abbreviations for
 125 .IR add .
 126 .IP "aox delete user [-f] <username>"
 127 Deletes the specified Archiveopteryx user. If
 128 .I -f
 129 is specified, any mailboxes owned by the user are also deleted.
 130 .IP
 131 .I del
 132 and
 133 .I remove
 134 are acceptable abbreviations for
 135 .IR delete .
 136 .IP "aox change password <username> <new-password>"
 137 .IP "aox change password -p <username>"
 138 Changes the specified user's password. If the
 139 .I -p
 140 flag is specified, the password is read interactively, instead of from
 141 the command-line.
 142 .IP "aox change username <username> <new-username>"
 143 Renames the specified user.
 144 .IP "aox change address <username> <new-address>"
 145 Changes the specified user's email address.
 146 .IP "aox add mailbox <name> [username]"
 147 Creates a new mailbox with the specified name and, if a username is
 148 specified, owned by that user.
 149 .IP
 150 The mailbox
 151 .I name
 152 must be fully-qualified (begin with /), unless a
 153 .I username
 154 is specified, in which case unqualified names are assumed to be under
 155 the user's home directory.
 156 .IP "aox delete mailbox [-f] <name>"
 157 Deletes the specified mailbox.
 158 .IP
 159 If
 160 .I -f
 161 is specified, the mailbox and any messages it contains are permanently
 162 deleted. Otherwise, only empty mailboxes are deleted.
 163 .IP "aox add view <name> <source> <owner> <search>"
 164 Creates a new view mailbox which applies the specified search
 165 on the specified source mailbox. When a new message is added
 166 to the source, and it matches the search, it will automatically
 167 be added to the view as well.
 168 .IP "aox add alias <address> <mailbox>"
 169 Creates an alias that instructs the server to accept mail to the given
 170 .I address
 171 and deliver it to the specified
 172 .IR mailbox .
 173 .IP "aox delete alias <address>"
 174 Deletes an alias, if one exists, for the given
 175 .IR address .
 176 .IP "aox setacl [-d] <mailbox> <identifier> <rights>"
 177 Assigns the specified rights to the given identifier on the mailbox. If
 178 the rights begin with + or -, the specified rights are added to or
 179 subtracted from the existing rights; otherwise, the rights are set to
 180 exactly those given.
 181 .IP
 182 With -d, the identifier's rights are deleted altogether.
 183 .IP
 184 A summary of the changes made is displayed when the operation completes.
 185 .IP "aox undelete <mailbox> <search>"
 186 Searches for deleted messages in the specified mailbox and
 187 restores those that match the search.
 188 .PP
 189 Messages can be restored after an IMAP EXPUNGE or POP3 DELE
 190 until aox vacuum permanently removes them after the configured
 191 .IR undelete-time .
 192 .PP
 193 Example: aox undelete /users/fred/inbox from example.com
 194 .IP "aox vacuum"
 195 Permanently deletes messages that were marked for deletion more than
 196 .I undelete-time
 197 days ago, and removes any bodyparts that are no longer used.
 198 .IP
 199 This is not a replacement for running VACUUM ANALYSE on the database
 200 (either with vacuumdb or via autovacuum).
 201 .IP
 202 This command should be run (we suggest daily) via crontab.
 203 .IP "aox anonymise <file>"
 204 Reads a mail message from the named file, obscures most or all content
 205 and prints the result on stdout. The output resembles the original
 206 closely enough to be used in a bug report.
 207 .IP "aox reparse"
 208 Looks for messages that "arrived but could not be stored" and tries to
 209 parse them using workarounds that have been added more recently. If it
 210 succeeds, the new message is injected and the old one deleted.
 211 .IP "aox grant privileges <username>"
 212 makes sure that the named user has all the permissions needed for the
 213 db-user (i.e., and unprivileged user), and no more.
 214 .IP "aox check config"
 215 reads the configuration files and reports any problems that it finds.
 216 .SH OPTIONS
 217 The -v flag enables (slightly) more verbose diagnostic output wherever
 218 it is supported (see the descriptions of each command above).
 219 .SH EXAMPLES
 220 To add a user called "nirmala", whose password is "angstskrik" and
 221 whose main email address is "nirmala@example.com":
 222 .IP
 223 aox add user nirmala angstskrik nirmala@example.com
 224 .PP
 225 To change Nirmala's password to "temmelig hemmelig":
 226 .IP
 227 aox change password nirmala 'temmelig hemmelig'
 228 .PP
 229 To remove that user:
 230 .IP
 231 aox remove user nirmala
 232 .SH DIAGNOSTICS
 233 The return code of
 234 .B aox
 235 is zero if all goes well, and a non-zero in case of errors.
 236 .PP
 237 Diagnostics are logged using Archiveopteryx's
 238 .BR logd (8),
 239 just like the servers do. Disasters are also logged via stderr.
 240 .SH BUGS
 241 There is no command-line option to set the configuration file.
 242 .SH AUTHOR
 243 The Archiveopteryx Developers, info@aox.org.
 244 .SH VERSION
 245 This man page covers Archiveopteryx version 3.1.2, released 2009-07-13,
 246 http://www.archiveopteryx.org/3.1.2
 247 .SH SEE ALSO
 248 .BR archiveopteryx (8),
 249 .BR archiveopteryx.conf (5),
 250 .BR tlsproxy (8),
 251 http://www.archiveopteryx.org