# -*- rd -*-

= README --- milter-manager: a milter to use milters effectively.

== Name

milter manager

== Site

((<URL:http://milter-manager.sourceforge.net/>))

== License

Use the following rules:

  * Files that describe their license: their license
  * Commands: GPL3(license/gpl.txt)
  * Documents: GFDL(license/fdl.txt)
  * Web interface: AGPL3(license/agpl.txt)
  * Libraries: LGPL3(license/lgpl.txt)

Here is a concrete list:

  * Files that describe their license:
    * binding/ruby/lib/milter/compatible.rb: Ruby's
    * admin/vendor/plugins/restful-auth/: MIT
  * Commands: GPL3
    * src/*
    * tool/*
  * Documents: GFDL
    * README, README.ja
    * doc/*
  * Web interface: AGPL3
    * admin/**/*
  * Libraries: LGPL3
    * others than those above

== milter manager

milter manager is a milter to use multiple milters
effectively.

If milter manager is introduced, milter manager
administrates milters instead of MTA. The was has some
advantages:

  * reduce milter administration cost
  * combine milters flexibly

See ((<Introduction|"doc/introduction.rd">)) for more details.

== Dependencies

  * MTA that supports milter
    * Sendmail >= 8.13.8
    * Postfix >= 2.3.3
  * GLib >= 2.12.3
  * Ruby >= 1.8.5
  * Ruby/GLib2 (Ruby-GNOME2) >= 0.16.0
  * UN*X OS
    * Linux >= 2.6.18
    * FreeBSD

=== Optional dependencies

  * Cutter >= 1.0.6: unit testing framework for C

    It is needed for 'make check' and 'make coverage'.

    ((<Cutter|URL:http://cutter.sourceforge.net/>))

  * LCOV: graphical front-end for GCC's coverage testing tool gcov

    It is needed for 'make coverage'.

    ((<LCOV - the LTP GCOV extension|URL:http://ltp.sourceforge.net/coverage/lcov.php>))

  * RRDtool (It's better that bundled Ruby bindings are also installed)

    It is needed for milter-manager-log-analyzer.

    ((<RRDtool|URL:http://oss.oetiker.ch/rrdtool/>))

== Get

tar.gz:
((<URL:http://sourceforge.net/project/showfiles.php?group_id=236233>))

Subversion:
  % svn co https://milter-manager.svn.sourceforge.net/svnroot/milter-manager/milter-manager/trunk milter-manager

== Install

See ((<Install|"doc/install.rd">)).

== Configuration

See ((<Configuration|"doc/configuration.rd">)).

== Usage

milter-manager command is installed into sbin/ not
bin/. In most cases, normal user doesn't include sbin/ in
PATH. You will need to use absolute path.

If you don't specify --prefix option for configure script,
milter-manager is installed into /usr/local/sbin/. You can
run milter-manager like the following:

  % /usr/local/sbin/milter-manager --help

Available options are shown if installation is succeeded.
Details of them are described in the next section. It's good
startup that we use --show-config option to confirm the
current configuration:

  % /usr/local/sbin/milter-manager --show-config

Command line options overrides configurations specified in
configuration file.

=== Options

: --help

   Shows available options and exits.

: --connection-spec=SPEC

   Specifies a socket that accepts connections from
   MTA. SPEC should be formatted as one of the followings:

     * unix:PATH
     * inet:PORT
     * inet:PORT@HOST
     * inet:PORT@[ADDRESS]
     * inet6:POST
     * inet6:PORT@HOST
     * inet6:PORT@[ADDRESS]

   Examples:
     * unix:/var/run/milter/milter-manager.sock
     * inet:10025
     * inet:10025@localhost
     * inet:10025@[127.0.0.1]
     * inet6:10025
     * inet6:10025@localhost
     * inet6:10025@[::1]

   This option overrides "manager.connection_spec" in
   configuration file.

: --config-dir=DIRECTORY

    Specifies a directory that includes milter-manager's
    configuration file. milter-manager tries to load
    DIRECTORY/milter-manager.conf. If it isn't find,
    milter-manager loads milter-manager.conf in default
    directory.

: --pid-file=FILE

   Saves process ID of milter-manager to FILE.

   This option overrides "manager.pid_file" in configuration
   file.

: --user-name=NAME

   Runs milter-manager as NAME user.
   milter-manager should be started by root.

   This option overrides "security.effective_user" in
   configuration file.

: --group-name=NAME

   Runs milter-manager as NAME group.
   milter-manager should be started by root.

   This option overrides "security.effective_group" in
   configuration file.

: --socket-group-name=NAME

   Changes group of UNIX domain socket for accepting
   connection by milter-manager to NAME group. Specified
   group should be one of the effective user's supplementary
   groups.

   This option overrides "manager.unix_socket_group" in
   configuration file.

: --daemon

   Runs milter-manager as daemon process.

   This option overrides "manager.daemon" in configuration
   file.

: --no-daemon

   This option cancels the prior --daemon option.

: --show-config

   Shows the current configuration and exits. The output
   format can be used in configuration file. This option is
   useful for confirming registered milters and reporting your
   milter-manager's configuration when you report
   milter-manager's problems.

: --verbose

   Logs verbosely. Logs by syslog with 'mail'. If
   milter-manager isn't daemon process, standard output is
   also used.

   'MILTER_LOG_LEVEL=all' environment variable configuration
   has the same effect.

: --version

   Shows version and exits.

== Tools

milter manager includes some useful tools. They are
installed into bin/.

  * milter-test-server: It talks MTA side milter protocol.
    It can be used for testing a milter without MTA.
  * milter-test-client: It is a milter that just shows
    received data from MTA. It can be used for confirming
    what data is sent from MTA.
  * milter-performance-check: It is a SMTP client that
    measures MTA performance.
  * milter-manager-log-analyzer: It analyzes log of
    milter-manager and visualizes behavior of milters
    registered to milter-manager.

=== milter-test-server

milter-test-server talks MTA side milter protocol. It can
connect to a milter without MTA. For now, there is no
similar tool. It is useful to test milter not MTA +
milter. For example, it can be used for the following
situation:

  * milter's performance check
  * milter's operation check

milter-test-server can be used for simple performance check
because it shows elapsed time. You can confirm elapsed time
without MTA's processing time. You will find a problem of a
milter more easily because it doesn't depend on MTA.

If a milter changes headers and/or body, milter-test-server
can show changed message. It can be used for testing a
milter that may change headers and/or body. If it is used
with unit testing frame like Cutter, you can write automated
unit tests.

==== Options

: --help

   Shows available options and exits.

: --connection-spec=SPEC

   Specifies a socket to connect to milter. SPEC should be
   formatted as one of the followings:

     * unix:PATH
     * inet:PORT
     * inet:PORT@HOST
     * inet:PORT@[ADDRESS]
     * inet6:POST
     * inet6:PORT@HOST
     * inet6:PORT@[ADDRESS]

   Examples:
     * unix:/var/run/milter/milter-manager.sock
     * inet:10025
     * inet:10025@localhost
     * inet:10025@[127.0.0.1]
     * inet6:10025
     * inet6:10025@localhost
     * inet6:10025@[::1]

: --negotiate-version=VERSION

    Use VERSION as milter protocol version sent to milter.

    Default value is 8. The value is the same as Sendmail
    8.14's default value.

: --connect-host=HOST

    Uses HOST as connected host.

    The host name is passed to milter's xxfi_connect() callback.

: --connect-address=SPEC

    Uses SPEC as connected address. SPEC format is same as
    --connection-spec option's SPEC.

    The address is passed to milter's xxfi_connect() callback.

: --helo-fqdn=FQDN

    Uses FQDN for 'HELO/EHLO' SMTP command.

    The FQDN is passed to milter's xxfi_helo() callback.

: --from=FROM

    Uses FROM for 'MAIL FROM' SMTP command.

    The address is passed to milter's xxfi_envfrom() callback.

: --recipient=RECIPIENT

    Uses RECIPIENT for 'RCPT TO' SMTP command. If you want
    to use multiple recipients, specify --recipient option
    n-times.

    The address is passed to milter's xxfi_envrcpt()
    callback. xxfi_envrcpt() is called for each recipient.

: --header=NAME:VALUE

    Adds a header that names NAME and its value is VALUE. If
    you want to multiple headers, specify --header option
    n-times.

    The header is passed to milter's xxfi_header() callback.
    xxfi_header() is called for each header.

: --body=CHUNK

    Adds CHUNK as body chunk. If you want to multiple
    chunks, specify --body option n-times.

    The chunk is passed to milter's xxfi_body()
    callback. xxfi_body() is called for each chunk.

: --unknown=COMMAND

    Uses COMMAND as unknown SMTP command.

    The command is passed to milter's xxfi_unknown()
    callback. xxfi_unknown() is called between
    xxfi_envrcpt() and xxfi_data().

: --mail-file=PATH

    Uses file exists at PATH as mail content. If the file
    has 'From:' and/or 'To:', they are used for from and/or
    recipient addresses.

: --output-message

    Shows a message applied a milter. If you want to
    check milter's operation that may change header and/or
    body, specify this option.

: --verbose

   Logs verbosely.

   'MILTER_LOG_LEVEL=all' environment variable configuration
   has the same effect.

: --version

   Shows version and exits.

=== milter-test-client

milter-test-client is a milter that just shows received data
from MTA. It also shows macros received from MTA, it can be
used for confirming MTA's milter configuration.

Postfix's source archive includes similar tool.
It's src/milter/test-milter.c. It seems that it's used for
testing Postfix's milter implementation. But test-milter
doesn't show macros. If you have a milter that doesn't work
as you expect and uses macro, milter-test-client is useful
tool for looking into the problems.

==== Options

: --help

   Shows available options and exits.

: --connection-spec=SPEC

   Specifies a socket that accepts connections from
   MTA. SPEC should be formatted as one of the followings:

     * unix:PATH
     * inet:PORT
     * inet:PORT@HOST
     * inet:PORT@[ADDRESS]
     * inet6:POST
     * inet6:PORT@HOST
     * inet6:PORT@[ADDRESS]

   Examples:
     * unix:/tmp/milter-test-client.sock
     * inet:10025
     * inet:10025@localhost
     * inet:10025@[127.0.0.1]
     * inet6:10025
     * inet6:10025@localhost
     * inet6:10025@[::1]

: --verbose

   Logs verbosely.

   'MILTER_LOG_LEVEL=all' environment variable configuration
   has the same effect.

: --version

   Shows version and exits.

=== milter-performance-check

milter-performance-check is a SMTP client that measures MTA
performance. milter-test-server measures milter's
performance and miter-performance-check measures MTA +
milter's performance.

smtp-source bundled with Postfix is a similar
tool. smtp-source has more features.

milter-performance-check is useful because it measures
elapsed time of only SMTP sessions. smtp-source doesn't
provide the feature. You need to also use 'time' command and
measure smtp-source command runtime not elapsed time of SMTP
sessions.

Normally, there isn't big difference between elapsed time of
SMTP sessions and tool runtime.

If you satisfy milter-performance-check's features, it's
better that you use milter-performance-check. If you don't,
smtp-source is more better tool for you.

==== Options

: --help

   Shows available options and exits.

: --smtp-server=SERVER

   Uses SEVER as target SMTP server.

   The default is localhost.

: --smtp-port=PORT

   Uses PORT as SMTP port.

   The default is 25.

: --helo-fqdn=FQDN

   Uses FQDN as HELO SMTP command.

   The default localhost.localdomain.

: --from=FROM

   Uses FROM as MAIL SMTP command.

   The default from@example.com.

: --force-from=FROM

   Uses FROM as MAIL SMTP command even if mail file includes
   'From:' header.

   The default is none.

: --recipient=RECIPIENT

   Uses RECIPIENT as RCPT SMTP command. If you want to use
   multiple recipients, use --recipient n-times.

   The default is [to@example.com].

: --force-recipient=RECIPIENT

   Uses RECIPIENT as RCPT SMTP command even if mail file
   includes 'To:' header. If you want to use multiple
   recipients, use --recipient n-times.

   The default is none.

: --n-mails=N

   Sends N mails. All mails are sent concurrently.

   The default is 100.

: --period=PERIOD

   Sends mails in PERIOD seconds/minutes/hours. Each mail is
   sent averagely. PERIOD is treated as seconds when its
   unit is omitted.

   Example (100 mails are sent):
     * --period=5    # sends mails at intervals of 0.05 seconds (5 / 100)
     * --period=50s  # sends mails at intervals of 0.5 seconds (50 / 100)
     * --period=10m  # sends mails at intervals of 6 seconds (60 * 10 / 100)
     * --period=0.5h # sends mails at intervals of 18 seconds (60 * 60 * 0.5 / 100)

   The default is none.

: --interval=INTERVAL

   Sends mails at intervals of INTERVAL seconds/minutes/hours.
   INTERVAL is treated as seconds when its unit is omitted.

   Example:
     * --interval=5    # sends mails at intervals of 5 seconds
     * --interval=0.5s # sends mails at intervals of 0.5 seconds
     * --interval=10m  # sends mails at intervals of 10 minutes
     * --interval=0.5h # sends mails at intervals of 0.5 hours

   The default is none.

: --shuffle, --no-shuffle

   Shuffles target mails before sending.

   The default is false. (don't shuffle.)

=== milter-manager-log-analyzer

milter-manager-log-analyzer analyzes milter-manager log and
generates graphs for milters' result. It's useful for
confirming system status transition because graphs shows
data in time-line. Graphs can also be used for comparing
changes between before introducing new milter and after
introducing new milter.

==== Options

: --help

   Shows available options and exits.

: --log=lOG_FILE

   Reads log from LOG_FILE

   The default is standard input.

: --output-directory=DIRECTORY

   Outputs graphs, HTML and data to DIRECTORY.

   The default is the current directory. (".")

: --no-update-db

   Doesn't update database. It's useful for just generates
   graphs.

   If this option is not specified, database will be updated.

== Thanks

  * OBATA Akio: reports a bug.
