Changeset 27:b1d527287347 in mailjam for docs/src/configuration.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/configuration.rst

    r16 r27  
    22=============
    33
     4Mailjam has separate configuration files for the different apps (the daemon and
     5the variety of different clients available). Check below to read more about the
     6configuration file you need to modify depending on what you want to do.
     7
    48.. contents::
    59
    610.. _configuration_daemon:
    711
    8 Mailjam daemon configuration file
    9 ---------------------------------
    10 
    11 All the configurations that can be applied to the Mailjam daemon are registered
    12 in the **mailjam.conf** file. That file contains ini-style [1]_ configuration
    13 parameters, separated in different *categories*.
     12Mailjam daemon configuration file - mailjam.conf
     13------------------------------------------------
     14
     15All the configurations that can be applied to the :ref:`overview_mailjam_daemon`
     16are registered in the **mailjam.conf** file. That file contains ini-style [1]_
     17configuration parameters, separated in different *categories*.
    1418
    1519.. note::
     
    1822   your setup. The usual locations are:
    1923
    20    - */etc/mailjam.conf* - In most Linux systems (like archlinux, gentoo,
    21      fedora, debian, ubuntu, etc)
    22 
    23    - */usr/local/etc/mailjam.conf* - In most BSD systems (like FreeBSD, OpenBSD,
    24      NetBSD, etc)
     24   - */etc/mailjam/mailjam.conf* - In most Linux systems (like archlinux,
     25     gentoo, fedora, debian, ubuntu, etc)
     26
     27   - */usr/local/etc/mailjam/mailjam.conf* - In most BSD systems (like FreeBSD,
     28     OpenBSD, NetBSD, etc)
    2529
    2630   There is a copy of the configuration file in the *conf/* directory, within
     
    6266***
    6367
    64 Default: ``off`` (because ssl support hasn't been added yet)
    65 
    66 Enables/disables SSL [3]_ support in the daemon. If ``off`` all the traffic
    67 to/from the server will travel unencrypted. If ``on`` all the traffic will
     68Default: ``false`` (because ssl support hasn't been added yet)
     69
     70Enables/disables SSL [3]_ support in the daemon. If ``false`` all the traffic
     71to/from the server will travel unencrypted. If ``true`` all the traffic will
    6872travel encrypted.
    6973
     
    295299will be able to reset those passwords.
    296300
     301.. _configuration_mta_client:
     302
     303Mailjam MTA client configuration file - mailjam-mta.conf
     304--------------------------------------------------------
     305
     306This file contains all the parameters to configure the
     307:ref:`overview_mailjam_mta_client` properly. It contains ini-style [1]_
     308configuration parameters, separated in different *categories*.
     309
     310.. note::
     311
     312   The mailjam-mta.conf file will be installed in different locations
     313   depending on your setup. The usual locations are:
     314
     315   - */etc/mailjam/mailjam-mta.conf* - In most Linux systems (like archlinux,
     316     gentoo, fedora, debian, ubuntu, etc)
     317
     318   - */usr/local/etc/mailjam/mailjam-mta.conf* - In most BSD systems (like
     319     FreeBSD, OpenBSD, NetBSD, etc)
     320
     321   There is a copy of the configuration file in the *conf/* directory, within
     322   the sources.
     323
     324.. _configuration_mta_client_server:
     325
     326server
     327++++++
     328
     329This section contains the configuration parameters that tell the MTA client
     330where to connect when trying to interact with the
     331:ref:`overview_mailjam_daemon`.
     332
     333These are all the available parameters in this section:
     334
     335.. _configuration_mta_client_server_address:
     336
     337address
     338*******
     339
     340Default: ``localhost``
     341
     342The address where the daemon is listening for XMLRPC requests. This is
     343the address to where the client will try to connect to.
     344
     345.. _configuration_mta_client_server_port:
     346
     347port
     348****
     349
     350Default: ``9876``
     351
     352The port where the daemon accepts incoming XMLRPC requests. This is the
     353port to where the client will try to connect to.
     354
     355.. _configuration_mta_client_server_uri:
     356
     357uri
     358***
     359
     360Default: http://localhost:9876
     361
     362This is the URI [4]_ to where the client will connect to. It is constructed
     363based on the values of the :ref:`configuration_mta_client_server_address`
     364and :ref:`configuration_mta_client_server_port` parameters.
     365
     366.. note::
     367
     368   The default configuration file contains a dynamic setting for this
     369   parameter::
     370
     371     uri = http://%(address)s:%(port)s
     372
     373   That means that the parameter will inherit the values from the
     374   :ref:`configuration_mta_client_server_address`
     375   and :ref:`configuration_mta_client_server_port` parameters.
     376
     377.. seealso::
     378
     379   More information about this (and other tricks) here:
     380
     381   http://docs.python.org/library/configparser.html
     382
     383   http://www.doughellmann.com/PyMOTW/ConfigParser
     384
     385.. warning::
     386
     387   You can replace this with any URI you would like, **this is the parameter
     388   that is really used for establishing new connections** so be aware that if
     389   you remove the references to the
     390   :ref:`configuration_mta_client_server_address` and
     391   :ref:`configuration_mta_client_server_port` parameters, the values you have
     392   provided for those parameters will be ignored.
     393
     394.. _configuration_mta_client_server_ssl:
     395
     396ssl
     397***
     398
     399Default: ``false`` (because ssl support hasn't been added yet)
     400
     401Enables/disables SSL [3]_ connections to the daemon. If ``false`` all the
     402traffic to/from the server will travel unencrypted. If ``true`` all the traffic
     403will travel encrypted.
     404
     405.. warning::
     406
     407   In order to enable SSL support in the client, you have to be sure the
     408   :ref:`overview_mailjam_daemon` supports SSL too (check the
     409   :ref:`configuration_daemon_xmlrpc_ssl` parameter in the
     410   :ref:`configuration_daemon_xmlrpc` section of the
     411   :ref:`daemon configuration file <configuration_daemon>`)
     412
     413.. _configuration_mta_client_archive:
     414
     415archive
     416+++++++
     417
     418This section contains the configuration parameters that set where the files
     419generated by the client will be stored/saved.
     420
     421.. seealso::
     422
     423   For more information about the kind of files the client does generate,
     424   take a look at the
     425   :ref:`MTA client documentation <overview_mailjam_mta_client>`.
     426
     427These are all the available parameters in this section:
     428
     429.. _configurtion_mta_client_archive_persistent:
     430
     431persistent
     432**********
     433
     434Default: ``true``
     435
     436Enables/disables the local archive for the client. If ``true``, the client
     437will save a copy of every email sent to the list in an internal archive,
     438that could be checked/queried later. If ``false``, the emails will not be
     439kept on disk after being processed.
     440 
     441.. warning::
     442
     443   This feature is not ready yet.
     444
     445
     446.. _configuration_mta_client_archive_path:
     447
     448path
     449****
     450
     451Default: ``/usr/local/mailjam/archive-mta``
     452
     453Path to the directory where the archives will be saved.
     454
     455.. warning::
     456
     457   This feature is not ready yet.
     458
     459
     460.. _configuration_cli_client:
     461
     462Mailjam CLI client configuration file - mailjam-cli.conf
     463--------------------------------------------------------
     464
     465This file contains all the parameters to configure the
     466:ref:`overview_mailjam_cli_client` properly. It contains ini-style [1]_
     467configuration parameters, separated in different *categories*.
     468
     469.. note::
     470
     471   The mailjam-cli.conf file will be installed in different locations
     472   depending on your setup. The usual locations are:
     473
     474   - */etc/mailjam/mailjam-cli.conf* - In most Linux systems (like archlinux,
     475     gentoo, fedora, debian, ubuntu, etc)
     476
     477   - */usr/local/etc/mailjam/mailjam-cli.conf* - In most BSD systems (like
     478     FreeBSD, OpenBSD, NetBSD, etc)
     479
     480   There is a copy of the configuration file in the *conf/* directory, within
     481   the sources.
     482
     483.. _configuration_cli_client_server:
     484
     485server
     486++++++
     487
     488This section contains the configuration parameters that tell the cli client
     489where to connect when trying to interact with the
     490:ref:`overview_mailjam_daemon`.
     491
     492These are all the available parameters in this section:
     493
     494.. _configuration_cli_client_server_address:
     495
     496address
     497*******
     498
     499Default: ``localhost``
     500
     501The address where the daemon is listening for XMLRPC requests. This is
     502the address to where the client will try to connect to.
     503
     504.. _configuration_cli_client_server_port:
     505
     506port
     507****
     508
     509Default: ``9876``
     510
     511The port where the daemon accepts incoming XMLRPC requests. This is the
     512port to where the client will try to connect to.
     513
     514.. _configuration_cli_client_server_uri:
     515
     516uri
     517***
     518
     519Default: http://localhost:9876
     520
     521This is the URI [4]_ to where the client will connect to. It is constructed
     522based on the values of the :ref:`configuration_cli_client_server_address`
     523and :ref:`configuration_cli_client_server_port` parameters.
     524
     525.. note::
     526
     527   The default configuration file contains a dynamic setting for this
     528   parameter::
     529
     530     uri = http://%(address)s:%(port)s
     531
     532   That means that the parameter will inherit the values from the
     533   :ref:`configuration_cli_client_server_address`
     534   and :ref:`configuration_cli_client_server_port` parameters.
     535
     536.. seealso::
     537
     538   More information about this (and other tricks) here:
     539
     540   http://docs.python.org/library/configparser.html
     541
     542   http://www.doughellmann.com/PyMOTW/ConfigParser
     543
     544.. warning::
     545
     546   You can replace this with any URI you would like, **this is the parameter
     547   that is really used for establishing new connections** so be aware that if
     548   you remove the references to the
     549   :ref:`configuration_cli_client_server_address` and
     550   :ref:`configuration_cli_client_server_port` parameters, the values you have
     551   provided for those parameters will be ignored.
     552
     553.. _configuration_cli_client_server_ssl:
     554
     555ssl
     556***
     557
     558Default: ``false`` (because ssl support hasn't been added yet)
     559
     560Enables/disables SSL [3]_ connections to the daemon. If ``false`` all the
     561traffic to/from the server will travel unencrypted. If ``true`` all the traffic
     562will travel encrypted.
     563
     564.. warning::
     565
     566   In order to enable SSL support in the client, you have to be sure the
     567   :ref:`overview_mailjam_daemon` supports SSL too (check the
     568   :ref:`configuration_daemon_xmlrpc_ssl` parameter in the
     569   :ref:`configuration_daemon_xmlrpc` section of the
     570   :ref:`daemon configuration file <configuration_daemon>`)
     571
     572.. _configuration_cli_client_history:
     573
     574history
     575+++++++
     576
     577This section contains the configuration parameters that set the behaviour
     578of the client feature that allows it to save a history of commands provided
     579by the user.
     580
     581These are all the available parameters in this section:
     582
     583.. _configurtion_cli_client_archive_enabled:
     584
     585enabled
     586*******
     587
     588Default: ``true``
     589
     590Enables/disables history support in the client. If ``true`` all commands
     591provided by an user will be saved to disk. If ``false`` nothing will be
     592written to disk.
     593
     594.. _configuration_cli_client_history_path:
     595
     596path
     597****
     598
     599Default: ``~/.mailjam/cli/history``
     600
     601Path to the file where the list of executed commands will be saved.
     602
    297603
    298604.. [1] http://en.wikipedia.org/wiki/INI_file
    299605.. [2] http://en.wikipedia.org/wiki/XML-RPC
    300606.. [3] http://en.wikipedia.org/wiki/Secure_Socket_Layer
     607.. [4] http://en.wikipedia.org/wiki/Uniform_resource_identifier
Note: See TracChangeset for help on using the changeset viewer.