Update release date.
[aox:aox.git] / 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