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)
  33 .IP \(bu
  34 DAViCal (datbase)
  35 .IP \(bu
  36 Dovecot (filesystem)
  37 .IP \(bu
  38 PostfixAdmin (database)
  39 .IP \(bu
  40 Roundcube (database)
  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.