mailshears 0.0.1

data/doc/TODO

@@ -0,0 +1,16 @@
+* There is essentially no error handling. We report errors, but we
+  don't fail when we see one. The main reason for this is that we
+  don't know when each plugin will be run. If the first plugin
+  encounters an error, we could quit right there. But what if the
+  third one fails after the first two succeed? We would need some kind
+  of rollback mechanism.
+
+  For "mv", a rollback is conceivable. But with "rm", there's no going
+  back. Maybe relying on the user to interpret the output and go
+  fix stuff himself is the best we can do?
+
+* Add OpenDKIM support.
+
+* Make a release.
+
+* Implement moving of domains.

data/doc/mailshears.example.conf.yml

@@ -0,0 +1,37 @@
+i_mean_business: false
+plugins: [agendav, davical, dovecot, postfixadmin, roundcube]
+
+agendav_dbhost: localhost
+agendav_dbport: 5432
+agendav_dbopts:
+agendav_dbtty:
+agendav_dbuser: postgres
+agendav_dbpass:
+agendav_dbname: agendav
+
+davical_dbhost: localhost
+davical_dbport: 5432
+davical_dbopts:
+davical_dbtty:
+davical_dbuser: postgres
+davical_dbpass:
+davical_dbname: davical
+
+dovecot_mail_root: /var/spool/mail/vhosts
+
+postfixadmin_dbhost: localhost
+postfixadmin_dbport: 5432
+postfixadmin_dbopts:
+postfixadmin_dbtty:
+postfixadmin_dbuser: postgres
+postfixadmin_dbpass:
+postfixadmin_dbname: postfixadmin
+
+roundcube_dbhost: localhost
+roundcube_dbport: 5432
+roundcube_dbopts:
+roundcube_dbtty:
+roundcube_dbuser: postgres
+roundcube_dbpass:
+roundcube_dbname: roundcube
+

data/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,
+<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.

data/lib/common/agendav_plugin.rb

@@ -0,0 +1,54 @@
+require 'common/plugin'
+require 'common/user'
+
+# Code that all Agendav plugins ({AgendavPrune}, {AgendavRm},
+# {AgendavMv}) share.
+module AgendavPlugin
+
+  # We implement the Plugin "interface."
+  include Plugin
+
+
+  # Initialize this Agendav {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
+  def initialize(cfg)
+    @db_hash = {
+      :host     => cfg.agendav_dbhost,
+      :port     => cfg.agendav_dbport,
+      :options  => cfg.agendav_dbopts,
+      :tty      => cfg.agendav_dbtty,
+      :dbname   => cfg.agendav_dbname,
+      :user     => cfg.agendav_dbuser,
+      :password => cfg.agendav_dbpass }
+  end
+
+
+  # Return a list of Agendav users.
+  #
+  # @return [Array<User>] a list of users contained in the
+  #   Agendav database.
+  #
+  def list_users()
+    users = []
+
+    connection = PG::Connection.new(@db_hash)
+
+    sql_query  = '(SELECT username FROM prefs)'
+    sql_query += 'UNION'
+    sql_query += '(SELECT user_from FROM shared);'
+
+    begin
+      connection.query(sql_query) do |result|
+        users = result.field_values('username')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return users.map{ |u| User.new(u) }
+  end
+
+end

data/lib/common/configuration.rb

