X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=doc%2Fman1%2Fmailshears.1;fp=doc%2Fman1%2Fmailshears.1;h=de6ce682fa47f361853e73a2c84378213cb95321;hp=0000000000000000000000000000000000000000;hb=439b686d8a0907bf8c0fc86a50014754da380534;hpb=2ba18d3c7a998fdb05c8b81759c2540f83b44bff diff --git a/doc/man1/mailshears.1 b/doc/man1/mailshears.1 new file mode 100644 index 0000000..de6ce68 --- /dev/null +++ b/doc/man1/mailshears.1 @@ -0,0 +1,184 @@ +.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, + would be replaced by \(dqagendav\(dq, \(dqdavical\(dq, or so +on. Their meanings should be self-explanatory. +\# +.IP \(bu 2 +\fI_dbhost\fR (default: localhost) +\# +.IP \(bu +\fI_dbport\fR (default: 5432) +\# +.IP \(bu +\fI_dbopts\fR (default: empty) +\# +.IP \(bu +\fI_dbtty\fR (default: empty) +\# +.IP \(bu +\fI_dbuser\fR (default: 'postgres') +\# +.IP \(bu +\fI_dbpass\fR (default: empty) +\# +.IP \(bu +\fI_dbname\fR (default: ) +.P +An example configuration file, mailshears.example.conf.yml, is shipped +with mailshears. + +.SH BUGS + +Send bugs to michael@orlitzky.com.