source: mailjam/docs/src/_build/html/_sources/configuration.txt

Configuration
=============

Mailjam has separate configuration files for the different apps (the daemon and
the variety of different clients available). Check below to read more about the
configuration file you need to modify depending on what you want to do.

.. contents::

.. _configuration_daemon:

Mailjam daemon configuration file - mailjam.conf
------------------------------------------------

All the configurations that can be applied to the :ref:`overview_mailjam_daemon`
are registered in the **mailjam.conf** file. That file contains ini-style [1]_ 
configuration parameters, separated in different *categories*.

.. note::

   The mailjam.conf file will be installed in different locations depending on
   your setup. The usual locations are:

   - */etc/mailjam/mailjam.conf* - In most Linux systems (like archlinux, 
     gentoo, fedora, debian, ubuntu, etc)

   - */usr/local/etc/mailjam/mailjam.conf* - In most BSD systems (like FreeBSD, 
     OpenBSD, NetBSD, etc)

   There is a copy of the configuration file in the *conf/* directory, within
   the sources.

.. _configuration_daemon_xmlrpc:

xmlrpc_server
+++++++++++++

This section contains the configuration parameters that modify the behaviour of
the daemon when serving content through XMLRPC [2]_. 

These are all the available parameters in this section:

.. _configuration_daemon_xmlrpc_address:

address
*******

Default: ``localhost``

The address where the daemon will be listening for XMLRPC requests. Use ``*``
to listen an all available addresses, or any specific ``hostname`` or 
``ip address`` value.

.. _configuration_daemon_xmlrpc_port:

port
****

Default: ``9876``

The port where the daemon will be listening por XMLRPC requests.

.. _configuration_daemon_xmlrpc_ssl:

ssl
***

Default: ``false`` (because ssl support hasn't been added yet)

Enables/disables SSL [3]_ support in the daemon. If ``false`` all the traffic 
to/from the server will travel unencrypted. If ``true`` all the traffic will
travel encrypted.

.. _configuration_daemon_xmlrpc_ssl_key:

ssl_key
*******

Default: ``/usr/local/etc/mailjam/ssl/mailjam.key``

Path to the ssl key used for encrypted SSL sessions.

.. warning::

   This parameter is not used right now, as ssl support hasn't been added yet)

.. _configuration_daemon_xmlrpc_ssl_crt:

ssl_crt
*******

Default: ``/usr/local/etc/mailjam/ssl/mailjam.crt``

Path to the ssl certificate used for encrypted SSL sessions.

.. warning::

   This parameter is not used right now, as ssl support hasn't been added yet)

.. _configuration_daemon_xmlrpc_logfile:

logfile
*******

Default: ``/var/log/mailjam/xmlrpc_server.log``

Path to the file where log messages will be saved
   
.. _configuration_daemon_storage:

storage
+++++++

This section contains the configuration parameters that modify the way the
daemon saves data to disk, using one of the storage backends.

These are all the available parameters in this section:

.. _configuration_daemon_storage_backend:

backend
*******

Default: ``json``

Sets the type of backend the daemon is going to use. Right now the only backend
available is ``json``.

.. _configuration_daemon_xmlrpc_path:

path
****

Default: ``/usr/local/mailjam/storage``

Path to the directory where the backend will save data.

.. _configuration_daemon_storage_lists_db:

lists_db
********

Default: ``/usr/local/mailjam/storage/mailings.json``

Path to the file where the identifiers of existing mailing lists will be saved.

.. note::

   The default configuration file contains a dynamic setting for this 
   parameter::

     lists_db = %(path)s/mailings.%(backend)s

   That means that the parameter will inherit the values of the base path and 
   the extension of the file from the *storage.path* and *storage.backend* 
   settings. 

.. seealso::

   More information about this (and other tricks) here:

   http://docs.python.org/library/configparser.html

   http://www.doughellmann.com/PyMOTW/ConfigParser

.. _configuration_daemon_xmlrpc_members_db:

members_db
**********

Default: ``/usr/local/mailjam/storage/members.json``

Path to the file where the identifiers of existing members will be saved.

.. note::

   The same notes as for the *lists_db* parameter apply to this configuration
   parameter.

.. _configuration_daemon_archive:

archive
+++++++

This section contains the configuration parameters that modify the way the
daemon saves data to disk, using one of the storage backends.

These are all the available parameters in this section:

.. _configuration_daemon_archive_enabled:

enabled
*******

Default: ``true``

Enables/disables the *archives* feature. When enabled, Mailjam saves copies of
email address into an *archive*, so they can be read later, through a web 
interface.

To disable that feature, set this to ``false``.

.. warning::

   This feature is not ready yet, so it doesn't matter if you set this to true
   or false

.. _configuration_daemon_archive_backend:

backend
*******

Default: ``json``

Sets the type of backend used to store messages into the archive.

.. warning::

   This feature is not ready yet.

.. _configuration_daemon_archive_path:

path
****

Default: ``/usr/local/mailjam/archives``

Path to the directory where the archives will be saved.

.. warning::

   This feature is not ready yet.

.. _configuration_daemon_mailing_lists:

mailing_lists
+++++++++++++

This section contains the configuration parameters that set the default 
behaviour for mailing lists.

.. warning::

   This parameters are not currently used in mailjam, we are still working
   on per-mailing-list configuration parameters.

These are all the available parameters in this section:

.. _configuration_daemon_mailing_lists_private:

private
*******

Default: ``true``

Sets if a given mailing list is *private* (only registered members can send 
messages to the list) or not (anyone can send messages to the list).

If ``false``, by default all new lists will not be private.

.. _configuration_daemon_members:

members
+++++++

This section contains the configuration parameters that set the default 
behaviour for members.

.. warning::

   This parameters are not currently used in mailjam, we are still working
   on per-member configuration parameters.

These are all the available parameters in this section:

.. _configuration_daemon_members_auto_signup:

auto_signup
***********

Default: ``false``

Enables/disables auto-registration of members to mailing lists through a public
web application. If ``true``, users can register themselves into mailing lists
using a public web interface. If ``false``, only mailing lists administrators 
will be able to add new members to the list.

.. _configuration_daemon_members_allow_chpasswd:

allow_chpasswd
**************

Default: ``false``

Enables/disables the option to update passwords by the members themselves.

If ``true``, members of a mailing list will be able to update their passwords
using a public web interface. If ``false``, only mailing lists administrators
will be able to reset those passwords.

.. _configuration_mta_client:

Mailjam MTA client configuration file - mailjam-mta.conf
--------------------------------------------------------

This file contains all the parameters to configure the 
:ref:`overview_mailjam_mta_client` properly. It contains ini-style [1]_ 
configuration parameters, separated in different *categories*.

.. note::

   The mailjam-mta.conf file will be installed in different locations 
   depending on your setup. The usual locations are:

   - */etc/mailjam/mailjam-mta.conf* - In most Linux systems (like archlinux, 
     gentoo, fedora, debian, ubuntu, etc)

   - */usr/local/etc/mailjam/mailjam-mta.conf* - In most BSD systems (like 
     FreeBSD, OpenBSD, NetBSD, etc)

   There is a copy of the configuration file in the *conf/* directory, within
   the sources.

.. _configuration_mta_client_server:

server
++++++

This section contains the configuration parameters that tell the MTA client 
where to connect when trying to interact with the 
:ref:`overview_mailjam_daemon`.

These are all the available parameters in this section:

.. _configuration_mta_client_server_address:

address
*******

Default: ``localhost``

The address where the daemon is listening for XMLRPC requests. This is
the address to where the client will try to connect to.

.. _configuration_mta_client_server_port:

port
****

Default: ``9876``

The port where the daemon accepts incoming XMLRPC requests. This is the 
port to where the client will try to connect to.

.. _configuration_mta_client_server_uri:

uri
***

Default: http://localhost:9876

This is the URI [4]_ to where the client will connect to. It is constructed
based on the values of the :ref:`configuration_mta_client_server_address`
and :ref:`configuration_mta_client_server_port` parameters.

.. note::

   The default configuration file contains a dynamic setting for this 
   parameter::

     uri = http://%(address)s:%(port)s

   That means that the parameter will inherit the values from the
   :ref:`configuration_mta_client_server_address`
   and :ref:`configuration_mta_client_server_port` parameters.

.. seealso::

   More information about this (and other tricks) here:

   http://docs.python.org/library/configparser.html

   http://www.doughellmann.com/PyMOTW/ConfigParser

.. warning::

   You can replace this with any URI you would like, **this is the parameter
   that is really used for establishing new connections** so be aware that if
   you remove the references to the 
   :ref:`configuration_mta_client_server_address` and 
   :ref:`configuration_mta_client_server_port` parameters, the values you have
   provided for those parameters will be ignored.

.. _configuration_mta_client_server_ssl:

ssl
***

Default: ``false`` (because ssl support hasn't been added yet)

Enables/disables SSL [3]_ connections to the daemon. If ``false`` all the 
traffic to/from the server will travel unencrypted. If ``true`` all the traffic 
will travel encrypted.

.. warning::

   In order to enable SSL support in the client, you have to be sure the
   :ref:`overview_mailjam_daemon` supports SSL too (check the 
   :ref:`configuration_daemon_xmlrpc_ssl` parameter in the 
   :ref:`configuration_daemon_xmlrpc` section of the 
   :ref:`daemon configuration file <configuration_daemon>`)

.. _configuration_mta_client_archive:

archive
+++++++

This section contains the configuration parameters that set where the files 
generated by the client will be stored/saved.

.. seealso::

   For more information about the kind of files the client does generate,
   take a look at the 
   :ref:`MTA client documentation <overview_mailjam_mta_client>`.

These are all the available parameters in this section:

.. _configurtion_mta_client_archive_persistent:

persistent
**********

Default: ``true``

Enables/disables the local archive for the client. If ``true``, the client
will save a copy of every email sent to the list in an internal archive, 
that could be checked/queried later. If ``false``, the emails will not be
kept on disk after being processed.
 
.. warning::

   This feature is not ready yet.


.. _configuration_mta_client_archive_path:

path
****

Default: ``/usr/local/mailjam/archive-mta``

Path to the directory where the archives will be saved.

.. warning::

   This feature is not ready yet.


.. _configuration_cli_client:

Mailjam CLI client configuration file - mailjam-cli.conf
--------------------------------------------------------

This file contains all the parameters to configure the 
:ref:`overview_mailjam_cli_client` properly. It contains ini-style [1]_ 
configuration parameters, separated in different *categories*.

.. note::

   The mailjam-cli.conf file will be installed in different locations 
   depending on your setup. The usual locations are:

   - */etc/mailjam/mailjam-cli.conf* - In most Linux systems (like archlinux, 
     gentoo, fedora, debian, ubuntu, etc)

   - */usr/local/etc/mailjam/mailjam-cli.conf* - In most BSD systems (like 
     FreeBSD, OpenBSD, NetBSD, etc)

   There is a copy of the configuration file in the *conf/* directory, within
   the sources.

.. _configuration_cli_client_server:

server
++++++

This section contains the configuration parameters that tell the cli client 
where to connect when trying to interact with the 
:ref:`overview_mailjam_daemon`.

These are all the available parameters in this section:

.. _configuration_cli_client_server_address:

address
*******

Default: ``localhost``

The address where the daemon is listening for XMLRPC requests. This is
the address to where the client will try to connect to.

.. _configuration_cli_client_server_port:

port
****

Default: ``9876``

The port where the daemon accepts incoming XMLRPC requests. This is the 
port to where the client will try to connect to.

.. _configuration_cli_client_server_uri:

uri
***

Default: http://localhost:9876

This is the URI [4]_ to where the client will connect to. It is constructed
based on the values of the :ref:`configuration_cli_client_server_address`
and :ref:`configuration_cli_client_server_port` parameters.

.. note::

   The default configuration file contains a dynamic setting for this 
   parameter::

     uri = http://%(address)s:%(port)s

   That means that the parameter will inherit the values from the
   :ref:`configuration_cli_client_server_address`
   and :ref:`configuration_cli_client_server_port` parameters.

.. seealso::

   More information about this (and other tricks) here:

   http://docs.python.org/library/configparser.html

   http://www.doughellmann.com/PyMOTW/ConfigParser

.. warning::

   You can replace this with any URI you would like, **this is the parameter
   that is really used for establishing new connections** so be aware that if
   you remove the references to the 
   :ref:`configuration_cli_client_server_address` and 
   :ref:`configuration_cli_client_server_port` parameters, the values you have
   provided for those parameters will be ignored.

.. _configuration_cli_client_server_ssl:

ssl
***

Default: ``false`` (because ssl support hasn't been added yet)

Enables/disables SSL [3]_ connections to the daemon. If ``false`` all the 
traffic to/from the server will travel unencrypted. If ``true`` all the traffic 
will travel encrypted.

.. warning::

   In order to enable SSL support in the client, you have to be sure the
   :ref:`overview_mailjam_daemon` supports SSL too (check the 
   :ref:`configuration_daemon_xmlrpc_ssl` parameter in the 
   :ref:`configuration_daemon_xmlrpc` section of the 
   :ref:`daemon configuration file <configuration_daemon>`)

.. _configuration_cli_client_history:

history
+++++++

This section contains the configuration parameters that set the behaviour
of the client feature that allows it to save a history of commands provided
by the user. 

These are all the available parameters in this section:

.. _configurtion_cli_client_archive_enabled:

enabled
*******

Default: ``true``

Enables/disables history support in the client. If ``true`` all commands 
provided by an user will be saved to disk. If ``false`` nothing will be
written to disk.

.. _configuration_cli_client_history_path:

path
****

Default: ``~/.mailjam/cli/history``

Path to the file where the list of executed commands will be saved.


.. [1] http://en.wikipedia.org/wiki/INI_file
.. [2] http://en.wikipedia.org/wiki/XML-RPC
.. [3] http://en.wikipedia.org/wiki/Secure_Socket_Layer
.. [4] http://en.wikipedia.org/wiki/Uniform_resource_identifier