1MAIRIXRC(5) File Formats Manual MAIRIXRC(5)
2
6 mairixrc - configuration file for mairix(1)
7
9 $HOME/.mairixrc
10
12 The mairixrc file tells mairix where your mail folders are located. It
13 also tells mairix where the results of searches are to be written.
14 mairix searches for this file at $HOME/.mairixrc unless the -f option
16 is used.
17 The directives base, mfolder, and database must always appear in the
19 file. There must also be some folder definitions (using the maildir,
20 mh, or mbox) directives.
21 Comments
24 Any line starting with a '#' character is treated as a comment.
25 Directives
28 base=base-directory
29 This defines the path to the common parent directory of all your
30 maildir folders.
31 imap_server=hostname
34 If any IMAP source folders are specified or the results folder
35 is an IMAP folder, this defines the host name of the IMAP
36 server. The port is currently always 143. This option is mutu‐
37 ally exclusive with the 'imap_pipe' option.
38 imap_pipe=shell-command
41 If any IMAP source folders are specified or the results folder
42 is an IMAP folder, this defines a shell command that can be used
43 to connect to the IMAP server and talk to it over UNIX pipes in‐
44 stead of a TCP/IP connection. This option is mutually exclusive
45 with the 'imap_server' option.
46 imap_username=username
49 If any IMAP source folders are specified or the results folder
50 is an IMAP folder, this defines the user name to use to log in
51 to the IMAP server. This parameter is optional, but IMAP
52 servers normally require clients to log in, so it is normally
53 necessary to specify it. One example of a case where it is not
54 required is if the 'imap_pipe' option is in use the the shell
55 command established a connection with an IMAP server in pre-au‐
56 thenticated state.
57 imap_password=password
60 If any IMAP source folders are specified or the results folder
61 is an IMAP folder, this defines the password to use to log in to
62 the IMAP server. This parameter is optional, but IMAP servers
63 normally require clients to log in, so it is normally necessary
64 to specify it.
65 maildir=list-of-folder-specifications
68 This is a colon-separated list of the Maildir folders (relative
69 to `base') that you want indexed. Any entry that ends `...' is
70 recursively scanned to find any Maildir folders underneath it.
71 More than one line starting with `maildir' can be included. In
73 this case, mairix joins the lines together with colons as though
74 a single list of folders had been given on a single very long
75 line.
76 Each colon-separated entry may be a wildcard. See the discus‐
78 sion under mbox (below) for the wildcard syntax. For example
79 maildir=zzz/foo*...
81 will match maildir folders like these (relative to the base-di‐
83 rectory)
84 zzz/foobar/xyz
86 zzz/fooquux
87 zzz/foo
88 zzz/fooabc/u/v/w
89 and
93 maildir=zzz/foo[abc]*
95 will match maildir folders like these (relative to the
97 folder_base)
98 zzz/fooa
100 zzz/fooaaaxyz
101 zzz/foobcd
102 zzz/fooccccccc
103 If a folder name contains a colon, you can write this by using
105 the sequence '\:' to escape the colon. Otherwise, the backslash
106 character is treated normally. (If the folder name actually
107 contains the sequence '\:', you're out of luck.)
108 mh=list-of-folder-specifications
111 This is a colon-separated list of the MH folders (relative to
112 `base') that you want indexed. Any entry that ends '...' is re‐
113 cursively scanned to find any MH folders underneath it.
114 More than one line starting with 'mh' can be included. In this
116 case, mairix joins the lines together with colons as though a
117 single list of folders had been given on a single very long
118 line.
119 Each colon-separated entry may be a wildcard, see the discussion
121 under maildir (above) and mbox (below) for the syntax and seman‐
122 tics of specifying wildcards.
123 mairix recognizes the types of MH folders created by the follow‐
125 ing email applications:
126 * xmh
128 * sylpheed
130 * claws-mail
132 * evolution
134 * NNML
136 * Mew
138 mbox=list-of-folder-specifications
141 This is a colon-separated list of the mbox or MMDF folders (rel‐
142 ative to `base') that you want indexed.
143 Each colon-separated item in the list can be suffixed by '...'.
145 If the item matches a regular file, that file is treated as a
146 mbox folder and the '...' suffix is ignored. If the item
147 matches a directory, a recursive scan of everything inside that
148 directory is made, and all regular files are initially consid‐
149 ered as mbox/MMDF folders. (Any directories found in this scan
150 are themselves scanned, since the scan is recursive.)
151 Each colon-separated item may contain wildcard operators, but
153 only in its final path component. The wildcard operators cur‐
154 rently supported are
155 *
158 Match zero or more characters (each character matched is arbi‐
159 trary)
160 ?
163 Match exactly one arbitrary character
164 [abcs-z]
167 Character class : match a single character from the set a, b, c,
168 s, t, u, v, w, x, y and z.
169 To include a literal ']' in the class, place it immediately af‐
171 ter the opening '['. To include a literal '-' in the class,
172 place it immediately before the closing ']'.
173 If these metacharacters are included in non-final path compo‐
175 nents, they have no special meaning.
176 Here are some examples
178 mbox=foo/bar*
181 matches 'foo/bar', 'foo/bar1', 'foo/barrrr' etc
182 mbox=foo*/bar*
185 matches 'foo*/bar', 'foo*/bar1', 'foo*/barrrr' etc
186 mbox=foo/*
189 matches 'foo/bar', 'foo/bar1', 'foo/barrrr', 'foo/foo', ´foo/x'
190 etc
191 mbox=foo...
194 matches any regular file in the tree rooted at 'foo'
195 mbox=foo/*...
198 same as before
199 mbox=foo/[a-z]*...
202 matches 'foo/a', 'foo/aardvark/xxx', 'foo/zzz/foobar',
203 ´foo/w/x/y/zzz', but not 'foo/A/foobar'
204 Regular files that are mbox folder candidates are examined in‐
206 ternally. Only files containing standard mbox 'From ' or MMDF
207 ´^A^A^A^A' separator lines will be scanned for messages.
208 If a regular file has a name ending in '.gz', and gzip support
210 is compiled into the mairix binary, the file will be treated as
211 a gzipped mbox.
212 If a regular file has a name ending in '.bz2', and bzip support
214 is compiled into the mairix binary, the file will be treated as
215 a bzip2'd mbox.
216 More than one line starting with 'mbox' can be included. In
218 this case, mairix joins the lines together with colons as though
219 a single list of folders had been given on a single very long
220 line.
221 mairix performs no locking of mbox folders when it is accessing
223 them. If a mail delivery program is modifying the mbox at the
224 same time, it is likely that one or messages in the mbox will
225 never get indexed by mairix (until the database is removed and
226 recreated from scratch, anyway.) The assumption is that mairix
227 will be used to index archive folders rather than incoming ones,
228 so this is unlikely to be much of a problem in reality.
229 mairix can support a maximum of 65536 separate mboxes, and a
231 maximum of 65536 messages within any one mbox.
232 imap=list-of-folders
235 This is a colon-separated list of the IMAP folders that you want
236 indexed.
237 These folders must all be located on the same account on the
239 same IMAP server. The configuration options imap_server and
240 imap_pipe specify how to connect to the IMAP server.
241 More than one line starting with 'imap' can be included. In
243 this case, mairix joins the lines together with colons as though
244 a single list of folders had been given on a single very long
245 line.
246 omit=list-of-glob-patterns
248 This is a colon-separated list of glob patterns for folders to
249 be omitted from the indexing. This allows wide wildcards and
250 recursive elements to be used in the maildir,mh, andmbox direc‐
251 tives, with the omit option used to selectively remove unwanted
252 folders from the folder lists.
253 Within the glob patterns, a single '*' matches any sequence of
255 characters other than '/'. However '**' matches any sequence of
256 characters including '/'. This allows glob patterns to be con‐
257 structed which have a wildcard for just one directory component,
258 or for any number of directory components.
259 The _omit_ option can be specified as many times as required so
261 that the list of patterns doesn't all have to fit on one line.
262 As an example,
264 mbox=bulk...
266 omit=bulk/spam*
267 will index all mbox folders at any level under the 'bulk' subdi‐
269 rectory of the base folder, except for those folders whose names
270 start 'bulk/spam', e.g. 'bulk/spam', 'bulk/spam2005' etc.
271 In contrast,
273 mbox=bulk...
275 omit=bulk/spam**
276 will index all mbox folders at any level under the 'bulk' subdi‐
278 rectory of the base folder, except for those folders whose names
279 start 'bulk/spam', e.g. 'bulk/spam', 'bulk/spam2005',
280 ´bulk/spam/2005', 'bulk/spam/2005/jan' etc.
281 nochecks
284 This takes no arguments. If a line starting with nochecks is
285 present, it is the equivalent of specifying the -Q flag to every
286 indexing run.
287 mfolder=match-folder-name
290 This defines the name of the folder (within the directory speci‐
291 fied by base) into which the search mode writes its output. (If
292 the mformat used is 'raw' or 'excerpt', then this setting is not
293 used and may be omitted.)
294 The mfolder setting may be over-ridden for a particular search
296 by using the -o option to mairix.
297 mairix will refuse to output search results to a folder that ap‐
299 pears to be amongst those that are indexed. This is to prevent
300 accidental deletion of emails.
301 If the first character of the mfolder value is '/' or '.', it is
303 taken as a pathname in its own right. This allows you to spec‐
304 ify absolute paths and paths relative to the current directory
305 where the mfolder should be written. Otherwise, the value of
306 mfolder is appended to the value of base, in the same way as for
307 the source folders.
308 mformat=format
311 This defines the type of folder used for the match folder where
312 the search results go. There are six valid settings for format,
313 namely 'maildir', 'mh', 'mbox', 'imap', 'raw', or 'excerpt'
314 (MMDF search results are not supported). If the 'raw' setting
315 is used then mairix will just print out the path names of the
316 files that match and no match folder will be created. If the
317 'excerpt' setting is used, mairix will also print out the To:,
318 Cc:, From:, Subject: and Date: headers of the matching messages.
319 'maildir' is the default if this option is not defined. The
320 setting is case-insensitive.
321 database=path-to-database
324 This defines the path where mairix's index database is kept.
325 You can keep this file anywhere you like.
326 Currently, mairix will place a single database file at the loca‐
328 tion indicated by path-to-database. However, a future version
329 of mairix may instead place a directory containing several files
330 at this location.
331 path-to-database should be an absolute pathname (starting with
333 '/'). If a relative pathname is used, it will be interpreted
334 relative to the current directory at the time mairix is run,
335 (not relative to the location of the mairixrc file or anything
336 like that.)
337 follow_mbox_symlinks
340 This takes no arguments. By default, mairix will skip symlinks
341 to mboxes or MMDF files when indexing. If a line starting with
342 follow_mbox_symlinks is present, mairix will follow them instead
343 of skipping them.
344 sort=date+
347 Search results will be sorted in ascending date order. No other
348 value for sort is currently accepted. In absence of this entry,
349 results are unsorted.
350 Expansions
353 The part of each line in '.mairixrc' following the equals sign can con‐
354 tain the following types of expansion:
355 Home directory expansion
358 If the sequence '~/' appears at the start of the text after the
359 equals sign, it is expanded to the user's home directory. Exam‐
360 ple:
361 database=~/Mail/mairix_database
363 Environment expansion
367 If a '$' is followed by a sequence of alpha-numeric characters
368 (or ´_'), the whole string is replaced by looking up the corre‐
369 sponding environment variable. Similarly, if '$' is followed by
370 an open brace ('{'), everything up to the next close brace is
371 looked up as an environment variable and the result replaces the
372 entire sequence.
373 Suppose in the shell we do
375 export FOO=bar
377 and the '.mairixrc' file contains
379 maildir=xxx/$FOO
381 mbox=yyy/a${FOO}b
382 this is equivalent to
384 maildir=xxx/bar
386 mbox=yyy/abarb
387 If the specified environment variable is not set, the replace‐
389 ment is the empty string.
390
393 An alternative path to the configuration file may be given with the -f
394 option to mairix(1).
395 January 2006 MAIRIXRC(5)