Manitou-Mail Home

2. Configuration file

2.1. Location

By default, the configuration file is located at /etc/manitou-mdx.conf. Both manitou-mgr and manitou-mdx accept the --conf option to specify an alternative file.

2.2. Structure

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

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

2.2.1. Syntax rules

  • 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.

2.2.2. Example

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

# one identity
[mymail@example.com]
index_words=yes
mailfiles_directory=/var/manitou/spool/mymail

# another identity
[mymail2@example.net]
mailfiles_directory=/var/manitou/spool/mymail2
index_words=no
preferred_datetime=sender

2.3. Alphabetical list of options

2.3.1. alive_interval

In: [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.

2.3.2. auto_db_reconnect

In: [common] section only.

When set to "yes", manitou-mdx will try to reconnect to the database when an error occurs that may be due to a loss of its connection to the database. When set to "false", it will abort with a fatal error.

The default is yes.

2.3.3. db_connect_string

In: [common] section only.

The connection string used to connect to the manitou-mail database, formatted as needed by the DBD::Pg perl driver. 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.

2.3.4. detach_text_plain

In: [common] or identities 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.

2.3.5. flush_word_index_interval

In: [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.

2.3.6. flush_word_index_max_queued

In: [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.

2.3.7. incoming_check_interval

In: [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

2.3.8. incoming_mimeprocess_plugins

In: [common] or identities 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 stored into the database. See mdx plugins for more information on plugins.

Example:

incoming_mimeprocess_plugins = bayes_classify \
			antispam("spamtag")

2.3.9. incoming_postprocess_plugins

In: [common] or identities 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. See mdx plugins for more information on plugins.

2.3.10. incoming_preprocess_plugins

In: [common] or identities 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. See mdx plugins for more information on plugins.

2.3.11. index_words

In: [common] or identities 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 identities sections. It defaults to yes.

Example:

[mailbox@example.com]
index_words = no

2.3.12. index_words_accent_mode

In: [common] or identities sections.

The inverted word index can strip accents and diacritic marks from words to make it possible to search in accent-insensitive mode. Additionally it can store both versions of words: the original and accent-stripped version. This entry defines the behavior of the word extractor with regards to accents:

  • dual: the default value. Index both forms of any accented word, with and without accents.
  • strip: index only the form without accents.
  • keep: index the word as is, without any consideration for accents or lack thereof.

Example:

[mailbox@example.com]
index_words_accent_mode = strip

2.3.13. index_words_extractors

In: [common] or identities sections. Multi-line declaration.

Word extractors are external commands that are launched by manitou-mdx with attachments contents piped to their standard input. They extract words and output them encoded in utf-8 to the standard output. manitou-mdx associates these words in the inverted word index to the message being processed.

Example:

[mailbox@example.com]
index_words_extractors = application/pdf: /opt/scripts/pdf2text \
	application/msword: /opt/scripts/word2text

2.3.14. index_words_html_parts

In: [common] or identities sections.

A boolean value indicating whether manitou-mdx should index the HTML contents of incoming and outgoing messages. This option can appear in the [common] section and be overriden by identities sections. It defaults to yes.

Example:

[mailbox@example.com]
index_words_html_parts = no

2.3.15. init_sql

In: [common] section.

A multiline entry with SQL statements to be executed after each successful database connection. The typical use case is to SET specific SQL parameters.

Example:

init_sql = SET TIME ZONE 'Europe/Rome' \
  SET search_path TO myschema,public

2.3.16. local_delivery_agent

In: [common] or identities sections.

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 the $FROM$ substring is found, it will be substituted with 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

2.3.17. mailfiles_directory

In: identities sections

The path of the directory where incoming mailfiles are looked for. It is the fact that a mailfile is found in the associated spool directory that tells the mdx that the message is to be associated with this identity. Another possible source of incoming mail is spool_maildir for a maildir directory structure.

Example:

[support@example.com]
mailfiles_directory=/var/tmp/manitou/spool/support

2.3.18. maintenance_plugins

In: [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

2.3.19. no_send

In: [common] or identities 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.

2.3.20. outgoing_bcc

In: [common] or identities 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

2.3.21. outgoing_check_interval

In: [common] section only.

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

The default is 5.

Example:

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

2.3.22. plugins_directory

In: [common] section only

The location of a directory where manitou-mdx plugins are to be searched first. Plugins are perl modules named after the plugin name followed by a .pm suffix. When specified, this directory must contain a Manitou/Plugins subdirectory, which itself contains the module files.

By default, plugins_directory is not specified and the Perl interpreter follows its own algorithm to find the manitou-mdx plugin modules as it does with any other Perl module.

2.3.23. postprocess_mailfile_cmd

In: [common] or identities sections.

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

  • $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 identity's email (based on this config file)

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


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 necessary to point postprocess_mailfile_cmd to a user-made shell script. Example:

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

2.3.24. preferred_charset

In: [common] or identities 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

2.3.25. preferred_datetime

In: [common] or identities 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.

2.3.26. security_checks

In: [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

2.3.27. spool_maildir

In: identities sections

The absolute path of one or several maildir structure from which incoming mail is imported. Multiple paths are separated by colons. Inside the maildir, files immediately under the subdirectories new/ and cur/ are imported and deleted upon success. Folders are not recursed into. Each folder to import from must be explicitly listed with its absolute path.

Example:

[manitou@example.com]
spool_maildir=/var/lib/manitou/Maildir:/var/lib/manitou/Maildir/.mailing-lists

Another possible source of incoming mail is Section 2.3.17, “mailfiles_directory” for a directory containing *.received files.

2.3.28. store_filenames

In: [common] or identities 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 files for more information on this table.

2.3.29. store_raw_mail

In: [common] or identities 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

2.3.30. tags_incoming

In: [common] or identities sections.

This is a multi-line entry that lists the tags that should be applied to all the messages coming from a spool. 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 identities, is to create a tag per identity.

Example:

[one-email@example.com]
tags_incoming = tag1 \
		one-email-tag\		# comment
		tag2

2.3.31. tmpdir

In: [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. By default, a new temporary directory will be created in a location that depends on the configuration of the operating system.

Example:

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