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
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
44 instead of a TCP/IP connection. This option is mutually exclu‐
45 sive 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-aut‐
56 enticated 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-
83 directory)
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
113 recursively 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 folders (relative to
142 `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 folders. (Any directories found in this scan are
150 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
171 after 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
206 internally. Only files containing standard mbox 'From ' separa‐
207 tor 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 constrast,
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
299 appears to be amongst those that are indexed. This is to pre‐
300 vent 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'. If
314 the 'raw' setting is used then mairix will just print out the
315 path names of the files that match and no match folder will be
316 created. If the 'excerpt' setting is used, mairix will also
317 print out the To:, Cc:, From:, Subject: and Date: headers of the
318 matching messages. 'maildir' is the default if this option is
319 not defined. The setting is case-insensitive.
320 database=path-to-database
323 This defines the path where mairix's index database is kept.
324 You can keep this file anywhere you like.
325 Currently, mairix will place a single database file at the loca‐
327 tion indicated by path-to-database. However, a future version
328 of mairix may instead place a directory containing several files
329 at this location.
330 path-to-database should be an absolute pathname (starting with
332 '/'). If a relative pathname is used, it will be interpreted
333 relative to the current directory at the time mairix is run,
334 (not relative to the location of the mairixrc file or anything
335 like that.)
336 follow_mbox_symlinks
339 This takes no arguments. By default, mairix will skip symlinks
340 to mboxes when indexing. If a line starting with fol‐
341 low_mbox_symlinks is present, mairix will follow them instead of
342 skipping them.
343 Expansions
346 The part of each line in '.mairixrc' following the equals sign can con‐
347 tain the following types of expansion:
348 Home directory expansion
351 If the sequence '~/' appears at the start of the text after the
352 equals sign, it is expanded to the user's home directory. Exam‐
353 ple:
354 database=~/Mail/mairix_database
356 Environment expansion
360 If a '$' is followed by a sequence of alpha-numeric characters
361 (or ´_'), the whole string is replaced by looking up the corre‐
362 sponding environment variable. Similarly, if '$' is followed by
363 an open brace ('{'), everything up to the next close brace is
364 looked up as an environment variable and the result replaces the
365 entire sequence.
366 Suppose in the shell we do
368 export FOO=bar
370 and the '.mairixrc' file contains
372 maildir=xxx/$FOO
374 mbox=yyy/a${FOO}b
375 this is equivalent to
377 maildir=xxx/bar
379 mbox=yyy/abarb
380 If the specified environment variable is not set, the replace‐
382 ment is the empty string.
383
386 An alternative path to the configuration file may be given with the -f
387 option to mairix(1).
388 January 2006 MAIRIXRC(5)