lib,test: replace connection query() method with sync_exec{,_params}.
[mailshears.git] / doc / man1 / mailshears.1
1 .TH mailshears 1
2
3 .SH NAME
4 mailshears \- mangle your mail garden
5 .SH SYNOPSIS
6
7 \fBmailshears\fR [ [\fBprune\fR] | [\fBrm\fR <\fItargets\fR>] | [\fBmv\fR <\fIsrc\fR> <\fIdst\fR>] ]
8
9 .SH DESCRIPTION
10
11 Managing a mail system with virtual users is annoying. The
12 authoritative database of users is stored in one table, but every
13 other piece of software keeps its own database of users.
14
15 If you're using PostfixAdmin to manage your users, what happens when
16 you delete a user? Chances are, nothing happens: mail directories are
17 left behind, webmail preferences are saved, address books become
18 orphaned. That's what mailshears was designed to fix. It cleans up
19 after you remove a user or domain.
20
21 Another stupidly difficult task is renaming a single email
22 account. It's easy to move the user in one database, but then all of
23 the remaining filesystem directories and databases need to be updated
24 as well. Since these two tasks are related, mailshears does them both.
25
26 It is assumed that you use the \fBPostfixAdmin schema\fI with
27 \fBPostgreSQL\fR for your virtual users and domains. The rest of the
28 functionality is provided by plugins. The following are supported at
29 the moment:
30 \#
31 .IP \(bu 2
32 Agendav (database, v2.1.x)
33 .IP \(bu
34 DAViCal (database, v1.1.x)
35 .IP \(bu
36 Dovecot (filesystem, version irrelevant)
37 .IP \(bu
38 PostfixAdmin (database, v2.x)
39 .IP \(bu
40 Roundcube (database, v1.2.x)
41
42 You are free to pick and choose the plugins that you need. The Dovecot
43 plugin is a misnomer: as long as your mail is stored on disk in
44 directories of the form \(dqexample.com/user\(dq, it should work for
45 you.
46
47 .SH MODES
48 Mailshears has three modes, each of which takes different
49 arguments. The default mode prunes leftover stuff.
50 \#
51 .IP \(bu 2
52 \fBprune\fR
53
54 The default \(dqprune\(dq mode removes leftovers from your mail
55 system. The list of current users is collected from PostfixAdmin. The
56 other plugins are then queried to find any extra users/domains to
57 remove.
58 \#
59 .IP \(bu
60 \fBrm\fR
61
62 The \(dqrm\(dq mode removes a list of users and/or domains called
63 \fItargets\fR.
64 \#
65 .IP \(bu
66 \fBmv\fR
67
68 The \(dqmv\(dq mode renames the \fIsrc\fR user to \fIdst\fR. The
69 source user and destination domains must exist. Domains may not be
70 moved.
71
72 .SH EXAMPLES
73
74 Pruning leftover users and domains:
75
76 .nf
77 .I $ mailshears
78 mailshears, 2015-11-08 17:01:47 -0500 (Plugin: PrunePlugin)
79 -----------------------------------------------------------
80 AgendavPrune - Removed user booger@example.com.
81 DavicalPrune - Removed user booger@example.com (Principal ID: 2).
82 DovecotPrune - Removed user booger@example.com (/tmp/mailshears-test/example.com/booger).
83 DovecotPrune - Removed user jeremy@example.com (/tmp/mailshears-test/example.com/jeremy).
84 RoundcubePrune - Removed user booger@example.com (User ID: 2).
85 .fi
86
87 Removing a specific user:
88
89 .nf
90 .I $ mailshears rm adam@example.net
91 mailshears, 2015-11-08 17:04:42 -0500 (Plugin: RmPlugin)
92 --------------------------------------------------------
93 AgendavRm - Removed user adam@example.net.
94 DavicalRm - User adam@example.net not found.
95 DovecotRm - Removed user adam@example.net (/tmp/mailshears-test/example.net/adam).
96 PostfixadminRm - Removed user adam@example.net.
97 RoundcubeRm - Removed user adam@example.net (User ID: 3).
98 .fi
99
100 Removing a domain:
101
102 .nf
103 .I $ mailshears rm example.net
104 mailshears, 2015-11-08 17:05:42 -0500 (Plugin: RmPlugin)
105 --------------------------------------------------------
106 AgendavRm - Removed domain example.net.
107 DavicalRm - Domain example.net not found.
108 DovecotRm - Removed domain example.net (/tmp/mailshears-test/example.net).
109 PostfixadminRm - Removed domain example.net.
110 RoundcubeRm - Removed domain example.net.
111 .fi
112
113 Renaming an existing user:
114
115 .nf
116 .I $ mailshears mv alice@example.com alice@example.net
117 mailshears, 2015-11-08 17:06:29 -0500 (Plugin: MvPlugin)
118 --------------------------------------------------------
119 AgendavMv - Source user alice@example.com not found.
120 DavicalMv - Moved user alice@example.com (Principal ID: 1) to alice@example.net (Principal ID: 1).
121 DovecotMv - Moved user alice@example.com (/tmp/mailshears-test/example.com/alice) to alice@example.net (/tmp/mailshears-test/example.net/alice).
122 PostfixadminMv - Moved user alice@example.com to alice@example.net.
123 RoundcubeMv - Moved user alice@example.com (User ID: 1) to alice@example.net (User ID: 1).
124 .fi
125
126 .SH CONFIGURATION
127
128 Mailshears is configured with a YAML file containing all of the
129 database settings and plugin information. This file should be located
130 at ~/.mailshears.conf.yml, in your home directory.
131
132 The following two settings are global:
133 \#
134 .IP \(bu 2
135 \fIi_mean_business\fR (default: false) If this is set to false, mailshears
136 will output some \(dqwhat if\(dq information but won't actually
137 (re)move anything.
138 \#
139 .IP \(bu
140 \fIplugins\fR (default: ['postfixadmin'])
141 A list of enabled plugins. Valid values are \(dqagendav\(dq,
142 \(dqdavical\(dq, \(dqdovecot\(dq, \(dqpostfixadmin\(dq, and
143 \(dqroundcube\(dq.
144 .P
145 The \(dqdovecot\(dq plugin supports the following:
146 \#
147 .IP \(bu 2
148 \fIdovecot_mail_root\fR (default: /tmp/mailshears-test)
149
150 The location of your mail store. The domain directories should be
151 located one level beneath dovecot_mail_root.
152 .P
153 The database plugins all have the same configutation options:
154 connections settings preceded by the plugin name. So in what follows,
155 <plugin> would be replaced by \(dqagendav\(dq, \(dqdavical\(dq, or so
156 on. Their meanings should be self-explanatory.
157 \#
158 .IP \(bu 2
159 \fI<plugin>_dbhost\fR (default: localhost)
160 \#
161 .IP \(bu
162 \fI<plugin>_dbport\fR (default: 5432)
163 \#
164 .IP \(bu
165 \fI<plugin>_dbopts\fR (default: empty)
166 \#
167 .IP \(bu
168 \fI<plugin>_dbtty\fR (default: empty)
169 \#
170 .IP \(bu
171 \fI<plugin>_dbuser\fR (default: 'postgres')
172 \#
173 .IP \(bu
174 \fI<plugin>_dbpass\fR (default: empty)
175 \#
176 .IP \(bu
177 \fI<plugin>_dbname\fR (default: <plugin>)
178 .P
179 An example configuration file, mailshears.example.conf.yml, is shipped
180 with mailshears.
181
182 .SH BUGS
183
184 Send bugs to michael@orlitzky.com.