doc/README

   1 1. What is it?
   2
   3 Mailshears prunes leftover mail-stuff.
   4
   5 If you manage your mail system through a database, deleting a user or
   6 domain from the database probably doesn't remove the physical mail
   7 files and directory structure. Other stuff can be left behind
   8 too. Mailshears helps you clean up.
   9
  10
  11 2. Requirements
  12
  13 Right now, mailshears is targeted at one type of setup:
  14
  15   * You're either using PostfixAdmin[1], or your users, domains, and
  16     aliases are stored using the PostfixAdmin schema. This wouldn't be
  17     too hard to change; on the other hand, it's a good schema.
  18
  19   * You use Dovecot[2] as your mailstore. This is an optional plugin, but
  20     if you use something else for your physical mail storage,
  21     mailshears can't help you. I would of course accept patches
  22     implementing new plugins.
  23
  24     In fact, at the moment, the "Dovecot" plugin doesn't really do
  25     anything Dovecot-specific. It just specializes the Mailstore to
  26     use a <domain>/<localpart> filesystem layout.  It would make a lot
  27     of sense to make that configurable, and just call it a
  28     FilesystemMailstore.
  29
  30   * You maybe use Roundcube[3] webmail. Another optional
  31     plugin. Specifically, roundcube-1.0.2 is supported at the moment.
  32
  33
  34 3. Installation
  35
  36 You put it in a directory somewhere, and run bin/mailshears. To make
  37 it do anything, you'll need to create a config file. The default is
  38 stored in mailshears.example.conf.yml; I suggest you copy that to
  39 $HOME/.mailshears.conf.yml and edit it to fit your environment.
  40
  41 You'll probably want to set up a cron job to run it every once in a
  42 while.
  43
  44
  45 4. How it works
  46
  47 Mailshears gets a list of users and domains from your PostfixAdmin
  48 database. It then delegates to the plugins. A plugin represents
  49 something that you would like to clean up. For example, the Dovecot
  50 plugin represents the physical mail files/directories. The Roundcube
  51 plugin represents a Roundcube SQL database.
  52
  53 Each plugin knows how to get a list of its own users and domains. If
  54 there's a user or domain in the plugin list that isn't in the
  55 PostfixAdmin list, then mailshears knows that you've deleted that user
  56 or domain from the database. So, it asks the plugin to clean up.
  57
  58 By default, it doesn't actually /do/ anything. There's a variable in
  59 the config file that you'll need to set before mailshears will touch
  60 your junk.
  61
  62
  63 5. How to report bugs
  64
  65 Email them to me at michael@orlitzky.com.
  66
  67
  68
  69 [1] http://postfixadmin.sourceforge.net/
  70
  71 [2] http://dovecot.org/
  72
  73 [3] http://www.roundcube.net/