File: mairixrc.5

package info (click to toggle)
mairix 0.24-2
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, buster, sid, trixie
  • size: 1,376 kB
  • sloc: ansic: 13,318; sh: 1,035; yacc: 185; makefile: 143; lex: 87; perl: 34
file content (458 lines) | stat: -rw-r--r-- 12,423 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
.TH MAIRIXRC 5 "January 2006"
.de Sx
.PP
.ne \\$1
.nf
.na
.RS 12
..
.de Ex
.RE 
.fi
.ad
.IP "" 7
..
.SH NAME
mairixrc \- configuration file for mairix(1)
.SH SYNOPSIS
$HOME/.mairixrc
.SH DESCRIPTION
.PP
The
.I mairixrc
file tells
.B mairix
where your mail folders are located.  It also tells
.B mairix
where the results of searches are to be written.

.B mairix
searches for this file at
.I $HOME/.mairixrc
unless the
.B -f
option is used.

The directives
.BR base ,
.BR mfolder ,
and
.B database
must always appear in the file.  There must also be some folder definitions
(using the
.BR maildir ,
.BR mh ,
or
.BR mbox )
directives.

.SS Comments
Any line starting with a '#' character is treated as a comment.

.SS Directives
.TP
.BI base= base-directory
.br
This defines the path to the common parent directory of all your
maildir folders.

.TP
.BI imap_server= hostname
.br
If any IMAP source folders are specified or the results folder is an IMAP
folder, this defines the host name of the IMAP server. The port is
currently always 143. This option is mutually exclusive with the 'imap_pipe'
option.

.TP
.BI imap_pipe= shell-command
.br
If any IMAP source folders are specified or the results folder is an IMAP
folder, this defines a shell command that can be used to connect to the
IMAP server and talk to it over UNIX pipes instead of a TCP/IP connection.
This option is mutually exclusive with the 'imap_server' option.

.TP
.BI imap_username= username
.br
If any IMAP source folders are specified or the results folder is an IMAP
folder, this defines the user name to use to log in to the IMAP server.
This parameter is optional, but IMAP servers normally require clients to
log in, so it is normally necessary to specify it. One example of a case
where it is not required is if the 'imap_pipe' option is in use the the
shell command established a connection with an IMAP server in
pre-autenticated state.

.TP
.BI imap_password= password
.br
If any IMAP source folders are specified or the results folder is an IMAP
folder, this defines the password to use to log in to the IMAP server.
This parameter is optional, but IMAP servers normally require clients to
log in, so it is normally necessary to specify it.

