4 mailshears \- mangle your mail garden
7 \fBmailshears\fR [--help] [ [\fBprune\fR] | [\fBrm\fR <\fItargets\fR>] | [\fBmv\fR <\fIsrc\fR> <\fIdst\fR>] ]
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.
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.
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.
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
32 DAViCal (database, v1.1.x)
34 Dovecot (filesystem, version irrelevant)
36 PostfixAdmin (database, v2.x)
38 Roundcube (database, v1.2.x)
40 You are free to pick and choose the plugins that you need. The Dovecot
41 plugin is a misnomer: as long as your mail is stored on disk in
42 directories of the form \(dqexample.com/user\(dq, it should work for
46 Mailshears has three modes, each of which takes different
47 arguments. The default mode prunes leftover stuff.
52 The default \(dqprune\(dq mode removes leftovers from your mail
53 system. The list of current users is collected from PostfixAdmin. The
54 other plugins are then queried to find any extra users/domains to
60 The \(dqrm\(dq mode removes a list of users and/or domains called
66 The \(dqmv\(dq mode renames the \fIsrc\fR user to \fIdst\fR. The
67 source user and destination domains must exist. Domains may not be
72 Pruning leftover users and domains:
76 mailshears, 2015-11-08 17:01:47 -0500 (Plugin: PrunePlugin)
77 -----------------------------------------------------------
78 DavicalPrune - Removed user booger@example.com (Principal ID: 2).
79 DovecotPrune - Removed user booger@example.com (/tmp/mailshears-test/example.com/booger).
80 DovecotPrune - Removed user jeremy@example.com (/tmp/mailshears-test/example.com/jeremy).
81 RoundcubePrune - Removed user booger@example.com (User ID: 2).
84 Removing a specific user:
87 .I $ mailshears rm adam@example.net
88 mailshears, 2015-11-08 17:04:42 -0500 (Plugin: RmPlugin)
89 --------------------------------------------------------
90 DavicalRm - User adam@example.net not found.
91 DovecotRm - Removed user adam@example.net (/tmp/mailshears-test/example.net/adam).
92 PostfixadminRm - Removed user adam@example.net.
93 RoundcubeRm - Removed user adam@example.net (User ID: 3).
99 .I $ mailshears rm example.net
100 mailshears, 2015-11-08 17:05:42 -0500 (Plugin: RmPlugin)
101 --------------------------------------------------------
102 DavicalRm - Domain example.net not found.
103 DovecotRm - Removed domain example.net (/tmp/mailshears-test/example.net).
104 PostfixadminRm - Removed domain example.net.
105 RoundcubeRm - Removed domain example.net.
108 Renaming an existing user:
111 .I $ mailshears mv alice@example.com alice@example.net
112 mailshears, 2015-11-08 17:06:29 -0500 (Plugin: MvPlugin)
113 --------------------------------------------------------
114 DavicalMv - Moved user alice@example.com (Principal ID: 1) to alice@example.net (Principal ID: 1).
115 DovecotMv - Moved user alice@example.com (/tmp/mailshears-test/example.com/alice) to alice@example.net (/tmp/mailshears-test/example.net/alice).
116 PostfixadminMv - Moved user alice@example.com to alice@example.net.
117 RoundcubeMv - Moved user alice@example.com (User ID: 1) to alice@example.net (User ID: 1).
122 Mailshears is configured with a YAML file containing all of the
123 database settings and plugin information. This file should be located
124 at \fI$XDG_CONFIG_HOME\fR/mailshears/mailshears.conf.yml, where
125 \fI$XDG_CONFIG_HOME\fR defaults to \fI$HOME\fR/.config.
127 The following two settings are global:
130 \fIi_mean_business\fR (default: false) If this is set to false, mailshears
131 will output some \(dqwhat if\(dq information but won't actually
135 \fIplugins\fR (default: ['postfixadmin'])
136 A list of enabled plugins. Valid values are \(dqdavical\(dq,
137 \(dqdovecot\(dq, \(dqpostfixadmin\(dq, and \(dqroundcube\(dq.
139 The \(dqdovecot\(dq plugin supports the following:
142 \fIdovecot_mail_root\fR (default: /tmp/mailshears-test)
144 The location of your mail store. The domain directories should be
145 located one level beneath dovecot_mail_root.
147 The database plugins all have the same configutation options:
148 connections settings preceded by the plugin name. So in what follows,
149 <plugin> would be replaced by \(dqdavical\(dq, for example. Their
150 meanings should be self-explanatory.
153 \fI<plugin>_dbhost\fR (default: localhost)
156 \fI<plugin>_dbport\fR (default: 5432)
159 \fI<plugin>_dbopts\fR (default: empty)
162 \fI<plugin>_dbuser\fR (default: 'postgres')
165 \fI<plugin>_dbpass\fR (default: empty)
168 \fI<plugin>_dbname\fR (default: <plugin>)
170 An example configuration file, mailshears.example.conf.yml, is shipped
175 Send bugs to michael@orlitzky.com.