Remove mv_domain() from MvPlugin.
[mailshears.git] / 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/