MAIRIXRC(5)

NAME
mairixrc - configuration file for mairix(1)

SYNOPSIS
$HOME/.mairixrc

DESCRIPTION

The mairixrc file tells mairix where your mail folders are located. It also tells mairix where the results of searches are to be written.

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

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

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

  Directives

base=base-directory
    This defines the path to the common parent directory of all your maildir folders.

imap_server=hostname
    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.

imap_pipe=shell-command
    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.

imap_username=username
    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.

imap_password=password
    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.

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

    maildir=zzz/foo*...
    will match maildir folders like these (relative to the
    base-directory)

        zzz/foobar/xyz
        zzz/fooquux
        zzz/foo
        zzz/fooabc/u/v/w

        and

            maildir=zzz/foo[abc]*
            will match maildir folders like these (relative to the folder_base)

                zzz/fooa
                zzz/fooaaaxyz
                zzz/foobcd
                zzz/fooccccccc
                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.)

                mh=list-of-folder-specifications
                    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.

                    mairix
                    recognizes the types of MH folders created by the following email applications:

                    *   xmh

                    *   sylpheed

                    *   claws-mail

                    *   evolution

                    *   NNML

                    *   Mew

                mbox=list-of-folder-specifications
                    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

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

                ?
                    Match exactly one arbitrary character

                [abcs-z]
                    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

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

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

                mbox=foo/*
                    matches 'foo/bar', 'foo/bar1', 'foo/barrrr', 'foo/foo',
                    'foo/x' etc

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

                mbox=foo/*...
                    same as before

                mbox=foo/[a-z]*...
                    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
                    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
                    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,
                    mairix
                    joins the lines together with colons as though a
                    single list of folders had been given on a single very long line.

                    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
                    mairix
                    (until the database is removed and recreated from scratch, anyway.)  The
                    assumption is that
                    mairix
                    will be used to index archive folders rather than incoming ones, so this is
                    unlikely to be much of a problem in reality.

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

                imap=list-of-folders
                    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,
                    mairix
                    joins the lines together with colons as though a
                    single list of folders had been given on a single very long line.

                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
                    maildir,mh, andmbox
                    directives, with the
                    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,

                    mbox=bulk...
                    omit=bulk/spam*
                    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,

                        mbox=bulk...
                        omit=bulk/spam**
                        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.

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

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

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

                            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.

                        mformat=format
                            This defines the type of folder used for the match folder where
                            the search results go.  There are six valid settings for
                            format,
                            namely 'maildir', 'mh', 'mbox', 'imap', 'raw', or 'excerpt'.  If the 'raw' setting is
                            used then
                            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,
                            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.

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

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

                            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
                            mairix
                            is run,
                            (not
                            relative to the location of the
                            mairixrc
                            file or anything like that.)

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

  Expansions

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

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:

    database=~/Mail/mairix_database

    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

        export FOO=bar
        and the '.mairixrc' file contains

            maildir=xxx/$FOO
            mbox=yyy/a${FOO}b
            this is equivalent to

                maildir=xxx/bar
                mbox=yyy/abarb
                If the specified environment variable is not set, the replacement
                is the empty string.

NOTES

An alternative path to the configuration file may be given with the -f option to mairix(1).