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
  32 DAViCal (database, v1.1.x)
  33 .IP \(bu
  34 Dovecot (filesystem, version irrelevant)
  35 .IP \(bu
  36 PostfixAdmin (database, v2.x)
  37 .IP \(bu
  38 Roundcube (database, v1.2.x)
  39
  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
  43 you.
  44
  45 .SH MODES
  46 Mailshears has three modes, each of which takes different
  47 arguments. The default mode prunes leftover stuff.
  48 \#
  49 .IP \(bu 2
  50 \fBprune\fR
  51
  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
  55 remove.
  56 \#
  57 .IP \(bu
  58 \fBrm\fR
  59
  60 The \(dqrm\(dq mode removes a list of users and/or domains called
  61 \fItargets\fR.
  62 \#
  63 .IP \(bu
  64 \fBmv\fR
  65
  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
  68 moved.
  69
  70 .SH EXAMPLES
  71
  72 Pruning leftover users and domains:
  73
  74 .nf
  75 .I $ mailshears
  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).
  82 .fi
  83
  84 Removing a specific user:
  85
  86 .nf
  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).
  94 .fi
  95
  96 Removing a domain:
  97
  98 .nf
  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.
 106 .fi
 107
 108 Renaming an existing user:
 109
 110 .nf
 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).
 118 .fi
 119
 120 .SH CONFIGURATION
 121
 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.
 126
 127 The following two settings are global:
 128 \#
 129 .IP \(bu 2
 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
 132 (re)move anything.
 133 \#
 134 .IP \(bu
 135 \fIplugins\fR (default: ['postfixadmin'])
 136 A list of enabled plugins. Valid values are \(dqdavical\(dq,
 137 \(dqdovecot\(dq, \(dqpostfixadmin\(dq, and \(dqroundcube\(dq.
 138 .P
 139 The \(dqdovecot\(dq plugin supports the following:
 140 \#
 141 .IP \(bu 2
 142 \fIdovecot_mail_root\fR (default: /tmp/mailshears-test)
 143
 144 The location of your mail store. The domain directories should be
 145 located one level beneath dovecot_mail_root.
 146 .P
 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.
 151 \#
 152 .IP \(bu 2
 153 \fI<plugin>_dbhost\fR (default: localhost)
 154 \#
 155 .IP \(bu
 156 \fI<plugin>_dbport\fR (default: 5432)
 157 \#
 158 .IP \(bu
 159 \fI<plugin>_dbopts\fR (default: empty)
 160 \#
 161 .IP \(bu
 162 \fI<plugin>_dbuser\fR (default: 'postgres')
 163 \#
 164 .IP \(bu
 165 \fI<plugin>_dbpass\fR (default: empty)
 166 \#
 167 .IP \(bu
 168 \fI<plugin>_dbname\fR (default: <plugin>)
 169 .P
 170 An example configuration file, mailshears.example.conf.yml, is shipped
 171 with mailshears.
 172
 173 .SH BUGS
 174
 175 Send bugs to michael@orlitzky.com.