AUTHENTICATION_MILTER(1)

NAME
  Authentication Milter

USAGE
  authentication_milter [-c|--control <command>] [-d|--daemon] [--pidfile <file>] [-h|--help] [--prefix <dir>] [-i|--ident <ident>]

OPTIONS

-c|--control <command>
      Control a running daemon process or start a new one.

      start|restart

        Start a new daemon process, or restart an existing process.

      stop

        Stop an already running daemon process.

      status

        Show the status of a running daemon process.

      Control implies --daemon, and takes account of --pidfile
      If no valid data is found in the pidfile then control will
      search the process list for a master process.

      If you are running multiple distinct instances of authentication
      milter on a single host, each with differing configurations then you
      should use the --ident identifier to differentiate between them.

-h|--help
      Show this help.

-h|--help default_config
      Output an example default configuration, including
      config for all installed handler modules.

-h|--help installed
      Show a list of installed handler modules.

-h|--help <ModuleName>
      Show help for a particular handler module.

      Modules installed by default include the following.

      AddID Auth DKIM DMARC IPRev LocalIP PTR ReturnOK
      Sanitize SenderID SpamAssassin SPF TrustedIP TLS

-d|--daemon
      detatch from shell and run as a daemon

--pidfile <file>
      Write the process PID to the given file.
      defaults to /var/run/authentication_milter.pid

--prefix <dir>
      Read configuration from dir rather than /etc/

-i|--ident <ident>
      A string identifier for use in process management and logging

      This should be used when you are running multiple instances of
      authentication_milter on a single host, each with different configurations.

CONFIGURATION
  The milter reads configuration from /etc/authentication_milter.json

  The configuration file format is as follows...

  {
    "debug"     : 0,                                    | Verbose debugging output
    "dryrun"    : 0,                                    | Dryrun (do not alter or reject mail)
    "logtoerr"  : 0,                                    | Also write logs to STDERR
    "error_log" : "/var/log/authentication_milter.err", | Capture STDERR to logfile

    "connection"             : "inet:12345@localhost",  | The connection to use
    "umask"                  : "0000",                  | Set umask (for unix socket)

    "connections" : {                                   | Other than the default connection, also bind to
                                                        | these connections.

        "name_two" : {                                  | Name of connection
            "connection"   : "unix:/var/sock/a.sock",   | The connection to use
            "umask"        : "0000",                    | Set umask
        }
        "name_one" : {                                  | Name of connection
            "connection"   : "inet:12346@localhost",    | The connection to use
        }
    },

    "runas"                  : "nobody",                | Drop privs and run as this user (root only)
    "rungroup"               : "nogroup",               | Drop privs and run as this group (root daemon only)
    "chroot"                 : "/path/to/chroot"        | Set chroot before forking (root only)
                                                        | N.B. This path will need to be setup with all required
                                                        | files or the server WILL segfault.
    "listen_backlog"         : 20,                      | socket listen backlog limit (default 20)
    "min_children"           : 20,                      | Max number of children to pre fork
    "max_children"           : 200,                     | Max number of children to pre fork
    "min_spare_children"     : 10,                      | Min number of spare children to maintain
    "max_spare_children"     : 20,                      | Max number of spare children to maintain
    "max_requests_per_child" : 200,                     | Max number of requests per child process (prefork)

    "protocol"               : "milter",                | The protocol the milter is to use
                                                        | can be either milter or smtp

    "smtp" : {                                          | Parameters for use when protocol is smtp
        "server_name"    : "scan.example.com",          | The server name to use for the server
        "sock_type"      : "inet",                      | Socket type (inet or unix)
        "sock_host"      : "localhost",                 | Host to connect to (when inet)
        "sock_port"      : "2525",                      | Port to connect to (when inet)
        "sock_path"      : "/var/run/smtp.sock",        | Socket path to connect to (when unix)
        "timeout_in"     : "10",                        | Timeout when waiting for inbound SMTP data
        "timeout_out"    : "10",                        | Timeout when waiting for outbound SMTP data
        "pipeline_limit" : "50",                        | Limit the number of transactions accepted in an SMTP pipeline
        "queue_type"     : "before",                    | SMTP Queue type, either before or after. After queues have
                                                        | an upstream queue ID, before queues do not.

        "tcp:12346" : {                                 | Outbound SMTP details can be set per inbound port/socket
                                                        | This allows outbound SMTP to be routed differently for
                                                        | different inbound ports. The key is the inbound port specified
                                                        | as unix:<socket path> or inet:<port>
                                                        | It is not currently possible to set based on listening host.
                                                        | If a specific config set is not found them we use the default
                                                        | set as defined above.
            "server_name" : "scan.example.com",         | The server name to use for the server
            "sock_type"   : "inet",                     | Socket type (inet or unix)
            "sock_host"   : "localhost",                | Host to connect to (when inet)
            "sock_port"   : "2526",                     | Port to connect to (when inet)
            "timeout_in"  : "10",                       | Timeout when waiting for inbound SMTP data
            "timeout_out" : "10"                        | Timeout when waiting for outbound SMTP data
        },
        "unix:/var/sock/a.sock" : {
            "server_name" : "util.example.com",
            "sock_type"   : "unix",
            "sock_path"   : "/var/run/smtp.sock",
            "timeout_in"  : "10",
            "timeout_out" : "10"
        }

    },

                                                        | Timeouts for callbacks, should be slightly lower
                                                        | than the corresponding timeouts in Postfix
                                                        | Timeouts are ignored if missing.
    "connect_timeout"       : 30,                       | Timeout for Connect callbacks
    "command_timeout"       : 30,                       | Timeout for Helo,Mail,Rcpt,Data and Unknown callbacks
    "content_timeout"       : 300,                      | Timeout for Header,Eoh, Body and Eom callbacksa

    "dns_resolvers"         : [                         | Explicit list of DNS resolvers to use
        "8.8.8.8",
        "127.0.0.1"
    ],
    "dns_timeout"           : 10,                       | Timeout for DNS lookups
    "dns_retry"             : 2,                        | Number of times a lookup will retry per call

    "tempfail_on_error"               : "1",            | Tempfail on errors
    "tempfail_on_error_authenticated" : "0",            | Tempfail on errors for Authenticated IP Connections
    "tempfail_on_error_local"         : "0",            | Tempfail on errors for Local IP Connections
    "tempfail_on_error_trusted"       : "0",            | Tempfail on errors for Trusted IP Connections

    "handlers" : {                                      | Config for each handlers, can be prefixed with !
                                                        | to disable that handler without having to remove
                                                        | its config.

        "ActiveModule" : {
            "foo" : "bar"
        },
        "!InactiveModule" : {},
                                                        | Additionally, config for a module can be placed in a file
                                                        | with filename /etc/authentication_milter.d/ModuleName.json
                                                        | the contents of which should be the JSON assigned to the
                                                        | entry here.

                                                        | Please see the help for each handler for its individual
                                                        | configuration requirements.
    }
  }

DMARC
This milter uses Mail::DMARC as a backend for DMARC checks, this module requires that a configuration file is setup.

You should create and populate /etc/mail-dmarc.ini

For DMARC reporting you are also required to setup a datastore, including creating a basic table structure. The detauls of this are to be found in the Mail::DMARC documentation.

At this time forensic reports are not supported by Mail::DMARC or this milter. Only aggregate reports will be generated.

To check reports please use the dmarc_view_reports command, to send reports please use the dmarc_send_reports command. These are included with the Mail::DMARC module.

AUTHORS
Marc Bradshaw <marc@marcbradshaw.net>

COPYRIGHT
Copyright 2015

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.