@@ -0,0 +1,116 @@
+require 'yaml'
+
+# A configuration object that knows how to read options out of a file
+# in <tt>~/.mailshears.conf.yml</tt>. The configuration options can be
+# accessed via methods even though the internal representation is a
+# hash.
+#
+# === Examples
+#
+#   >> cfg = Configuration.new()
+#   >> cfg.i_mean_business()
+#   => true
+#
+class Configuration
+
+  # The default path to the user's configuration file.
+  USERCONF_PATH = ENV['HOME'] + '/.mailshears.conf.yml'
+
+  # The hash structure in which we store our configuration options
+  # internally.
+  @dict = {}
+
+
+  # Initialize a {Configuration} object with the config file at *path*.
+  #
+  # @param path [String] the path to the configuration file to
+  #   load. We check for a file named ".mailshears.conf.yml" in the
+  #   user's home directory by default.
+  #
+  def initialize(path = USERCONF_PATH)
+    cfg = default_configuration()
+
+    # Now, load the user configuration which will override the
+    # variables defined above.
+    begin
+      user_config = YAML.load(File.open(path))
+
+      # Write our own update() method for Ruby 1.8.
+      user_config.each do |key, value|
+        cfg[key] = value
+      end
+    rescue Errno::ENOENT
+      # If the user config file doesn't exist, whatever.
+    end
+
+    # Convert all of the keys to symbols.
+    cfg = cfg.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
+
+    @dict = cfg
+  end
+
+
+  # Replace all missing method calls with hash lookups. This lets us
+  # retrieve the values in our option hash by using methods named
+  # after the associated keys.
+  #
+  # @param sym [Symbol] the method that was called.
+  #
+  # @return [Object] the config file value associated with *sym*.
+  #
+  def method_missing(sym, *args)
+    return @dict[sym]
+  end
+
+
+  private;
+
+
+  # A default config hash.
+  #
+  # @return [Hash] sensible default configuration values.
+  #
+  def default_configuration()
+    d = {}
+
+    d['i_mean_business'] = false
+    d['plugins'] = ['postfixadmin']
+
+    d['agendav_dbhost'] = 'localhost'
+    d['agendav_dbport'] = 5432
+    d['agendav_dbopts'] = ''
+    d['agendav_dbtty'] = ''
+    d['agendav_dbuser'] = 'postgres'
+    d['agendav_dbpass'] = ''
+    d['agendav_dbname'] = 'agendav'
+
+    d['davical_dbhost'] = 'localhost'
+    d['davical_dbport'] = 5432
+    d['davical_dbopts'] = ''
+    d['davical_dbtty'] = ''
+    d['davical_dbuser'] = 'postgres'
+    d['davical_dbpass'] = ''
+    d['davical_dbname'] = 'davical'
+
+    d['dovecot_mail_root'] = '/tmp/mailshears-test'
+
+    d['postfixadmin_dbhost'] = 'localhost'
+    d['postfixadmin_dbport'] = 5432
+    d['postfixadmin_dbopts'] = ''
+    d['postfixadmin_dbtty'] = ''
+    d['postfixadmin_dbuser'] = 'postgres'
+    d['postfixadmin_dbpass'] = ''
+    d['postfixadmin_dbname'] = 'postfixadmin'
+
+    d['roundcube_dbhost'] = 'localhost'
+    d['roundcube_dbport'] = 5432
+    d['roundcube_dbopts'] = ''
+    d['roundcube_dbtty'] = ''
+    d['roundcube_dbuser'] = 'postgres'
+    d['roundcube_dbpass'] = ''
+    d['roundcube_dbname'] = 'roundcube'
+
+    return d
+  end
+
+end

data/lib/common/davical_plugin.rb

@@ -0,0 +1,104 @@
+require 'common/plugin'
+require 'common/user'
+
+# Code that all DAViCal plugins ({DavicalPrune}, {DavicalRm}, and
+# {DavicalMv}) will share.
+#
+module DavicalPlugin
+
+  # We implement the Plugin "interface."
+  include Plugin
+
+  # Initialize this DAViCal {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
+  def initialize(cfg)
+    @db_hash = {
+      :host     => cfg.davical_dbhost,
+      :port     => cfg.davical_dbport,
+      :options  => cfg.davical_dbopts,
+      :tty      => cfg.davical_dbtty,
+      :dbname   => cfg.davical_dbname,
+      :user     => cfg.davical_dbuser,
+      :password => cfg.davical_dbpass }
+  end
+
+
+  # Describe the given DAViCal user who is assumed to exist.
+  #
+  # @param user [User] the {User} object whose description we want.
+  #
+  # @return [String] a String describing the given *user* in terms
+  #   of his DAViCal "Principal ID".
+  #
+  def describe_user(user)
+    principal_id = self.get_principal_id(user)
+    return "Principal ID: #{principal_id}"
+  end
+
+
+  #
+  # Produce a list of DAViCal users.
+  #
+  # This method remains public for use in testing.
+  #
+  # @return [Array<User>] an array of {User} objects, one for each
+  #   user found in the DAViCal database.
+  #
+  def list_users()
+    usernames = []
+
+    connection = PG::Connection.new(@db_hash)
+
+    # User #1 is the super-user, and not tied to an email address.
+    sql_query = 'SELECT username FROM usr WHERE user_no > 1;'
+
+    begin
+      connection.query(sql_query) do |result|
+        usernames = result.field_values('username')
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return usernames.map{ |u| User.new(u) }
+  end
+
+
+  protected;
+
+
+  # Find the "Principal ID" of the given user.
+  #
+  # @param user [User] the user whose Principal ID we want.
+  #
+  # @return [Fixnum] an integer representing the user's Principal ID
+  #   that we obtained from the DAViCal database.
+  #
+  def get_principal_id(user)
+    principal_id = nil
+
+    connection = PG::Connection.new(@db_hash)
+
+    sql_query =  'SELECT principal.principal_id '
+    sql_query += 'FROM (principal INNER JOIN usr '
+    sql_query += '      ON principal.user_no = usr.user_no) '
+    sql_query += 'WHERE usr.username = $1;'
+
+    begin
+      connection.query(sql_query, [user.to_s()]) do |result|
+        if result.num_tuples > 0
+          principal_id = result[0]['principal_id']
+        end
+      end
+    ensure
+      # Make sure the connection gets closed even if the query explodes.
+      connection.close()
+    end
+
+    return principal_id
+  end
+
+end