Changeset 27:b1d527287347 in mailjam for docs/src/_build/html/_sources

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

Location:

docs/src/_build/html/_sources

Files:

• configuration.txt (modified) (4 diffs)
• examples.txt (modified) (1 diff)
• install.txt (modified) (12 diffs)
• overview.txt (modified) (1 diff)
• running.txt (modified) (1 diff)

docs/src/_build/html/_sources/configuration.txt

@@ -2 +2 @@
 =============
 
+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
----------------------------------
-
-All the configurations that can be applied to the Mailjam daemon are registered
-in the **mailjam.conf** file. That file contains ini-style [1]_ configuration 
-parameters, separated in different *categories*.
+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::
@@ -18 +22 @@
    your setup. The usual locations are:
 
-   - */etc/mailjam.conf* - In most Linux systems (like archlinux, gentoo, 
-     fedora, debian, ubuntu, etc)
-
-   - */usr/local/etc/mailjam.conf* - In most BSD systems (like FreeBSD, OpenBSD,
-     NetBSD, etc)
+   - */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
@@ -62 +66 @@
 ***
 
-Default: ``off`` (because ssl support hasn't been added yet)
-
-Enables/disables SSL [3]_ support in the daemon. If ``off`` all the traffic 
-to/from the server will travel unencrypted. If ``on`` all the traffic will
+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.
 
@@ -295 +299 @@
 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

docs/src/_build/html/_sources/examples.txt

@@ -3 +3 @@
 
 .. contents::
+
+TBW

docs/src/_build/html/_sources/install.txt

@@ -2 +2 @@
 =========================
 
+Installing Mailjam is quite easy. If you have some experience installing 
+Python_ packages [1]_, you already know how to do it. Mailjam is a standard
+Python_ package available on pypi_ [3]_ so just use your favourite tool
+(pip_, easy_install_, etc) to intall it.
+
+Keep reading if you want to learn more about the different options/choices
+you have when installing Mailjam.
+
 .. contents::
 
@@ -14 +22 @@
 *2.6.x* too.
 
-Please, refer to your operating system package system documentation to learn
-more about how to install python.
+Please, refer to your operating system documentation to learn more about how 
+to install python.
 
 .. _install_mailjam:
@@ -22 +30 @@
 -----------------------
 
+You can install Mailjam using one of the available tools for installing Python_
+packages, or you can install it from sources. Keep reading to learn more about
+it.
+
 .. _install_with_pip:
 
@@ -29 +41 @@
 You can install Mailjam using pip_::
 
-  pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
-
-.. note::
-
-   Mailjam has not been recorded/uploaded to pypi_ yet, so, in order to install 
-   it using pip you will have to provide the URL for the public Mailjam repo.
+  pip install Mailjam
+
+.. note::
+
+   The previous command will install the latest release from pypi_. If you
+   would like to install the latest *bleeding edge* sources (unstable code),
+   you can do it using pip_ too::
+
+     pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
 
 .. _install_with_easy_install:
@@ -41 +56 @@
 +++++++++++++++++++++++++++++
 
-You can not install Mailjam using easy_install_ yet (until we do record/upload 
-it to pypi)
+You can install Mailjam using easy_install_::
+
+  easy_install Mailjam
 
 .. _install_inside_virtualenv:
@@ -66 +82 @@
 And, once the environment has been activated, use pip to install Mailjam::
 
-  env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
+  env$ pip install Mailjam
+
+.. note::
+
+   Remember that you can install the latest *bleeding edge* version using 
+   pip_ too::
+   
+     env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
 
 .. _install_from_sources:
@@ -82 +105 @@
 ********
 
-**There are no releases yet**. You will have to install it from the repository.
-
-.. _install_from_repository:
-
-From repository
-***************
-
-The source code of Mailjam is hosted in bitbucket_ [1]_. In order to grab
-the latest sources you need Mercurial_.
-
-To get a copy of the sources, just *clone* the repository::
-
-  hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo
-
-Then, go inside the *mailjam-repo* directory and run::
+You can grab a copy of the latest release from pypi_:
+
+http://pypi.python.org/packages/source/m/mailjam/
+
+After downloaded, you have to unpack the sources::
+
+  tar -zxvvf mailjam-0.1.0.tar.gz
+
+This will create a directory called *mailjam-0.1.0*, go inside that directory
+and run::
 
   python setup.py install
@@ -110 +128 @@
    This process will work inside a virtualenv_ too.
 
+.. _install_from_repository:
+
+From repository
+***************
+
+The source code of Mailjam is hosted in bitbucket_ [2]_. In order to grab
+the latest sources you need Mercurial_.
+
+To get a copy of the sources, just *clone* the repository::
+
+  hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo
+
+Then, go inside the *mailjam-repo* directory and run::
+
+  python setup.py install
+
+.. warning::
+
+   If you want to install it *system-wide*, probably you will need *root*
+   privileges (check your OS documentation to learn more about how to get
+   *root* privileges - for example using sudo_)
+
+.. note::
+
+   This process will work inside a virtualenv_ too.
+
 .. _install_setting_up_mailjam:
 
@@ -115 +159 @@
 ------------------
 
-TBW
+In order to setup Mailjam, you will have to create the needed 
+:doc:`configuration files <configuration>`. Each component has its own
+configuration file:
+
+- The :ref:`Mailjam daemon <overview_mailjam_daemon>` configuration file is 
+  :ref:`mailjam.conf <configuration_daemon>`
+
+- The :ref:`Mailjam MTA client <overview_mailjam_mta_client>` configuration 
+  file is :ref:`mailjam-mta.conf <configuration_mta_client>`
+
+- The :ref:`Mailjam CLI client <overview_mailjam_cli_client>` configuration 
+  file is :ref:`mailjam-cli.conf <configuration_cli_client>`
+
+Refer to each configuration file documentation to learn more about the different
+settings you can customize.
+
+Each component will search for its configuration file in a list of predefined
+locations, but you can override that behaviour using the *-c* parameter when
+starting the component. 
+
+.. note::
+
+   Mailjam will search for the config files, in order, through the following 
+   paths:
+
+   1. /etc/mailjam
+
+   2. /etc
+
+   3. /usr/local/etc/mailjam
+
+   4. /usr/local/etc
+
+   5. the *conf* directory within the sources (or the installed *egg* [4]_)
+
+For example, you can start the :ref:`overview_mailjam_daemon` passing 
+*/var/db/mailjam/mailjam.conf* as its configuration file::
+
+  mailjam-server -c /var/db/mailjam/mailjam.conf
+
+.. seealso::
+
+   :doc:`running` contains more information about how to run the different 
+   components.
+
+If you have installed Mailjam using pip_, easy_install_ or even from sources,
+the setup process should have taken care of the configuration files, adding
+a copy of the default files included in the sources to the default 
+destination.
+
+.. warning::
+
+   The default destination will be different based on your operating system.
+   For example, in most linux servers it will copy the files to */etc/mailjam*,
+   while in BSD servers it will copy the files to */usr/local/etc/mailjam*.
+
+.. seealso::
+
+   :doc:`Configuration files, settings and formats documentation <configuration>`
+
 
 .. _install_running_mailjam:
@@ -122 +225 @@
 ---------------
 
-TBW
+In order to run a full Mailjam environment, you will have to start the different
+components separately:
+
+1. :ref:`Start the daemon <running_daemon>`
+
+2. :ref:`Run the cli client and manage your mailing lists <running_cli_client>`
+
+3. :ref:`Add as much MTA clients as you need to your mail server<running_mta_client>`
+
+The daemon will have to be running all the time (it is the component responsible
+for providing information to the clients). You will need the CLI client to add, 
+edit or delete mailing lists and each MTA client will be responsible to handle 
+incoming emails for each mailing list.
 
 .. _install_running_tests:
@@ -129 +244 @@
 -------------------------------
 
-TBW
+Just in case you were wondering, **yes**, Mailjam code has some tests you can 
+run to check everything is ok and that the software should run smoothly on your
+server(s).
+
+To run the tests, simply get a copy of the sources from our public repository::
+
+  hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo
+
+then run the tests::
+
+  cd mailjam-repo && ./bin/run_tests
+
 
 .. _Python: http://python.org
@@ -140 +266 @@
 .. _sudo: http://sudo.ws
 
-.. [1] https://bitbucket.org/codigo23/mailjam
+.. [1] http://docs.python.org/tutorial/modules.html#packages
+.. [2] https://bitbucket.org/codigo23/mailjam
+.. [3] http://pypi.python.org/pypi/mailjam
+.. [4] http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt

docs/src/_build/html/_sources/overview.txt

@@ -18 +18 @@
    :class: open_fancybox
 
+This architecture works for small setups (everything running on a single server)
+but it works for bigger/larger installations with up to N mail servers, running
+each server its own :ref:`overview_mailjam_mta_client` (or multiple instances
+of it) to connect to N :ref:`overview_mailjam_daemon` servers (managed locally 
+or remotely using up to N :ref:`overview_mailjam_cli_client` or
+:ref:`overview_mailjam_web_client` instances).
+
+.. seealso::
+
+   :doc:`The examples documentation <examples>` contains some useful examples
+   about different kinds of setups.
 
 .. _overview_mailjam_daemon:

docs/src/_build/html/_sources/running.txt

@@ -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