1MAIRIXRC(5)                   File Formats Manual                  MAIRIXRC(5)
2
3
4

NAME

6       mairixrc - configuration file for mairix(1)
7

SYNOPSIS

9       $HOME/.mairixrc
10

DESCRIPTION

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
15       mairix searches for this file at $HOME/.mairixrc unless the  -f  option
16       is used.
17
18       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
22
23   Comments
24       Any line starting with a '#' character is treated as a comment.
25
26
27   Directives
28       base=base-directory
29              This defines the path to the common parent directory of all your
30              maildir folders.
31
32
33       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
39
40       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
47
48       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
58
59       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
66
67       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
72              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
77              Each  colon-separated  entry may be a wildcard.  See the discus‐
78              sion under mbox (below) for the wildcard syntax.  For example
79
80                   maildir=zzz/foo*...
81
82              will match maildir folders like these (relative to the  base-di‐
83              rectory)
84
85                   zzz/foobar/xyz
86                   zzz/fooquux
87                   zzz/foo
88                   zzz/fooabc/u/v/w
89
90
91
92              and
93
94                   maildir=zzz/foo[abc]*
95
96              will   match   maildir  folders  like  these  (relative  to  the
97              folder_base)
98
99                   zzz/fooa
100                   zzz/fooaaaxyz
101                   zzz/foobcd
102                   zzz/fooccccccc
103
104              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
109
110       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
115              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
120              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
124              mairix recognizes the types of MH folders created by the follow‐
125              ing email applications:
126
127              *      xmh
128
129              *      sylpheed
130
131              *      claws-mail
132
133              *      evolution
134
135              *      NNML
136
137              *      Mew
138
139
140       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
144              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
152              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
156
157       *
158              Match zero or more characters (each character matched  is  arbi‐
159              trary)
160
161
162       ?
163              Match exactly one arbitrary character
164
165
166       [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
170              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
174              If these metacharacters are included in  non-final  path  compo‐
175              nents, they have no special meaning.
176
177              Here are some examples
178
179
180       mbox=foo/bar*
181              matches 'foo/bar', 'foo/bar1', 'foo/barrrr' etc
182
183
184       mbox=foo*/bar*
185              matches 'foo*/bar', 'foo*/bar1', 'foo*/barrrr' etc
186
187
188       mbox=foo/*
189              matches  'foo/bar', 'foo/bar1', 'foo/barrrr', 'foo/foo', ´foo/x'
190              etc
191
192
193       mbox=foo...
194              matches any regular file in the tree rooted at 'foo'
195
196
197       mbox=foo/*...
198              same as before
199
200
201       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
205              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
209              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
213              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
217              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
222              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
230              mairix can support a maximum of 65536  separate  mboxes,  and  a
231              maximum of 65536 messages within any one mbox.
232
233
234       imap=list-of-folders
235              This is a colon-separated list of the IMAP folders that you want
236              indexed.
237
238              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
242              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
247       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
254              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
260              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
263              As an example,
264
265                   mbox=bulk...
266                   omit=bulk/spam*
267
268              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
272              In contrast,
273
274                   mbox=bulk...
275                   omit=bulk/spam**
276
277              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
282
283       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
288
289       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
295              The mfolder setting may be over-ridden for a  particular  search
296              by using the -o option to mairix.
297
298              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
302              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
309
310       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
322
323       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
327              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
332              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
338
339       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
345
346       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
351
352   Expansions
353       The part of each line in '.mairixrc' following the equals sign can con‐
354       tain the following types of expansion:
355
356
357       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
362                   database=~/Mail/mairix_database
363
364
365
366       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
374              Suppose in the shell we do
375
376                   export FOO=bar
377
378              and the '.mairixrc' file contains
379
380                   maildir=xxx/$FOO
381                   mbox=yyy/a${FOO}b
382
383              this is equivalent to
384
385                   maildir=xxx/bar
386                   mbox=yyy/abarb
387
388              If the specified environment variable is not set,  the  replace‐
389              ment is the empty string.
390
391

NOTES

393       An  alternative path to the configuration file may be given with the -f
394       option to mairix(1).
395
396
397
398
399
400                                 January 2006                      MAIRIXRC(5)
Impressum