source: mailjam/docs/src/_build/html/_sources/running.txt@ 27:b1d527287347

Running Mailjam
===============

In order to run Mailjam, you have to run the different components, depending on
what you want to do. Basically, you will need to run a server 
(:ref:`overview_mailjam_daemon`) all the time, then you will need one 
:ref:`overview_mailjam_mta_client` per mailing list. 

Ocasionally, you will need to add or delete a mailing list, or edit its 
information, members list, etc. To do that, you will have to run a Mailjam 
client (either the :ref:`CLI client <overview_mailjam_cli_client>` or the
:ref:`Web client <overview_mailjam_web_client>`).

Keep reading if you want to learn more about the way you can start each 
component, the different arguments/parameters you can provide on startup, etc.

.. warning::

   Remember that, before being able to run any component, you have to 
   :ref:`set up proper configuration files <install_setting_up_mailjam>`. You
   can learn more about Mailjam configuration files in the 
   :doc:`configuration files documentation <configuration>`.

.. contents::

.. _running_daemon:

The daemon
----------

First component you should start is the :ref:`overview_mailjam_daemon`. It is
quite easy, just run this command from a shell/console::

  mailjam-server

The server process will read the :ref:`mailjam.conf <configuration_daemon>` 
configuration file, will prepare everything and will start listening for XMLRPC
requests on *localhost:9876*

.. warning::

   *localhost:9876* is the default value provided by the default configuration
   files. If you have modified that, it will be a different *address:port* 
   combination.

.. warning::

   If you didn't add a valid configuration file to one of the 
   :ref:`default paths <install_setting_up_mailjam>`, the server will refuse to
   start, giving you an error message.

.. warning::

   As of the current version of Mailjam, there are no pre-made init scripts that
   can handle the start/stop/restart of the daemon, but those will be added in
   one of the future releases.

.. _running_daemon_parameters:

Additional parameters
+++++++++++++++++++++

You can pass some parameters to *mailjam-server* to modify the behaviour of
the daemon or get more information.

.. note::

   Remember that the proper way to modify the behaviour of the daemon is 
   editing its configuration file, :ref:`mailjam.conf <configuration_daemon>`

.. _running_daemon_help:

--help
******

You can get some help by passing the *-h* or *--help* parameters::

  mailjam-server -h

::

  mailjam-server --help

.. _running_daemon_config:

--config
********

You can set the path to the config file the server will load on startup,
passing the *-c* or *--config* parameters::

  mailjam-server -c /home/mailjam/mailjam.conf

::

  mailjam-server --config /home/mailjam/mailjam.conf
  
.. warning::

   If the file does not exist, or if it is not a valid configuration file,
   an error will be shown and the daemon will refuse to start.

.. _running_daemon_version:

--version
*********

You can check the version of the mailjam server you are trying to run by
passing the *-v* or *--version* parameters::

  mailjam-server -v

::

  mailjam-server --version


.. _running_cli_client:

The CLI client
--------------



.. _running_mta_client:

The MTA client
--------------

Once you have your :ref:`daemon running <running_daemon>`, you have to add
as many :ref:`MTA clients <overview_mailjam_mta_client>` as mailing lists you
want to manage to your mail server.

.. _running_mta_client_quick:

Quick configuration (you are a mail-servers-master)
+++++++++++++++++++++++++++++++++++++++++++++++++++

Edit your mail server aliases file [1]_ (probably */etc/aliases* or 
*/etc/mail/aliases*) and add an entry like::

  list@mydomain.com: "|/usr/local/bin/mailjam-mta -a list@mydomain.com -i -"

.. warning::
   
   replace *list@mydomain.com* with the real address of your mailing list

.. warning::

   replace */usr/local/bin/mailjam-mta* with the real path to your mailjam-mta
   installation

Rebuild your *aliases* database::

  newaliases

.. warning::

   Refer to your OS documentation to see how you can rebuild *aliases*. In most
   unix-like systems it is done by the newaliases [2]_ command.

.. _running_mta_client_explained:

