imapfilter/imapfilter/imapfilter.1

.Dd February 9, 2004
.Dt IMAPFILTER 1
.Os
.Sh NAME
.Nm imapfilter
.Nd mail filter
.Sh SYNOPSIS
.Nm
.Op Fl hkpqvV
.Op Fl c Ar configfile
.Op Fl d Ar interval
.Op Fl l Ar logfile
.Sh DESCRIPTION
.Nm
is a mail filtering utility.  It connects to remote mail servers using the
Internet Message Access Protocol (IMAP) and processes messages based on
the definition of filter rules.  It can be used to delete, sort, etc.
messages residing in multiple mailboxes at different mail servers.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl D
Debug mode; creates a temporary file name in
.Pa /tmp/imapfilter.XXXX ,
where debugging messages about the program's progress are printed.
.It Fl V
Displays program's version.
.It Fl c Ar configfile
Configuration file to read settings and filters from.  The default is
.Pa $HOME/.imapfilterrc .
.It Fl d Ar interval
Runs imapfilter at daemon mode and repeatedly polls at the specified interval.
.It Fl k
Kills any other running instances of
.Nm
and removes the lockfile left from a past session.
.It Fl l Ar logfile
File that contains logs of error messages
.Nm
produces and optionally information about the deleted messages.
.It Fl p
Enters the interactive encrypted passwords editor.
.It Fl q
Quiet mode; prints less detailed information about the program's actions.
Multiple
.Fl q
options decrease the verbosity.  The minimum is -2.
.It Fl v
Verbose mode; prints more detailed information about the program's actions.
Multiple
.Fl v
options increase the verbosity.  The maximum is 2.
.El
.Pp
While running in daemon mode, if the SIGUSR1 signal is send,
.Nm
wakes up from its sleep phase and rereads its configuration file.
.Sh AUTHENTICATION AND ENCRYPTION
.Nm
supports the Challenge-Response Authentication Mechanism (CRAM) for
user authentication.  The authentication type associated with CRAM is
CRAM-MD5.
.Nm
will authenticate using CRAM-MD5, if the mail server supports this
authentication method, instead of plaintext password LOGIN.
.Pp
.Nm
supports encryption of the connection with the IMAP STARTTLS extension,
and will try to negotiate a TLS connection if the mail server supports it.
.Pp
.Nm
supports imaps (port 993) SSL/TLS connections.  The user must manually enable
imaps SSL/TLS connections and specify the SSL/TLS protocol to be negotiated,
through
.Nm Ap s
configuration file.
.Sh PASSWORD EDITOR
.Nm
has the capability to encrypt the accounts' passwords and store them
separately at
.Pa $HOME/.imapfilter/passwords .
These passwords are encrypted with a master password, supplied by
the user.  The Blowfish block cipher with a 128bit key in CBC mode
is used to do the encryption.  The master password is entered each
time
.Nm
is run, in order to decrypt the password file and retrieve the
actual passwords of the user's IMAP mail accounts.
.Pp
First of all, while defining accounts in the
.Nm
configuration file, the user must specify only the username and server
in those accounts he/she wishes to encrypt the passwords before storage.
Then, one can enter the interactive passwords' editor by using the
.Fl p
option.
.Pp
After entering the interactive password editor, a command line prompt
is used to manage the passwords.  The available commands are:
.Bl -tag -width Ds
.It Cm c
Clears a password from an account.  It takes as an argument a
number, specifying which account's password should be cleared.
.It Cm e
Edits an account's password entry.  It takes as an argument a
number, the account's password to be edited.
.It Cm h
Prints a brief help message of all commands.
.It Cm l
Lists all accounts.  Specifically a number that describes the
account, the hostname of the IMAP mail server, the username
and the password (if one is already specified).
.It Cm p
Changes the master password, used to encrypt all other passwords.
.It Cm q
Quits the password editor without saving changes.
.It Cm w
Saves changes.
.It Cm x
Saves changes and exits the password editor.
.El
.Sh INTERNAL DETAILS
After
.Nm
reads the configuration file and creates all necessary data structures, it
starts by going through the list of accounts.  It connects to the servers
specified, in the order they were defined in the configuration file with
the
.Ar account
keyword.  It then goes through the list of mailboxes belonging to the server,
in the order they were defined in the configuration file with the
.Ar folder
keyword.  For each mailbox it applies the filters that were specified for it,
in the order they were defined in the configuration file using the
.Ar job
keyword.  This process continues until the last account, mailbox and filter.
.Sh ENVIRONMENT
.Bl -tag -width Ds
.It Ev HOME
User's home directory.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa $HOME/.imapfilterrc
Default configuration file.
.It Pa $HOME/.imapfilter/passwords
File where the encrypted passwords are stored.
.It Pa $HOME/.imapfilter/certificates
File where the SSL/TLS certificates are stored.
.It Pa $HOME/.imapfilter/lock
Lock file containing the PID of
.Nm .
.It Pa /tmp/imapfilter.XXXX
Debug file.
.El
.Sh SEE ALSO
.Xr imapfilterrc 5
.Sh STANDARDS
.Bl -tag -width Ds
.It IMAP4rev1:
RFC 3501, RFC 2683, RFC 2595, RFC 2342, RFC 2195
.El
.Sh AUTHORS
.An Lefteris Chatzibarbas Aq lefcha@hellug.gr
1	.Dd February 9, 2004
2	.Dt IMAPFILTER 1
3	.Os
4	.Sh NAME
5	.Nm imapfilter
6	.Nd mail filter
7	.Sh SYNOPSIS
8	.Nm
9	.Op Fl hkpqvV
10	.Op Fl c Ar configfile
11	.Op Fl d Ar interval
12	.Op Fl l Ar logfile
13	.Sh DESCRIPTION
14	.Nm
15	is a mail filtering utility. It connects to remote mail servers using the
16	Internet Message Access Protocol (IMAP) and processes messages based on
17	the definition of filter rules. It can be used to delete, sort, etc.
18	messages residing in multiple mailboxes at different mail servers.
19	.Pp
20	The options are as follows:
21	.Bl -tag -width Ds
22	.It Fl D
23	Debug mode; creates a temporary file name in
24	.Pa /tmp/imapfilter.XXXX ,
25	where debugging messages about the program's progress are printed.
26	.It Fl V
27	Displays program's version.
28	.It Fl c Ar configfile
29	Configuration file to read settings and filters from. The default is
30	.Pa $HOME/.imapfilterrc .
31	.It Fl d Ar interval
32	Runs imapfilter at daemon mode and repeatedly polls at the specified interval.
33	.It Fl k
34	Kills any other running instances of
35	.Nm
36	and removes the lockfile left from a past session.
37	.It Fl l Ar logfile
38	File that contains logs of error messages
39	.Nm
40	produces and optionally information about the deleted messages.
41	.It Fl p
42	Enters the interactive encrypted passwords editor.
43	.It Fl q
44	Quiet mode; prints less detailed information about the program's actions.
45	Multiple
46	.Fl q
47	options decrease the verbosity. The minimum is -2.
48	.It Fl v
49	Verbose mode; prints more detailed information about the program's actions.
50	Multiple
51	.Fl v
52	options increase the verbosity. The maximum is 2.
53	.El
54	.Pp
55	While running in daemon mode, if the SIGUSR1 signal is send,
56	.Nm
57	wakes up from its sleep phase and rereads its configuration file.
58	.Sh AUTHENTICATION AND ENCRYPTION
59	.Nm
60	supports the Challenge-Response Authentication Mechanism (CRAM) for
61	user authentication. The authentication type associated with CRAM is
62	CRAM-MD5.
63	.Nm
64	will authenticate using CRAM-MD5, if the mail server supports this
65	authentication method, instead of plaintext password LOGIN.
66	.Pp
67	.Nm
68	supports encryption of the connection with the IMAP STARTTLS extension,
69	and will try to negotiate a TLS connection if the mail server supports it.
70	.Pp
71	.Nm
72	supports imaps (port 993) SSL/TLS connections. The user must manually enable
73	imaps SSL/TLS connections and specify the SSL/TLS protocol to be negotiated,
74	through
75	.Nm Ap s
76	configuration file.
77	.Sh PASSWORD EDITOR
78	.Nm
79	has the capability to encrypt the accounts' passwords and store them
80	separately at
81	.Pa $HOME/.imapfilter/passwords .
82	These passwords are encrypted with a master password, supplied by
83	the user. The Blowfish block cipher with a 128bit key in CBC mode
84	is used to do the encryption. The master password is entered each
85	time
86	.Nm
87	is run, in order to decrypt the password file and retrieve the
88	actual passwords of the user's IMAP mail accounts.
89	.Pp
90	First of all, while defining accounts in the
91	.Nm
92	configuration file, the user must specify only the username and server
93	in those accounts he/she wishes to encrypt the passwords before storage.
94	Then, one can enter the interactive passwords' editor by using the
95	.Fl p
96	option.
97	.Pp
98	After entering the interactive password editor, a command line prompt
99	is used to manage the passwords. The available commands are:
100	.Bl -tag -width Ds
101	.It Cm c
102	Clears a password from an account. It takes as an argument a
103	number, specifying which account's password should be cleared.
104	.It Cm e
105	Edits an account's password entry. It takes as an argument a
106	number, the account's password to be edited.
107	.It Cm h
108	Prints a brief help message of all commands.
109	.It Cm l
110	Lists all accounts. Specifically a number that describes the
111	account, the hostname of the IMAP mail server, the username
112	and the password (if one is already specified).
113	.It Cm p
114	Changes the master password, used to encrypt all other passwords.
115	.It Cm q
116	Quits the password editor without saving changes.
117	.It Cm w
118	Saves changes.
119	.It Cm x
120	Saves changes and exits the password editor.
121	.El
122	.Sh INTERNAL DETAILS
123	After
124	.Nm
125	reads the configuration file and creates all necessary data structures, it
126	starts by going through the list of accounts. It connects to the servers
127	specified, in the order they were defined in the configuration file with
128	the
129	.Ar account
130	keyword. It then goes through the list of mailboxes belonging to the server,
131	in the order they were defined in the configuration file with the
132	.Ar folder
133	keyword. For each mailbox it applies the filters that were specified for it,
134	in the order they were defined in the configuration file using the
135	.Ar job
136	keyword. This process continues until the last account, mailbox and filter.
137	.Sh ENVIRONMENT
138	.Bl -tag -width Ds
139	.It Ev HOME
140	User's home directory.
141	.El
142	.Sh FILES
143	.Bl -tag -width Ds
144	.It Pa $HOME/.imapfilterrc
145	Default configuration file.
146	.It Pa $HOME/.imapfilter/passwords
147	File where the encrypted passwords are stored.
148	.It Pa $HOME/.imapfilter/certificates
149	File where the SSL/TLS certificates are stored.
150	.It Pa $HOME/.imapfilter/lock
151	Lock file containing the PID of
152	.Nm .
153	.It Pa /tmp/imapfilter.XXXX
154	Debug file.
155	.El
156	.Sh SEE ALSO
157	.Xr imapfilterrc 5
158	.Sh STANDARDS
159	.Bl -tag -width Ds
160	.It IMAP4rev1:
161	RFC 3501, RFC 2683, RFC 2595, RFC 2342, RFC 2195
162	.El
163	.Sh AUTHORS
164	.An Lefteris Chatzibarbas Aq lefcha@hellug.gr