.TP
.BI maildir= list-of-folder-specifications
This is a colon-separated list of the Maildir folders (relative to
`base') that you want indexed.  Any entry that ends `...' is
recursively scanned to find any Maildir folders underneath it.

More than one line starting with `maildir' can be included.  In
this case, mairix joins the lines together with colons as though a
single list of folders had been given on a single very long line.

Each colon-separated entry may be a wildcard.  See the discussion
under mbox (below) for the wildcard syntax.  For example
.Sx 1
maildir=zzz/foo*...
.Ex
will match maildir folders like these (relative to the 
.IR base-directory )
.Sx 4
zzz/foobar/xyz
zzz/fooquux
zzz/foo
zzz/fooabc/u/v/w
.Ex

and
.Sx 1
maildir=zzz/foo[abc]*
.Ex
will match maildir folders like these (relative to the folder_base)
.Sx 4
zzz/fooa
zzz/fooaaaxyz
zzz/foobcd
zzz/fooccccccc
.Ex
If a folder name contains a colon, you can write this by using the
sequence '\\:' to escape the colon.  Otherwise, the backslash
character is treated normally.  (If the folder name actually
contains the sequence '\\:', you're out of luck.)

.TP
.BI mh= list-of-folder-specifications
.br
This is a colon-separated list of the MH folders (relative to
`base') that you want indexed.  Any entry that ends '...' is
recursively scanned to find any MH folders underneath it.

More than one line starting with 'mh' can be included.  In this
case, mairix joins the lines together with colons as though a
single list of folders had been given on a single very long line.

Each colon-separated entry may be a wildcard, see the discussion
under maildir (above) and mbox (below) for the syntax and
semantics of specifying wildcards.

.B mairix
recognizes the types of MH folders created by the following email applications:
.RS 7
.IP "*"
xmh
.IP "*"
sylpheed
.IP "*"
claws-mail
.IP "*"
evolution
.IP "*"
NNML
.IP "*"
Mew
.RE

.TP
.BI mbox= list-of-folder-specifications
.br
This is a colon-separated list of the mbox folders (relative to
`base') that you want indexed.

Each colon-separated item in the list can be suffixed by '...'.
If the item matches a regular file, that file is treated as a mbox
folder and the '...' suffix is ignored.  If the item matches a
directory, a recursive scan of everything inside that directory is
made, and all regular files are initially considered as mbox
folders.  (Any directories found in this scan are themselves
scanned, since the scan is recursive.)

Each colon-separated item may contain wildcard operators, but only
in its final path component.  The wildcard operators currently
supported are

.TP
*
.br
Match zero or more characters (each character matched is
arbitrary)

.TP
?
.br
Match exactly one arbitrary character

.TP
[abcs-z]
.br
Character class : match a single character from the set a, b,
c, s, t, u, v, w, x, y and z.

To include a literal ']' in the class, place it immediately
after the opening '['.  To include a literal '-' in the
class, place it immediately before the closing ']'.

If these metacharacters are included in non-final path components,
they have no special meaning.

Here are some examples

.TP
mbox=foo/bar*
.br
matches 'foo/bar', 'foo/bar1', 'foo/barrrr' etc

.TP
mbox=foo*/bar*
.br
matches 'foo*/bar', 'foo*/bar1', 'foo*/barrrr' etc

.TP
mbox=foo/*
.br
matches 'foo/bar', 'foo/bar1', 'foo/barrrr', 'foo/foo',
\'foo/x' etc

.TP
mbox=foo...
.br
matches any regular file in the tree rooted at 'foo'

.TP
mbox=foo/*...
.br
same as before

.TP
mbox=foo/[a-z]*...
.br
matches 'foo/a', 'foo/aardvark/xxx', 'foo/zzz/foobar',
\'foo/w/x/y/zzz', but not 'foo/A/foobar'

Regular files that are mbox folder candidates are examined
internally.  Only files containing standard mbox 'From ' separator
lines will be scanned for messages.

If a regular file has a name ending in '.gz', and gzip support is
compiled into the 
.B mairix
binary, the file will be treated as a gzipped mbox.

If a regular file has a name ending in '.bz2', and bzip support is
compiled into the
.B mairix
binary, the file will be treated as a bzip2'd mbox.

More than one line starting with 'mbox' can be included.  In this
case, 
.B mairix
joins the lines together with colons as though a
single list of folders had been given on a single very long line.

.B mairix
performs no locking of mbox folders when it is accessing
them.  If a mail delivery program is modifying the mbox at the
same time, it is likely that one or messages in the mbox will
never get indexed by 
.B mairix
(until the database is removed and recreated from scratch, anyway.)  The
assumption is that
.B mairix
will be used to index archive folders rather than incoming ones, so this is
unlikely to be much of a problem in reality.

.B mairix
can support a maximum of 65536 separate mboxes, and a
maximum of 65536 messages within any one mbox.

.TP
.BI imap= list-of-folders
.br
This is a colon-separated list of the IMAP folders that you want indexed.

These folders must all be located on the same account on the same IMAP
server. The configuration options imap_server and imap_pipe specify
how to connect to the IMAP server.

More than one line starting with 'imap' can be included.  In this
case, 
.B mairix
joins the lines together with colons as though a
single list of folders had been given on a single very long line.
.TP
.BI omit= list-of-glob-patterns
This is a colon-separated list of glob patterns for folders to be omitted from
the indexing.  This allows wide wildcards and recursive elements to be used
in the 
.BR maildir , mh ", and" mbox
directives, with the
.B omit
option used to selectively remove unwanted folders from the folder
lists.

Within the glob patterns, a single '*' matches any
sequence of characters other than '/'.  However '**' matches any
sequence of characters including '/'.  This allows glob patterns
to be constructed which have a wildcard for just one directory
component, or for any number of directory components.

The _omit_ option can be specified as many times as required so
that the list of patterns doesn't all have to fit on one line.

As an example,
.Sx 2
mbox=bulk...
omit=bulk/spam*
.Ex
will index all mbox folders at any level under the 'bulk'
subdirectory of the base folder, except for those folders whose
names start 'bulk/spam', e.g. 'bulk/spam', 'bulk/spam2005' etc.

In constrast,
.Sx 2
mbox=bulk...
omit=bulk/spam**
.Ex
will index all mbox folders at any level under the 'bulk'
subdirectory of the base folder, except for those folders whose
names start 'bulk/spam', e.g. 'bulk/spam', 'bulk/spam2005',
\'bulk/spam/2005', 'bulk/spam/2005/jan' etc.

.TP
.B nochecks
This takes no arguments.  If a line starting with
.B nochecks is
present, it is the equivalent of specifying the 
.B -Q
flag to every indexing run.

.TP
.BI mfolder= match-folder-name
This defines the name of the folder (within the directory
specified by 
.BR base )
into which the search mode writes its output.  (If the 
.B mformat
used is 'raw' or 'excerpt', then this setting is not used and may be omitted.)

The
.B mfolder
setting may be over-ridden for a particular search by using the
.B -o
option to
.BR mairix .

.B mairix
will refuse to output search results to a folder that appears to be amongst
those that are indexed.  This is to prevent accidental deletion of emails.

If the first character of the mfolder value is '/' or '.', it is
taken as a pathname in its own right.  This allows you to specify
absolute paths and paths relative to the current directory where
the mfolder should be written.  Otherwise, the value of mfolder is
appended to the value of base, in the same way as for the source
folders.

.TP
.BI mformat= format
This defines the type of folder used for the match folder where
the search results go.  There are six valid settings for
.IR format ,
namely 'maildir', 'mh', 'mbox', 'imap', 'raw', or 'excerpt'.  If the 'raw' setting is
used then
.B mairix
will just print out the path names of the files that match and no match folder
will be created.  If the 'excerpt' setting is used,
.B mairix
will also print out the To:, Cc:, From:, Subject: and Date: headers of the
matching messages.  'maildir' is the default if this option is not
defined.  The setting is case-insensitive.

.TP
.BI database= path-to-database
.br
This defines the path where
.BR mairix 's
index database is kept.  You can keep this file anywhere you like.

Currently,
.B mairix
will place a single database file at the location indicated by
.IR path-to-database .
However, a future version of
.B mairix
may instead place a directory containing several files at this location.

.I path-to-database
should be an absolute pathname (starting with '/').  If a relative pathname is
used, it will be interpreted relative to the current directory at the time
.B mairix
is run,
.RB ( not
relative to the location of the 
.I mairixrc
file or anything like that.)

.TP
.BI follow_mbox_symlinks
.br
This takes no arguments.  By default, mairix will skip symlinks to
mboxes when indexing.  If a line starting with
.B follow_mbox_symlinks
is present, mairix will follow them instead of skipping them.

.SS Expansions

The part of each line in '.mairixrc' following the equals sign can
contain the following types of expansion:

.TP
.B Home directory expansion
If the sequence '~/' appears at the start of the text after the
equals sign, it is expanded to the user's home directory.  Example:
.Sx 1
database=~/Mail/mairix_database
.Ex
.TP
.B Environment expansion
If a '$' is followed by a sequence of alpha-numeric characters (or
\'_'), the whole string is replaced by looking up the corresponding
environment variable.  Similarly, if '$' is followed by an open
brace ('{'), everything up to the next close brace is looked up as
an environment variable and the result replaces the entire
sequence.

Suppose in the shell we do
.Sx 1
export FOO=bar
.Ex
and the '.mairixrc' file contains
.Sx 2
maildir=xxx/$FOO
mbox=yyy/a${FOO}b
.Ex
this is equivalent to
.Sx 2
maildir=xxx/bar
mbox=yyy/abarb
.Ex
If the specified environment variable is not set, the replacement
is the empty string.

.SH NOTES
.PP
An alternative path to the configuration file may be given with the
.B \-f
option to mairix(1).