--- /dev/null
+.TH mailshears 1
+
+.SH NAME
+mailshears \- mangle your mail garden
+.SH SYNOPSIS
+
+\fBmailshears\fR [ [\fBprune\fR] | [\fBrm\fR <\fItargets\fR>] | [\fBmv\fR <\fIsrc\fR> <\fIdst\fR>] ]
+
+.SH DESCRIPTION
+
+Managing a mail system with virtual users is annoying. The
+authoritative database of users is stored in one table, but every
+other piece of software keeps its own database of users.
+
+If you're using PostfixAdmin to manage your users, what happens when
+you delete a user? Chances are, nothing happens: mail directories are
+left behind, webmail preferences are saved, address books become
+orphaned. That's what mailshears was designed to fix. It cleans up
+after you remove a user or domain.
+
+Another stupidly difficult task is renaming a single email
+account. It's easy to move the user in one database, but then all of
+the remaining filesystem directories and databases need to be updated
+as well. Since these two tasks are related, mailshears does them both.
+
+It is assumed that you use the \fBPostfixAdmin schema\fI with
+\fBPostgreSQL\fR for your virtual users and domains. The rest of the
+functionality is provided by plugins. The following are supported at
+the moment:
+\#
+.IP \(bu 2
+Agendav (database)
+.IP \(bu
+DAViCal (datbase)
+.IP \(bu
+Dovecot (filesystem)
+.IP \(bu
+PostfixAdmin (database)
+.IP \(bu
+Roundcube (database)
+
+You are free to pick and choose the plugins that you need. The Dovecot
+plugin is a misnomer: as long as your mail is stored on disk in
+directories of the form \(dqexample.com/user\(dq, it should work for
+you.
+
+.SH MODES
+Mailshears has three modes, each of which takes different
+arguments. The default mode prunes leftover stuff.
+\#
+.IP \(bu 2
+\fBprune\fR
+
+The default \(dqprune\(dq mode removes leftovers from your mail
+system. The list of current users is collected from PostfixAdmin. The
+other plugins are then queried to find any extra users/domains to
+remove.
+\#
+.IP \(bu
+\fBrm\fR
+
+The \(dqrm\(dq mode removes a list of users and/or domains called
+\fItargets\fR.
+\#
+.IP \(bu
+\fBmv\fR
+
+The \(dqmv\(dq mode renames the \fIsrc\fR user to \fIdst\fR. The
+source user and destination domains must exist. Domains may not be
+moved.
+
+.SH EXAMPLES
+
+Pruning leftover users and domains:
+
+.nf
+.I $ mailshears
+mailshears, 2015-11-08 17:01:47 -0500 (Plugin: PrunePlugin)
+-----------------------------------------------------------
+AgendavPrune - Removed user booger@example.com.
+DavicalPrune - Removed user booger@example.com (Principal ID: 2).
+DovecotPrune - Removed user booger@example.com (/tmp/mailshears-test/example.com/booger).
+DovecotPrune - Removed user jeremy@example.com (/tmp/mailshears-test/example.com/jeremy).
+RoundcubePrune - Removed user booger@example.com (User ID: 2).
+.fi
+
+Removing a specific user:
+
+.nf
+.I $ mailshears rm adam@example.net
+mailshears, 2015-11-08 17:04:42 -0500 (Plugin: RmPlugin)
+--------------------------------------------------------
+AgendavRm - Removed user adam@example.net.
+DavicalRm - User adam@example.net not found.
+DovecotRm - Removed user adam@example.net (/tmp/mailshears-test/example.net/adam).
+PostfixadminRm - Removed user adam@example.net.
+RoundcubeRm - Removed user adam@example.net (User ID: 3).
+.fi
+
+Removing a domain:
+
+.nf
+.I $ mailshears rm example.net
+mailshears, 2015-11-08 17:05:42 -0500 (Plugin: RmPlugin)
+--------------------------------------------------------
+AgendavRm - Removed domain example.net.
+DavicalRm - Domain example.net not found.
+DovecotRm - Removed domain example.net (/tmp/mailshears-test/example.net).
+PostfixadminRm - Removed domain example.net.
+RoundcubeRm - Removed domain example.net.
+.fi
+
+Renaming an existing user:
+
+.nf
+.I $ mailshears mv alice@example.com alice@example.net
+mailshears, 2015-11-08 17:06:29 -0500 (Plugin: MvPlugin)
+--------------------------------------------------------
+AgendavMv - Source user alice@example.com not found.
+DavicalMv - Moved user alice@example.com (Principal ID: 1) to alice@example.net (Principal ID: 1).
+DovecotMv - Moved user alice@example.com (/tmp/mailshears-test/example.com/alice) to alice@example.net (/tmp/mailshears-test/example.net/alice).
+PostfixadminMv - Moved user alice@example.com to alice@example.net.
+RoundcubeMv - Moved user alice@example.com (User ID: 1) to alice@example.net (User ID: 1).
+.fi
+
+.SH CONFIGURATION
+
+Mailshears is configured with a YAML file containing all of the
+database settings and plugin information. This file should be located
+at ~/.mailshears.conf.yml, in your home directory.
+
+The following two settings are global:
+\#
+.IP \(bu 2
+\fIi_mean_business\fR (default: false) If this is set to false, mailshears
+will output some \(dqwhat if\(dq information but won't actually
+(re)move anything.
+\#
+.IP \(bu
+\fIplugins\fR (default: ['postfixadmin'])
+A list of enabled plugins. Valid values are \(dqagendav\(dq,
+\(dqdavical\(dq, \(dqdovecot\(dq, \(dqpostfixadmin\(dq, and
+\(dqroundcube\(dq.
+.P
+The \(dqdovecot\(dq plugin supports the following:
+\#
+.IP \(bu 2
+\fIdovecot_mail_root\fR (default: /tmp/mailshears-test)
+
+The location of your mail store. The domain directories should be
+located one level beneath dovecot_mail_root.
+.P
+The database plugins all have the same configutation options:
+connections settings preceded by the plugin name. So in what follows,
+<plugin> would be replaced by \(dqagendav\(dq, \(dqdavical\(dq, or so
+on. Their meanings should be self-explanatory.
+\#
+.IP \(bu 2
+\fI<plugin>_dbhost\fR (default: localhost)
+\#
+.IP \(bu
+\fI<plugin>_dbport\fR (default: 5432)
+\#
+.IP \(bu
+\fI<plugin>_dbopts\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbtty\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbuser\fR (default: 'postgres')
+\#
+.IP \(bu
+\fI<plugin>_dbpass\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbname\fR (default: <plugin>)
+.P
+An example configuration file, mailshears.example.conf.yml, is shipped
+with mailshears.
+
+.SH BUGS
+
+Send bugs to michael@orlitzky.com.
projects / mailshears.git / blobdiff