imapfilter/imapfilter/imapfilterrc.5

.Dd July 26, 2002
.Dt IMAPFILTERRC 5
.Os
.Sh NAME
.Nm imapfilterrc
.Nd imapfilter configuration file
.Sh SYNOPSIS
.Pa $HOME/.imapfilterrc
.Sh DESCRIPTION
The
.Nm
configuration file consists of a series of commands and variable settings,
with each one in a separate line.
.Pp
Empty lines and lines beginning with the number sign
.Sq #
character,
which
are considered comments, are ignored.
.Sh COMMANDS
.Bl -tag -width Ds
.It Cm account Ar alias username[:password]@hostname[:port] [ssl|ssl2|ssl3|tls1]
Defines a user account under the name
.Ar alias ,
using the
.Ar username
as user identification and
.Ar password
as the secret word, connecting to the
.Ar hostname
mail server, at the specified
.Ar port
(if not specified the default IMAP protocol port (ie. 143 or 993 when SSL/TLS is
enabled) is used).  SSL/TLS support is enabled with the argument
.Ar ssl ,
which uses as default the SSL protocol version 2, though this may be changed by
specifying a different protocol/version.
.Pp
The
.Ar alias
is comprised by alphanumeric, underscore
.Sq _
and minus
.Sq -
characters.
.Pp
The
.Ar username
and
.Ar password
strings can be given in a URL encoding like scheme, that is the
.Sq %
character followed by two hexadecimal digits representing the encoded
character's
.Xr ascii 7
code. Within the
.Ar username
and
.Ar password
field, any
.Sq \&: ,
.Sq @ ,
.Sq %
or
.Sq \ 
characters must be encoded in the above way.
.Pp
The
.Ar password
field may be omitted, in which case the user is prompted for one
interactively, when
.Xr imapfilter 1
is run. Also, a
.Ar password
must not be supplied, if the user intends to specify one using the
interactive encrypted passwords' editor of
.Xr imapfilter 1 ,
in order to store the password securely in the filesystem.
.It Cm folder Ar alias folder[,...]
Defines folders (mailboxes) and groups them under the
.Ar alias
name.  The mailboxes are associated with the last preceding
.Ar account
setting. More than one
.Ar folder
can be declared, separating them with a comma
.Sq \&, 
character. The
.Ar alias
is comprised by alphanumeric, underscore
.Sq _
and minus
.Sq -
characters.
.It Cm filter Ar alias [or|and]
Starts the declaration of a filter with the name
.Ar alias .
Optionally the
.Ar and
or
.Ar or
flag can be set, in order to set the mode in which the filter's masks
will be combined (default is
.Ar and
mode). The
.Ar alias
is comprised by alphanumeric, underscore
.Sq _
and minus
.Sq -
characters.
.It Cm [mask] Ar [or|and] [not] searchkey
A filter entry contains one or more mask entries which are defined with
the optional
.Ar mask
command, the
.Ar or
or
.Ar and
flag, the
.Ar not
flag and the searching criteria, based on which matching of a filter is done.
.Pp
The
.Ar or
and
.Ar and
flags are used to define in which way the current
.Ar mask
is combined with it's previous
.Ar mask .
The
.Ar not
flag is used to revert the functionality of the specified
.Ar searchkey .
.Pp
A
.Ar string
can be a word, or a phrase enclosed in
.Sq \&" .
The matching of the
.Ar string
is case-insensitive.
.Pp
The available searching criteria are:
.Bl -tag -width Ds
.It Cm answered
Messages that have been answered.
.It Cm bcc Ar string
Messages that contain the specified
.Ar string
in the envelope structure's
.Dq Bcc
field.
.It Cm body Ar string
Messages that contain the specified
.Ar string
in the body of the message.
.It Cm cc Ar string
Messages that contain the specified
.Ar string
in the envelope structure's
.Dq Cc
field.
.It Cm deleted
Messages that are marked for deletion.
.It Cm draft
Messages that have not completed composition.
.It Cm flagged
Messages marked for urgent/special attention.
.It Cm from Ar string
Messages that contain the specified
.Ar string
in the envelope structure's
.Dq From
field.
.It Cm header Ar fieldname string
Messages that have a header with the specified
.Ar fieldname ,
and contain the specified
.Ar string
in the field body.
.It Cm larger Ar number
Messages with size larger than the specified
.Ar number
in octets (bytes).
.It Cm new
Messages that have
.Qq recently
arrived in the mailbox (this session is the
first, to have been notified about the messages) and have not been read.
.It Cm newer Ar number
Messages whose internal date is newer than the specified
.Ar number
of days.
.It Cm old
Messages that have not
.Qq recently
arrived in the mailbox and have not been
read.
.It Cm older Ar number
Messages whose internal date is older than the specified
.Ar number
of days.
.It Cm recent
Messages that have
.Qq recently
arrived in the mailbox (this session is the
first, to have been notified about the messages).
.It Cm seen
Messages that have been read.
.It Cm smaller Ar number
Messages with size smaller than the specified
.Ar number
in octets (bytes).
.It Cm subject Ar string
Messages that contain the specified string in the envelope structure's
.Dq Subject
field.
.It Cm unanswered
Messages that have not been answered.
.It Cm undeleted
Messages that are not marked for deletion.
.It Cm undraft
Messages that have completed composition.
.It Cm unflagged
Messages that are not marked for urgent/special attention.
.It Cm unseen
Messages that have not been read.
.El
.It Cm action Ar type
The
.Cm action
command is used to end the filter entry started with the
.Cm filter
command. It assigns an action to be done when the filter is matched.
.Pp
The available
.Ar type
of actions are:
.Bl -tag -width Ds
.It Cm copy Ar mailbox [header,...]
Copies the messages to the specified
.Ar mailbox .
If the
.Ar mailbox
does not exist, then it is created. Optionally, fetches and displays the
.Ar header
of the messages that were copied.
.It Cm delete Ar [header,...]
Deletes the messages. User can also, optionally, define the
.Ar header
of the deleted messages to be displayed. More than one
.Ar header
can be declared and fetched, by separating them with a comma
.Sq \&,
character.
.It Cm flag Ar mode flag[,...] [header,...]
Sets the flags of the messages. The
.Ar mode
can be
.Ar replace ,
.Ar add ,
or
.Ar remove .
The
.Ar flag
can be
.Ar none ,
.Ar seen ,
.Ar answered ,
.Ar flagged ,
.Ar deleted ,
or
.Ar draft .
Optionally, the
.Ar header
of the messages is displayed.
.It Cm list Ar [header,...]
Just displays the
.Ar header
of the messages.
.It Cm move Ar mailbox [header,...]
Moves the messages to the specified
.Ar mailbox .
If the
.Ar mailbox
does not exist, then it is created. Optionally, fetches and displays the
.Ar header
of the messages that were moved.
.It Cm rcopy Ar account mailbox [header,...]
Copies the messages to the specified
.Ar mailbox
residing on a specific
.Ar account .
Optionally, displays the
.Ar header
of the messages.
.It Cm rmove Ar account mailbox [header,...]
Moves the messages to the specified
.Ar mailbox
residing on a specific
.Ar account .
Optionally, displays the
.Ar header
of the messages.
.El
.It Cm job Ar filter[,...] folder[,...]
This command is used to define which
.Ar filter
must be applied to which
.Ar folder .
More than one
.Ar filter
and/or
.Ar folder
can be declared, by separating them with a comma
.Sq \&,
character.
.It Cm [set] Ar variable=value
Manipulate and set the configuration variables.
.El
.Sh VARIABLES
.Bl -tag -width Ds
.It Va daemon
This variable enables the daemon mode of
.Xr imapfilter 1 .
It takes a numeric
argument, the polling interval in seconds.
.It Va expunge
Normally messages are marked for deletion and are actually deleted when the
mailbox is closed. When this option is enabled, messages are expunged after
they are marked deleted. The argument must be
.Dq yes
or
.Dq no .
Default is
.Dq no .
.It Va headers
By enabling this variable, message headers (if requested) are displayed,
besides being written to the log file. The argument must be
.Dq yes
or
.Dq no .
Default is
.Dq no .
.It Va logfile
Full path to log file where filtering information and possible error
messages are saved to. The command line
.Fl l
option overrides this setting.
.It Va namespace
When enabled, the program gets the namespace of the user's personal mailboxes,
and applies automatically the prefix and hierarchy delimiter to any mailboxes
residing on the mail server.  This must be disabled in cases where the user
wants to manually specify mailbox names (eg. because they are not part of the
user's personal namespace mailboxes).  The argument must be
.Dq yes
or
.Dq no .
Default is
.Dq yes .
.It Va subscribe
By enabling this variable newly created mailboxes get also subscribed; they
are set
.Dq active
in order for IMAP clients to recognize them. The argument must be
.Dq yes
or
.Dq no .
Default is
.Dq no .
.It Va timeout
The time in seconds, for the program to wait for a mail server's response.
If not set, then the client will block indefinitely.
.It Va warning
If
.Xr imapfilter 1
cannot lock memory pages, it prints a warning message about "insecure memory".
To suppress the warning, this variable must be disabled. The argument must
be
.Dq yes
or
.Dq no .
Default is
.Dq yes .
.El
.Sh EXAMPLES
See
.Pa sample.imapfilterrc .
.Sh ENVIROMENT
.Bl -tag -width Ds
.It Ev HOME
User's home directory.
.El
.Sh SEE ALSO
.Xr imapfilter 1
.Sh AUTHORS
.An Lefteris Chatzibarbas Aq lefcha@hellug.gr
1	.Dd July 26, 2002
2	.Dt IMAPFILTERRC 5
3	.Os
4	.Sh NAME
5	.Nm imapfilterrc
6	.Nd imapfilter configuration file
7	.Sh SYNOPSIS
8	.Pa $HOME/.imapfilterrc
9	.Sh DESCRIPTION
10	The
11	.Nm
12	configuration file consists of a series of commands and variable settings,
13	with each one in a separate line.
14	.Pp
15	Empty lines and lines beginning with the number sign
16	.Sq #
17	character,
18	which
19	are considered comments, are ignored.
20	.Sh COMMANDS
21	.Bl -tag -width Ds
22	.It Cm account Ar alias username[:password]@hostname[:port] [ssl\|ssl2\|ssl3\|tls1]
23	Defines a user account under the name
24	.Ar alias ,
25	using the
26	.Ar username
27	as user identification and
28	.Ar password
29	as the secret word, connecting to the
30	.Ar hostname
31	mail server, at the specified
32	.Ar port
33	(if not specified the default IMAP protocol port (ie. 143 or 993 when SSL/TLS is
34	enabled) is used). SSL/TLS support is enabled with the argument
35	.Ar ssl ,
36	which uses as default the SSL protocol version 2, though this may be changed by
37	specifying a different protocol/version.
38	.Pp
39	The
40	.Ar alias
41	is comprised by alphanumeric, underscore
42	.Sq _
43	and minus
44	.Sq -
45	characters.
46	.Pp
47	The
48	.Ar username
49	and
50	.Ar password
51	strings can be given in a URL encoding like scheme, that is the
52	.Sq %
53	character followed by two hexadecimal digits representing the encoded
54	character's
55	.Xr ascii 7
56	code. Within the
57	.Ar username
58	and
59	.Ar password
60	field, any
61	.Sq \&: ,
62	.Sq @ ,
63	.Sq %
64	or
65	.Sq \
66	characters must be encoded in the above way.
67	.Pp
68	The
69	.Ar password
70	field may be omitted, in which case the user is prompted for one
71	interactively, when
72	.Xr imapfilter 1
73	is run. Also, a
74	.Ar password
75	must not be supplied, if the user intends to specify one using the
76	interactive encrypted passwords' editor of
77	.Xr imapfilter 1 ,
78	in order to store the password securely in the filesystem.
79	.It Cm folder Ar alias folder[,...]
80	Defines folders (mailboxes) and groups them under the
81	.Ar alias
82	name. The mailboxes are associated with the last preceding
83	.Ar account
84	setting. More than one
85	.Ar folder
86	can be declared, separating them with a comma
87	.Sq \&,
88	character. The
89	.Ar alias
90	is comprised by alphanumeric, underscore
91	.Sq _
92	and minus
93	.Sq -
94	characters.
95	.It Cm filter Ar alias [or\|and]
96	Starts the declaration of a filter with the name
97	.Ar alias .
98	Optionally the
99	.Ar and
100	or
101	.Ar or
102	flag can be set, in order to set the mode in which the filter's masks
103	will be combined (default is
104	.Ar and
105	mode). The
106	.Ar alias
107	is comprised by alphanumeric, underscore
108	.Sq _
109	and minus
110	.Sq -
111	characters.
112	.It Cm [mask] Ar [or\|and] [not] searchkey
113	A filter entry contains one or more mask entries which are defined with
114	the optional
115	.Ar mask
116	command, the
117	.Ar or
118	or
119	.Ar and
120	flag, the
121	.Ar not
122	flag and the searching criteria, based on which matching of a filter is done.
123	.Pp
124	The
125	.Ar or
126	and
127	.Ar and
128	flags are used to define in which way the current
129	.Ar mask
130	is combined with it's previous
131	.Ar mask .
132	The
133	.Ar not
134	flag is used to revert the functionality of the specified
135	.Ar searchkey .
136	.Pp
137	A
138	.Ar string
139	can be a word, or a phrase enclosed in
140	.Sq \&" .
141	The matching of the
142	.Ar string
143	is case-insensitive.
144	.Pp
145	The available searching criteria are:
146	.Bl -tag -width Ds
147	.It Cm answered
148	Messages that have been answered.
149	.It Cm bcc Ar string
150	Messages that contain the specified
151	.Ar string
152	in the envelope structure's
153	.Dq Bcc
154	field.
155	.It Cm body Ar string
156	Messages that contain the specified
157	.Ar string
158	in the body of the message.
159	.It Cm cc Ar string
160	Messages that contain the specified
161	.Ar string
162	in the envelope structure's
163	.Dq Cc
164	field.
165	.It Cm deleted
166	Messages that are marked for deletion.
167	.It Cm draft
168	Messages that have not completed composition.
169	.It Cm flagged
170	Messages marked for urgent/special attention.
171	.It Cm from Ar string
172	Messages that contain the specified
173	.Ar string
174	in the envelope structure's
175	.Dq From
176	field.
177	.It Cm header Ar fieldname string
178	Messages that have a header with the specified
179	.Ar fieldname ,
180	and contain the specified
181	.Ar string
182	in the field body.
183	.It Cm larger Ar number
184	Messages with size larger than the specified
185	.Ar number
186	in octets (bytes).
187	.It Cm new
188	Messages that have
189	.Qq recently
190	arrived in the mailbox (this session is the
191	first, to have been notified about the messages) and have not been read.
192	.It Cm newer Ar number
193	Messages whose internal date is newer than the specified
194	.Ar number
195	of days.
196	.It Cm old
197	Messages that have not
198	.Qq recently
199	arrived in the mailbox and have not been
200	read.
201	.It Cm older Ar number
202	Messages whose internal date is older than the specified
203	.Ar number
204	of days.
205	.It Cm recent
206	Messages that have
207	.Qq recently
208	arrived in the mailbox (this session is the
209	first, to have been notified about the messages).
210	.It Cm seen
211	Messages that have been read.
212	.It Cm smaller Ar number
213	Messages with size smaller than the specified
214	.Ar number
215	in octets (bytes).
216	.It Cm subject Ar string
217	Messages that contain the specified string in the envelope structure's
218	.Dq Subject
219	field.
220	.It Cm unanswered
221	Messages that have not been answered.
222	.It Cm undeleted
223	Messages that are not marked for deletion.
224	.It Cm undraft
225	Messages that have completed composition.
226	.It Cm unflagged
227	Messages that are not marked for urgent/special attention.
228	.It Cm unseen
229	Messages that have not been read.
230	.El
231	.It Cm action Ar type
232	The
233	.Cm action
234	command is used to end the filter entry started with the
235	.Cm filter
236	command. It assigns an action to be done when the filter is matched.
237	.Pp
238	The available
239	.Ar type
240	of actions are:
241	.Bl -tag -width Ds
242	.It Cm copy Ar mailbox [header,...]
243	Copies the messages to the specified
244	.Ar mailbox .
245	If the
246	.Ar mailbox
247	does not exist, then it is created. Optionally, fetches and displays the
248	.Ar header
249	of the messages that were copied.
250	.It Cm delete Ar [header,...]
251	Deletes the messages. User can also, optionally, define the
252	.Ar header
253	of the deleted messages to be displayed. More than one
254	.Ar header
255	can be declared and fetched, by separating them with a comma
256	.Sq \&,
257	character.
258	.It Cm flag Ar mode flag[,...] [header,...]
259	Sets the flags of the messages. The
260	.Ar mode
261	can be
262	.Ar replace ,
263	.Ar add ,
264	or
265	.Ar remove .
266	The
267	.Ar flag
268	can be
269	.Ar none ,
270	.Ar seen ,
271	.Ar answered ,
272	.Ar flagged ,
273	.Ar deleted ,
274	or
275	.Ar draft .
276	Optionally, the
277	.Ar header
278	of the messages is displayed.
279	.It Cm list Ar [header,...]
280	Just displays the
281	.Ar header
282	of the messages.
283	.It Cm move Ar mailbox [header,...]
284	Moves the messages to the specified
285	.Ar mailbox .
286	If the
287	.Ar mailbox
288	does not exist, then it is created. Optionally, fetches and displays the
289	.Ar header
290	of the messages that were moved.
291	.It Cm rcopy Ar account mailbox [header,...]
292	Copies the messages to the specified
293	.Ar mailbox
294	residing on a specific
295	.Ar account .
296	Optionally, displays the
297	.Ar header
298	of the messages.
299	.It Cm rmove Ar account mailbox [header,...]
300	Moves the messages to the specified
301	.Ar mailbox
302	residing on a specific
303	.Ar account .
304	Optionally, displays the
305	.Ar header
306	of the messages.
307	.El
308	.It Cm job Ar filter[,...] folder[,...]
309	This command is used to define which
310	.Ar filter
311	must be applied to which
312	.Ar folder .
313	More than one
314	.Ar filter
315	and/or
316	.Ar folder
317	can be declared, by separating them with a comma
318	.Sq \&,
319	character.
320	.It Cm [set] Ar variable=value
321	Manipulate and set the configuration variables.
322	.El
323	.Sh VARIABLES
324	.Bl -tag -width Ds
325	.It Va daemon
326	This variable enables the daemon mode of
327	.Xr imapfilter 1 .
328	It takes a numeric
329	argument, the polling interval in seconds.
330	.It Va expunge
331	Normally messages are marked for deletion and are actually deleted when the
332	mailbox is closed. When this option is enabled, messages are expunged after
333	they are marked deleted. The argument must be
334	.Dq yes
335	or
336	.Dq no .
337	Default is
338	.Dq no .
339	.It Va headers
340	By enabling this variable, message headers (if requested) are displayed,
341	besides being written to the log file. The argument must be
342	.Dq yes
343	or
344	.Dq no .
345	Default is
346	.Dq no .
347	.It Va logfile
348	Full path to log file where filtering information and possible error
349	messages are saved to. The command line
350	.Fl l
351	option overrides this setting.
352	.It Va namespace
353	When enabled, the program gets the namespace of the user's personal mailboxes,
354	and applies automatically the prefix and hierarchy delimiter to any mailboxes
355	residing on the mail server. This must be disabled in cases where the user
356	wants to manually specify mailbox names (eg. because they are not part of the
357	user's personal namespace mailboxes). The argument must be
358	.Dq yes
359	or
360	.Dq no .
361	Default is
362	.Dq yes .
363	.It Va subscribe
364	By enabling this variable newly created mailboxes get also subscribed; they
365	are set
366	.Dq active
367	in order for IMAP clients to recognize them. The argument must be
368	.Dq yes
369	or
370	.Dq no .
371	Default is
372	.Dq no .
373	.It Va timeout
374	The time in seconds, for the program to wait for a mail server's response.
375	If not set, then the client will block indefinitely.
376	.It Va warning
377	If
378	.Xr imapfilter 1
379	cannot lock memory pages, it prints a warning message about "insecure memory".
380	To suppress the warning, this variable must be disabled. The argument must
381	be
382	.Dq yes
383	or
384	.Dq no .
385	Default is
386	.Dq yes .
387	.El
388	.Sh EXAMPLES
389	See
390	.Pa sample.imapfilterrc .
391	.Sh ENVIROMENT
392	.Bl -tag -width Ds
393	.It Ev HOME
394	User's home directory.
395	.El
396	.Sh SEE ALSO
397	.Xr imapfilter 1
398	.Sh AUTHORS
399	.An Lefteris Chatzibarbas Aq lefcha@hellug.gr