Explained configuration (you really want to know what's happening here)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

When new messages arrive at your mail server for your mailing list address 
(let's use the example address *list@mydomain.com*) one of the steps in the
process that checks the message, it's origin, destination, contents, etc is
the step where the mail server checks its internal *aliases* database, that is,
a list of *special* addresses that, instead of being *real* addresses, they are
related to some other addresses in some way.

Most MTAs out there support one very *convenient* feature that is to *pipe* the
contents of the message (headers and body) to a given shell command. That means
that the all the received data will be sent to an external command for it to 
process such data.

**Here is where mailjam-mta comes in**.

What you have to do is just tell your mail server that all messages with 
destination *list@mydomain.com* (to keep using the same example address) will be
*piped* to mailman-mta. The Mailjam MTA client will then know what to do with 
the message, performing some checks and re-sending it to the proper destinations
(the members/suscriptors of the given mailing list).

So, first thing you have to find out is **where is your aliases file?**.

In unix-like systems, like the different Linux distributions or the different 
BSD flavours, that file is */etc/mail/aliases* or */etc/aliases* (usually one is
a simbolic link to the other).

.. note::

   Usually the aliases file contains some lines like::

     MAILER-DAEMON: postmaster
     postmaster: root

Once you've found out where the file is, edit it and add this line to the bottom
of the file::

  list@mydomain.com: "|/usr/local/bin/mailjam-mta -a list@mydomain.com -i -"

.. warning::
   
   replace *list@mydomain.com* with the real address of your mailing list

.. warning::

   replace */usr/local/bin/mailjam-mta* with the real path to your mailjam-mta
   installation

There you are telling your mail server that any message coming **to** 
*list@mydomain.com* will be passed to the mailjam-mta command, passing some 
parameters to it:

- **-a list@mydomain.com** tells mailjam-mta that the message is actually for
  that mailing list. The MTA client will then use that value to check (against
  the mailjam daemon) if it is a valid mailing list.

- **-i -** tells mailjam-mta that the message will be *piped* directly. This is
  important, as mailjam-mta can read the messages from files, but in this case
  the mail server will *pipe* the data directly to mailjam-mta.

Once you've added that line to your *aliases* file, you have to rebuild your 
*aliases* database::

  newaliases

.. warning::

   Refer to your OS documentation to see how you can rebuild *aliases*. In most
   unix-like systems it is done by the newaliases [2]_ command.

And you are done. Everything is ready now.

.. _running_mta_client_parameters:

Additional parameters
+++++++++++++++++++++

You can pass some parameters to *mailjam-mta* to modify the behaviour of
the client or get more information.

.. note::

   Remember that the proper way to modify the behaviour of the client is 
   editing its configuration file, 
   :ref:`mailjam-mta.conf <configuration_mta_client>`

.. _running_mta_client_help:

--help
******

You can get some help by passing the *-h* or *--help* parameters::

  mailjam-mta -h

::

  mailjam-mta --help

.. _running_mta_client_config:

--config
********

You can set the path to the config file the client will load on startup,
passing the *-c* or *--config* parameters::

  mailjam-mta -c /home/mailjam/mailjam-mta.conf

::

  mailjam-mta --config /home/mailjam/mailjam-mta.conf
  
.. warning::

   If the file does not exist, or if it is not a valid configuration file,
   an error will be shown and the client will refuse to start.

.. _running_mta_client_version:

--version
*********

You can check the version of the mailjam client you are trying to run by
passing the *-v* or *--version* parameters::

  mailjam-mta -v

::

  mailjam-mta --version

.. _running_mta_client_address:

--address (required)
********************

This parameter is required (you have to provide it with a value in order to
run the mailjam-mta). It sets the address of the mailing list managed by this
MTA client instance.

The MTA client will use the provided value to do some checks on the daemon,
retrieving all the needed data to perform its tasks.

You can pass a valid address using both the *-a* and *--address* parameters::

  mailjam-mta -a list@mydomain.com

::

  mailjam-mta --address list@mydomain.com

.. _running_mta_client_input:

--input
*******

This parameter tells mailjam-mta from where it has to read the message sent 
to the mailing list. That could be a local file (to be readed from disk) or
a stream of data coming directly from the standard input (*stdin*).

For a regular configuration/setup, the second option is preferred, as the mail
server will send the stream of data directly to mailjam-mta (as 
:ref:`explained before <running_mta_client_explained>`)::

  mailjam-mta -i -

::

  mailjam-mta --input -

But perhaps some time you would like to send (again) a message you have on disk,
that could be done easily, passing the path to the file containing that message
to mailjam-mta::

  mailjam-mta -i /home/backups/mail/that-important-mail.txt

::

  mailjam-mta -input /home/backups/mail/that-important-mail.txt


.. _running_web_client:

The Web client
--------------

.. [1] http://en.wikipedia.org/wiki/Email_alias
.. [2] http://www.freebsd.org/cgi/man.cgi?query=newaliases