manitou-mdx configuration file

manitou-mdx uses a configuration file containing the declaration of mailboxes, plugins, and variables that influence the mdx behavior. Its default location is /etc/manitou-mdx.conf, and can be overriden with the --conf=/path/to/config_file option.

The file is is divided into sections: one common section at the top of the file, followed by one section per mailbox.

The common section contains configuration options that apply by default to all mailboxes. Then each mailbox's section can override specific options, or provide values for options that are not referenced in the common section. Options appearing in a mailbox section only apply to that mailbox.

Example

[common]
db_connect_string = Dbi:Pg:dbname=mail;user=mailadmin
local_delivery_agent=/usr/sbin/sendmail -f $FROM$ -t
plugins_directory = /usr/share/manitou/plugins

# one mailbox
[mymail@domain.tld]
index_words=yes
mailfiles_directory=/var/manitou/spool/mymail

# another mailbox
[mymail2@other-domain.tld]
mailfiles_directory=/var/manitou/spool/mymail2
index_words=no
preferred_datetime=sender

Syntax:

blank lines and lines starting with # are ignored
blanks around the first '=' sign of a line are ignored.
trailing blanks are ignored.
Some parameters accept multi-lines values, in which case a backslash (\) at the end of the line is the continuation character to use.

Parameters (alphabetical list)

alive_interval

[common] section only.

When this parameter is set, manitou-mdx will update the runtime_info table every 'alive_interval' seconds, with an entry containing the current timestamp (timestamp means the current date and time expressed as a number of seconds elapsed since Jan,1st 1970 UTC). The timestamp is put in the runtime_info.rt_value column of the row that matches rt_key='last_alive'. Its purpose is to be read by an external process to periodically check that manitou-mdx is alive and running.
Since it involves a write into the database, the value for 'alive_interval' should not be too small or the table will get rapidly bloated and performance degraded. For example any value below 60s is probably unnecessary small, while 600s looks reasonable.
The default is to leave it unset, meaning there is no update of the last_alive entry. A value of zero has the same meaning.

Example:

# signal every 500s that we're up 
alive_interval=500

db_connect_string

[common] section only.

The connection string used to connect to the manitou-mail database, formatted as needed by the DBD::Pg perl driver. If it's not specified, the MANITOU_CONNECT_STRING environment variable will be used instead; if that variable is not set, the program will fail at startup time.

Example:

db_connect_string = dbi:Pg:dbname=mail;user=mailadmin;password=pass;host=dbserver

The dbname, user, password and host parameters should suffice for most installations. However for more customized setups, additional options can be provided in the connect string. Please refer to the documentation of DBD::Pg and/or the PostgreSQL manual for more information.

detach_text_plain

[common] or mailboxes sections.

When set to "yes", text/plain attachments with no filename get included into the body of the messages instead of being kept separate. Such attachments are typically the text part of HTML messages, so it's more convenient to have them in the body.

The default is yes.

flush_word_index_interval

[common] section only.

It is the number of seconds during which word vectors used by the full text indexer are kept in memory, before being flushed to the database. During this lapse of time, the newly imported mails are not yet full-text searchable by other programs such as the user interface.

Flushing the vectors induces a spike of disk activity in the database, so increasing the delay between flushings reduces the load on the database.

This parameter can be changed in combination with flush_word_index_max_queued. It is ignored if index_words is set to "no".

The default value is 300 seconds.

flush_word_index_max_queued

[common] section only.

It is the maximum number of messages for which word vectors are kept in memory before being flushed to the database, and thus made available to the full-text search functionality. The parameter is ignored if index_words is set to "no".

The default value is 100 messages.

incoming_check_interval

[common] section only.

It is the number of seconds that manitou-mdx will wait before checking for new messages to be imported from the spool directory.

Setting it too small will generate too much unnecessary disk activity. When at least one file is available, all messages ready to be imported will be processed.

The default is 60 (one check every minute)

Example:

# check for new mail every 120s
incoming_check_interval=120

incoming_mimeprocess_plugins

[common] or mailboxes sections.

This is a multiline entry that declares the Perl plugins that should be run against incoming messages at import time, after having been parsed and before being put into the database. Refer to the section on plugins for more.

Example:

incoming_mimeprocess_plugins = bayes_classify \
			antispam("spamtag")

incoming_postprocess_plugins

[common] or mailboxes sections.

This is a multiline entry that declares the Perl plugins that should be run against incoming messages at import time, after the message has been put into the database. Refer to the section on plugins for more.

incoming_preprocess_plugins

[common] or mailboxes sections.

This is a multiline entry that declares the Perl plugins that should be run against incoming messages at import time, before the mailfile is opened. Refer to the section on plugins for more.

index_words

[common] or mailboxes sections.

A boolean value indicating whether manitou-mdx should index the body contents of incoming and outgoing messages. Such indexing allows the use of the fast words-search capability in manitou's user interface. It may be desirable to turn it off to reduce the database's disk usage.
That directive can appear in the [common] section and be overriden by mailboxes sections. It defaults to yes.
Example:

[mailbox@domain.tld]
index_words = no

local_delivery_agent

[common] section only.

The external command to which outgoing mail is passed by manitou-mdx. This is typically a sendmail-like command along with its arguments. The message is passed to the command through its standard input. If a substring $FROM$ is found, it will be substituted by the email address of the identity attached to the message when it was composed.
Example:

[common]
local_delivery_agent=/usr/lib/sendmail -f $FROM$ -t

mailfiles_directory

mailboxes sections

