From 439b686d8a0907bf8c0fc86a50014754da380534 Mon Sep 17 00:00:00 2001 From: Michael Orlitzky Date: Sun, 8 Nov 2015 17:34:45 -0500 Subject: [PATCH] Add a man page. Remove the outdated README and get rid of that TODO item. Update the gemspec with the description in the man page. --- doc/README | 73 ----------------- doc/TODO | 4 - doc/man1/mailshears.1 | 184 ++++++++++++++++++++++++++++++++++++++++++ mailshears.gemspec | 19 ++++- 4 files changed, 201 insertions(+), 79 deletions(-) delete mode 100644 doc/README create mode 100644 doc/man1/mailshears.1 diff --git a/doc/README b/doc/README deleted file mode 100644 index 4657422..0000000 --- a/doc/README +++ /dev/null @@ -1,73 +0,0 @@ -1. What is it? - -Mailshears prunes leftover mail-stuff. - -If you manage your mail system through a database, deleting a user or -domain from the database probably doesn't remove the physical mail -files and directory structure. Other stuff can be left behind -too. Mailshears helps you clean up. - - -2. Requirements - -Right now, mailshears is targeted at one type of setup: - - * You're either using PostfixAdmin[1], or your users, domains, and - aliases are stored using the PostfixAdmin schema. This wouldn't be - too hard to change; on the other hand, it's a good schema. - - * You use Dovecot[2] as your mailstore. This is an optional plugin, but - if you use something else for your physical mail storage, - mailshears can't help you. I would of course accept patches - implementing new plugins. - - In fact, at the moment, the "Dovecot" plugin doesn't really do - anything Dovecot-specific. It just specializes the Mailstore to - use a / filesystem layout. It would make a lot - of sense to make that configurable, and just call it a - FilesystemMailstore. - - * You maybe use Roundcube[3] webmail. Another optional - plugin. Specifically, roundcube-1.0.2 is supported at the moment. - - -3. Installation - -You put it in a directory somewhere, and run bin/mailshears. To make -it do anything, you'll need to create a config file. The default is -stored in mailshears.example.conf.yml; I suggest you copy that to -$HOME/.mailshears.conf.yml and edit it to fit your environment. - -You'll probably want to set up a cron job to run it every once in a -while. - - -4. How it works - -Mailshears gets a list of users and domains from your PostfixAdmin -database. It then delegates to the plugins. A plugin represents -something that you would like to clean up. For example, the Dovecot -plugin represents the physical mail files/directories. The Roundcube -plugin represents a Roundcube SQL database. - -Each plugin knows how to get a list of its own users and domains. If -there's a user or domain in the plugin list that isn't in the -PostfixAdmin list, then mailshears knows that you've deleted that user -or domain from the database. So, it asks the plugin to clean up. - -By default, it doesn't actually /do/ anything. There's a variable in -the config file that you'll need to set before mailshears will touch -your junk. - - -5. How to report bugs - -Email them to me at michael@orlitzky.com. - - - -[1] http://postfixadmin.sourceforge.net/ - -[2] http://dovecot.org/ - -[3] http://www.roundcube.net/ diff --git a/doc/TODO b/doc/TODO index b7ea257..ce3024c 100644 --- a/doc/TODO +++ b/doc/TODO @@ -11,10 +11,6 @@ * Add OpenDKIM support. -* Write a man page. - -* Update the README. - * Make a release. * Implement moving of domains. 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. diff --git a/mailshears.gemspec b/mailshears.gemspec index acc4635..6af744f 100644 --- a/mailshears.gemspec +++ b/mailshears.gemspec @@ -7,9 +7,24 @@ Gem::Specification.new do |s| s.email = ['michael@orlitzky.com'] s.homepage = 'http://michael.orlitzky.com/code/mailshears.php' s.summary = 'Prune unused mail directories.' - s.description = s.summary - s.license = 'AGPL-3' + s.description = <<-EOF + 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. + EOF + + s.license = 'AGPL-3' s.required_rubygems_version = '>= 1.3.6' # If you have runtime dependencies, add them here -- 2.44.2