NAME

aox - management tool for Archiveopteryx.

SYNOPSIS

/usr/local/bin/aox verb noun [ options ] [ arguments ]

aox help commands

aox help command

DESCRIPTION

aox is a command-line program to perform various system administration tasks for Archiveopteryx.

Examples of such tasks are adding users, changing the access control for mailboxes, etc. In principle, everything one would want to do using a shell script should be doable using aox.

COMMANDS

aox start [-v]: Starts the Archiveopteryx servers in the correct order.
aox stop [-v]: Stops the running Archiveopteryx servers in the correct order.
aox restart [-v]: Restarts the servers in the correct order (currently equivalent to start && stop).
aox show status [-v]: Displays a summary of the running Archiveopteryx servers.
aox show configuration [-p -v] [variable-name]: Displays variables configured in archiveopteryx.conf.
: If a variable-name is specified, only that variable is displayed.
: The -v flag displays only the value of the variable.
: The -p flag restricts the results to variables whose value has been changed from the default.
: configuration may be abbreviated as cf.
aox show build: Displays the build settings used for this installation (as configured in Jamsettings).
aox show counts [-f]: Displays the number of rows in the most important tables, as well as the total size of the mail stored.
: The -f flag causes it to collect slow-but-accurate statistics. Without it, by default, you get quick estimates (more accurate after VACUUM ANALYSE).
aox show queue: Displays a list of all mail queued for delivery to a smarthost.
aox show schema: Displays the revision of the existing database schema.
aox upgrade schema [-n]: Checks that the database schema is one that this version of Archiveopteryx is compatible with, and updates it if needed.
: The -n flag causes aox to perform the SQL statements for the schema upgrade and report on their status without COMMITing the transaction (i.e. see what the upgrade would do, without doing anything).
aox update database: Performs any updates to the database contents which are too slow for inclusion in aox upgrade schema. This command is meant to be used while the server is running. It does its work in small chunks, so it can be restarted at any time, and is tolerant of interruptions.
aox tune database <mostly-writing|mostly-reading|advanced-reading>: Adjusts the database indices and configuration to suit expected usage patterns.
aox list mailboxes [-d] [-o username] [pattern]: Displays a list of mailboxes matching the specified shell glob pattern. Without a pattern, all mailboxes are listed.
: The -d flag includes deleted mailboxes in the list.
: The "-o username" flag restricts the list to mailboxes owned by the specified user.
: The -s flag shows a count of messages and the total size of the messages in each mailbox.
: ls is an acceptable abbreviation for list.
aox list users [pattern]: Displays a list of users matching the specified shell glob pattern. Without a pattern, all users are listed.
aox list aliases [pattern]: Displays a list of aliases where either the address or the target mailbox matches the specified shell glob pattern. Without a pattern, all aliases are listed.
aox list rights <mailbox> [username]: Displays a list of users and the rights they have been granted to the specified mailbox. If a username is given, only that user's rights are displayed.
aox add user <username> <password> <email-address>
aox add user -p <username> <email-address>: Creates a new Archiveopteryx user with the specified username, password, and email address. If the -p flag is specified, the password is read interactively, instead of from the command-line.
: create and new are acceptable abbreviations for add.
aox delete user [-f] <username>: Deletes the specified Archiveopteryx user. If -f is specified, any mailboxes owned by the user are also deleted.
: del and remove are acceptable abbreviations for delete.
aox change password <username> <new-password>
aox change password -p <username>: Changes the specified user's password. If the -p flag is specified, the password is read interactively, instead of from the command-line.
aox change username <username> <new-username>: Renames the specified user.
aox change address <username> <new-address>: Changes the specified user's email address.
aox add mailbox <name> [username]: Creates a new mailbox with the specified name and, if a username is specified, owned by that user.
: The mailbox name must be fully-qualified (begin with /), unless a username is specified, in which case unqualified names are assumed to be under the user's home directory.
aox delete mailbox [-f] <name>: Deletes the specified mailbox.
: If -f is specified, the mailbox and any messages it contains are permanently deleted. Otherwise, only empty mailboxes are deleted.
aox add view <name> <source> <owner> <search>: Creates a new view mailbox which applies the specified search on the specified source mailbox. When a new message is added to the source, and it matches the search, it will automatically be added to the view as well.
aox add alias <address> <mailbox>: Creates an alias that instructs the server to accept mail to the given address and deliver it to the specified mailbox.
aox delete alias <address>: Deletes an alias, if one exists, for the given address.
aox setacl [-d] <mailbox> <identifier> <rights>: Assigns the specified rights to the given identifier on the mailbox. If the rights begin with + or -, the specified rights are added to or subtracted from the existing rights; otherwise, the rights are set to exactly those given.
: With -d, the identifier's rights are deleted altogether.
: A summary of the changes made is displayed when the operation completes.
aox undelete <mailbox> <search>: Searches for deleted messages in the specified mailbox and restores those that match the search.

Messages can be restored after an IMAP EXPUNGE or POP3 DELE until aox vacuum permanently removes them after the configured undelete-time.

Example: aox undelete /users/fred/inbox from example.com

aox vacuum: Permanently deletes messages that were marked for deletion more than undelete-time days ago, and removes any bodyparts that are no longer used.
: This is not a replacement for running VACUUM ANALYSE on the database (either with vacuumdb or via autovacuum).
: This command should be run (we suggest daily) via crontab.
aox anonymise <file>: Reads a mail message from the named file, obscures most or all content and prints the result on stdout. The output resembles the original closely enough to be used in a bug report.
aox reparse: Looks for messages that "arrived but could not be stored" and tries to parse them using workarounds that have been added more recently. If it succeeds, the new message is injected and the old one deleted.
aox grant privileges <username>: makes sure that the named user has all the permissions needed for the db-user (i.e., and unprivileged user), and no more.
aox check config: reads the configuration files and reports any problems that it finds.

OPTIONS

The -v flag enables (slightly) more verbose diagnostic output wherever it is supported (see the descriptions of each command above).

EXAMPLES

To add a user called "nirmala", whose password is "angstskrik" and whose main email address is "nirmala@example.com":

: aox add user nirmala angstskrik nirmala@example.com

To change Nirmala's password to "temmelig hemmelig":

: aox change password nirmala 'temmelig hemmelig'

To remove that user:

: aox remove user nirmala

DIAGNOSTICS

The return code of aox is zero if all goes well, and a non-zero in case of errors.

Diagnostics are logged using Archiveopteryx's logd(8), just like the servers do. Disasters are also logged via stderr.

BUGS

There is no command-line option to set the configuration file.

AUTHOR

The Archiveopteryx Developers, info@aox.org.

VERSION

This man page covers Archiveopteryx version 3.2.0, released 2013-12-02, http://archiveopteryx.org/3.1.3