Changeset 27:b1d527287347 in mailjam for docs/src/running.rst

Timestamp:

May 23, 2012, 6:32:54 PM (12 years ago)

Author:

Borja Lopez <borja@…>

Branch:

default

Phase:

public

Message:

Added more information to the README file

Updated the architecture scheme so it fits the renaming of the project
to mailjam

Fixed the search path for configuration files. Now it searches on /etc
first, /usr/local/etc then.

Added more docs regarding the installation, configuration and running
of each component

File:

• docs/src/running.rst (modified) (1 diff)

docs/src/running.rst

@@ -2 +2 @@
 ===============
 
+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