The path of the directory where incoming mailfiles are looked for. Is is the fact that a mailfile is found in a mailbox directory that tells the mdx that the message belongs to this mailbox.
Example:

[support@domain.tld]
mailfiles_directory=/var/tmp/manitou/spool/support

maintenance_plugins

[common] section.

Multi-line declaration of plugins that run periodically. The period is either a time interval such as 10mn or 2h, or a point in time in the day such as 20:30.

Example:

# vacuum every 2 hours
maintenance_plugins = 2h vacuum

no_send

[common] or mailboxes sections.

Set to yes if manitou-mdx should not send any outgoing message, even if such messages are available in the database.

If set to no or not set at all, manitou-mdx will pass outgoing messages to the local mailer and mark them as sent in the database.

outgoing_bcc

[common] or mailboxes sections.

An email address to which all outgoing email will be carbon-copied, using the Bcc field. Several email addresses separated by commas can also be used. This can be used for debugging, backup, or tracking purposes.

Example:

# blind-copy all outgoing mail to the local 'outgoing' address
outgoing_bcc=outgoing@localhost

outgoing_check_interval

[common] section only.

It is the number of seconds that manitou-mdx will sleep before checking for pending outgoing messages to send. Checking for outgoing messages is implented as a fast SQL query to the database.

The default is 5.

Example:

# check for new mail to send every 60s
outgoing_check_interval=60

plugins_directory

[common] section only

A directory path where manitou-mdx plugins are to be found. This entry has been obsoleted in version 0.9.7 since plugins now reside in ($libdir)/Manitou/Plugins with $libdir being determined at install time.

postprocess_mailfile_cmd

[common] or mailboxes sections.

A shell command run each time a mailfile has been processed, with the arguments below:

$0: a string telling the result of the mailfile processing, with three possible values: imported, error or discarded. A message is discarded when the action resulting from applying the filtering rules is "delete".
$1: the current name and path of the mailfile
$2: the mailbox's name (based on this config file)

Example: This postprocess command copies the mailfile to a daily tar archive and then removes it.

postprocess_mailfile_cmd = cd `dirname $1` && tar -f /var/manitou/archive/daily-$0.`date +%Y%m%d`.tar -r `basename $1` && rm $1

Note that the command has to be a one-liner. For complex processing, it is therefore better to point postprocess_mailfile_cmd to a user-made separate shell script, like this:

postprocess_mailfile_cmd = /usr/manitou/bin/postprocess.sh $0 $1 $2

preferred_charset

[common] or mailboxes sections.

The charset to which the bodies of outgoing mail should be converted before being set. Examples of values are utf-8, iso-8859-1, iso-8859-15, us-ascii...

When left unset, manitou-mdx will try to find a suitable charset based on the database encoding and possibly the contents of the message to send.

Example:

# use utf-8 to encode anything
preferred_charset = utf-8

preferred_datetime

[common] or mailboxes sections.

Each message has a internal date field in the database whose value can differ from the mail's headers date field. The header contains the sender's computer date at the time the message was sent. This date can be wrong or the delay between the sending and the fetch of the message into the database can be significant.

The 'preferred_datetime' parameter tells whether the internal date field of an incoming message should be set to the sender date or to the message's arrival date. The possible values are:

sender: the sender's date is used. Recommended if you're often offline and the incoming messages are not necessarily imported into manitou-mail on a regular basis, in a stream-like fashion. Note that the sender's date can be wrong (badly formatted or faked by the sender).
mtime: the last modification's date of the file containing the message. Recommended if mail is fetched on a regular basis or if the arrival date is to be considered more significant than the sender's date.

The default is mtime.

security_checks

[common] section only.

When set to "yes", the tmpdir directory permissions and owner are checked to make sure that no other user can create files or symlinks into it. If that check fails, the program exits immediately. When security_checks is set to "no", the result of the test is ignored.

The default is set to yes.

Example:

security_checks=yes

store_filenames

[common] or mailboxes sections.

A boolean value telling whether each mailfile's name and path should be stored into the files table of the database, associated with its mail_id. If the mailfiles are not deleted after processing, that table allows to retrieve a message in its original non-decoded form from it's database mail_id.

The default is set to yes

Example:

store_filenames=no

See table:file documentation for more information on this table.

store_raw_mail

[common] or mailboxes sections.

A boolean value telling if the original contents of imported mail messages should be stored as a binary large object in the raw_mail table. This allows to retrieve a message in its original non-decoded form by it's database mail_id, even after the mailfile has been deleted.

The default is set to no

Example:

store_raw_mail=yes

tags_incoming

[common] or mailboxes sections.

This is a multi-line entry that lists the tags that should be applied to all the messages coming into a mailbox. Note that a plugin called on incoming messages is still able to remove or add any tag. Each tag's name must be on a line by itself, consecutive lines being separated by a backslash followed by a newline. White spaces before the backslash will be ignored, as well as white spaces between the start of the line and the first non-space character. All the other characters are considered to be part of the tag's name. If a tag declared in the configuration file doesn't exist in the database, it will be inserted into it as soon as it's needed.
A typical use of tags_incoming, for installations that use a single database schema for several mailboxes, is to create a tag per mailbox.
Example:

[one-mailbox@domain.tld]
tags_incoming = tag1 \
		one-mailbox-tag\		# comment
		tag2

tmpdir

[common] section only.

A directory where temporary files will be created for attachments. That directory, if it already exists, should have such permissions that no other user than the one running manitou-mdx should be able to read or write into. It defaults to /var/tmp/manitou- where uid is the unix user-id running the program.

Example:

# system-wide temp directory
tmpdir=/var/tmp/manitou