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


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/src/running.rst

    r16 r27  
    22===============
    33
     4In order to run Mailjam, you have to run the different components, depending on
     5what you want to do. Basically, you will need to run a server
     6(:ref:`overview_mailjam_daemon`) all the time, then you will need one
     7:ref:`overview_mailjam_mta_client` per mailing list.
     8
     9Ocasionally, you will need to add or delete a mailing list, or edit its
     10information, members list, etc. To do that, you will have to run a Mailjam
     11client (either the :ref:`CLI client <overview_mailjam_cli_client>` or the
     12:ref:`Web client <overview_mailjam_web_client>`).
     13
     14Keep reading if you want to learn more about the way you can start each
     15component, the different arguments/parameters you can provide on startup, etc.
     16
     17.. warning::
     18
     19   Remember that, before being able to run any component, you have to
     20   :ref:`set up proper configuration files <install_setting_up_mailjam>`. You
     21   can learn more about Mailjam configuration files in the
     22   :doc:`configuration files documentation <configuration>`.
     23
    424.. contents::
     25
     26.. _running_daemon:
     27
     28The daemon
     29----------
     30
     31First component you should start is the :ref:`overview_mailjam_daemon`. It is
     32quite easy, just run this command from a shell/console::
     33
     34  mailjam-server
     35
     36The server process will read the :ref:`mailjam.conf <configuration_daemon>`
     37configuration file, will prepare everything and will start listening for XMLRPC
     38requests on *localhost:9876*
     39
     40.. warning::
     41
     42   *localhost:9876* is the default value provided by the default configuration
     43   files. If you have modified that, it will be a different *address:port*
     44   combination.
     45
     46.. warning::
     47
     48   If you didn't add a valid configuration file to one of the
     49   :ref:`default paths <install_setting_up_mailjam>`, the server will refuse to
     50   start, giving you an error message.
     51
     52.. warning::
     53
     54   As of the current version of Mailjam, there are no pre-made init scripts that
     55   can handle the start/stop/restart of the daemon, but those will be added in
     56   one of the future releases.
     57
     58.. _running_daemon_parameters:
     59
     60Additional parameters
     61+++++++++++++++++++++
     62
     63You can pass some parameters to *mailjam-server* to modify the behaviour of
     64the daemon or get more information.
     65
     66.. note::
     67
     68   Remember that the proper way to modify the behaviour of the daemon is
     69   editing its configuration file, :ref:`mailjam.conf <configuration_daemon>`
     70
     71.. _running_daemon_help:
     72
     73--help
     74******
     75
     76You can get some help by passing the *-h* or *--help* parameters::
     77
     78  mailjam-server -h
     79
     80::
     81
     82  mailjam-server --help
     83
     84.. _running_daemon_config:
     85
     86--config
     87********
     88
     89You can set the path to the config file the server will load on startup,
     90passing the *-c* or *--config* parameters::
     91
     92  mailjam-server -c /home/mailjam/mailjam.conf
     93
     94::
     95
     96  mailjam-server --config /home/mailjam/mailjam.conf
     97 
     98.. warning::
     99
     100   If the file does not exist, or if it is not a valid configuration file,
     101   an error will be shown and the daemon will refuse to start.
     102
     103.. _running_daemon_version:
     104
     105--version
     106*********
     107
     108You can check the version of the mailjam server you are trying to run by
     109passing the *-v* or *--version* parameters::
     110
     111  mailjam-server -v
     112
     113::
     114
     115  mailjam-server --version
     116
     117
     118.. _running_cli_client:
     119
     120The CLI client
     121--------------
     122
     123
     124
     125.. _running_mta_client:
     126
     127The MTA client
     128--------------
     129
     130Once you have your :ref:`daemon running <running_daemon>`, you have to add
     131as many :ref:`MTA clients <overview_mailjam_mta_client>` as mailing lists you
     132want to manage to your mail server.
     133
     134.. _running_mta_client_quick:
     135
     136Quick configuration (you are a mail-servers-master)
     137+++++++++++++++++++++++++++++++++++++++++++++++++++
     138
     139Edit your mail server aliases file [1]_ (probably */etc/aliases* or
     140*/etc/mail/aliases*) and add an entry like::
     141
     142  list@mydomain.com: "|/usr/local/bin/mailjam-mta -a list@mydomain.com -i -"
     143
     144.. warning::
     145   
     146   replace *list@mydomain.com* with the real address of your mailing list
     147
     148.. warning::
     149
     150   replace */usr/local/bin/mailjam-mta* with the real path to your mailjam-mta
     151   installation
     152
     153Rebuild your *aliases* database::
     154
     155  newaliases
     156
     157.. warning::
     158
     159   Refer to your OS documentation to see how you can rebuild *aliases*. In most
     160   unix-like systems it is done by the newaliases [2]_ command.
     161
     162.. _running_mta_client_explained:
     163
     164Explained configuration (you really want to know what's happening here)
     165+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
     166
     167When new messages arrive at your mail server for your mailing list address
     168(let's use the example address *list@mydomain.com*) one of the steps in the
     169process that checks the message, it's origin, destination, contents, etc is
     170the step where the mail server checks its internal *aliases* database, that is,
     171a list of *special* addresses that, instead of being *real* addresses, they are
     172related to some other addresses in some way.
     173
     174Most MTAs out there support one very *convenient* feature that is to *pipe* the
     175contents of the message (headers and body) to a given shell command. That means
     176that the all the received data will be sent to an external command for it to
     177process such data.
     178
     179**Here is where mailjam-mta comes in**.
     180
     181What you have to do is just tell your mail server that all messages with
     182destination *list@mydomain.com* (to keep using the same example address) will be
     183*piped* to mailman-mta. The Mailjam MTA client will then know what to do with
     184the message, performing some checks and re-sending it to the proper destinations
     185(the members/suscriptors of the given mailing list).
     186
     187So, first thing you have to find out is **where is your aliases file?**.
     188
     189In unix-like systems, like the different Linux distributions or the different
     190BSD flavours, that file is */etc/mail/aliases* or */etc/aliases* (usually one is
     191a simbolic link to the other).
     192
     193.. note::
     194
     195   Usually the aliases file contains some lines like::
     196
     197     MAILER-DAEMON: postmaster
     198     postmaster: root
     199
     200Once you've found out where the file is, edit it and add this line to the bottom
     201of the file::
     202
     203  list@mydomain.com: "|/usr/local/bin/mailjam-mta -a list@mydomain.com -i -"
     204
     205.. warning::
     206   
     207   replace *list@mydomain.com* with the real address of your mailing list
     208
     209.. warning::
     210
     211   replace */usr/local/bin/mailjam-mta* with the real path to your mailjam-mta
     212   installation
     213
     214There you are telling your mail server that any message coming **to**
     215*list@mydomain.com* will be passed to the mailjam-mta command, passing some
     216parameters to it:
     217
     218- **-a list@mydomain.com** tells mailjam-mta that the message is actually for
     219  that mailing list. The MTA client will then use that value to check (against
     220  the mailjam daemon) if it is a valid mailing list.
     221
     222- **-i -** tells mailjam-mta that the message will be *piped* directly. This is
     223  important, as mailjam-mta can read the messages from files, but in this case
     224  the mail server will *pipe* the data directly to mailjam-mta.
     225
     226Once you've added that line to your *aliases* file, you have to rebuild your
     227*aliases* database::
     228
     229  newaliases
     230
     231.. warning::
     232
     233   Refer to your OS documentation to see how you can rebuild *aliases*. In most
     234   unix-like systems it is done by the newaliases [2]_ command.
     235
     236And you are done. Everything is ready now.
     237
     238.. _running_mta_client_parameters:
     239
     240Additional parameters
     241+++++++++++++++++++++
     242
     243You can pass some parameters to *mailjam-mta* to modify the behaviour of
     244the client or get more information.
     245
     246.. note::
     247
     248   Remember that the proper way to modify the behaviour of the client is
     249   editing its configuration file,
     250   :ref:`mailjam-mta.conf <configuration_mta_client>`
     251
     252.. _running_mta_client_help:
     253
     254--help
     255******
     256
     257You can get some help by passing the *-h* or *--help* parameters::
     258
     259  mailjam-mta -h
     260
     261::
     262
     263  mailjam-mta --help
     264
     265.. _running_mta_client_config:
     266
     267--config
     268********
     269
     270You can set the path to the config file the client will load on startup,
     271passing the *-c* or *--config* parameters::
     272
     273  mailjam-mta -c /home/mailjam/mailjam-mta.conf
     274
     275::
     276
     277  mailjam-mta --config /home/mailjam/mailjam-mta.conf
     278 
     279.. warning::
     280
     281   If the file does not exist, or if it is not a valid configuration file,
     282   an error will be shown and the client will refuse to start.
     283
     284.. _running_mta_client_version:
     285
     286--version
     287*********
     288
     289You can check the version of the mailjam client you are trying to run by
     290passing the *-v* or *--version* parameters::
     291
     292  mailjam-mta -v
     293
     294::
     295
     296  mailjam-mta --version
     297
     298.. _running_mta_client_address:
     299
     300--address (required)
     301********************
     302
     303This parameter is required (you have to provide it with a value in order to
     304run the mailjam-mta). It sets the address of the mailing list managed by this
     305MTA client instance.
     306
     307The MTA client will use the provided value to do some checks on the daemon,
     308retrieving all the needed data to perform its tasks.
     309
     310You can pass a valid address using both the *-a* and *--address* parameters::
     311
     312  mailjam-mta -a list@mydomain.com
     313
     314::
     315
     316  mailjam-mta --address list@mydomain.com
     317
     318.. _running_mta_client_input:
     319
     320--input
     321*******
     322
     323This parameter tells mailjam-mta from where it has to read the message sent
     324to the mailing list. That could be a local file (to be readed from disk) or
     325a stream of data coming directly from the standard input (*stdin*).
     326
     327For a regular configuration/setup, the second option is preferred, as the mail
     328server will send the stream of data directly to mailjam-mta (as
     329:ref:`explained before <running_mta_client_explained>`)::
     330
     331  mailjam-mta -i -
     332
     333::
     334
     335  mailjam-mta --input -
     336
     337But perhaps some time you would like to send (again) a message you have on disk,
     338that could be done easily, passing the path to the file containing that message
     339to mailjam-mta::
     340
     341  mailjam-mta -i /home/backups/mail/that-important-mail.txt
     342
     343::
     344
     345  mailjam-mta -input /home/backups/mail/that-important-mail.txt
     346
     347
     348.. _running_web_client:
     349
     350The Web client
     351--------------
     352
     353.. [1] http://en.wikipedia.org/wiki/Email_alias
     354.. [2] http://www.freebsd.org/cgi/man.cgi?query=newaliases
Note: See TracChangeset for help on using the changeset viewer.