bionic (5) automx.conf.5.gz

Provided by: automx_0.10.0-2.1build1_all bug

NAME

       automx.conf - automx configuration parameters

DESCRIPTION

       The  automx automx.conf configuration file specifies all parameters that control the automx configuration
       system. Parameters not specified in automx.conf are left at their default values.

SYNTAX

       The general format of the automx.conf file is as follows:

       • Each logical line has the form parameter = value. Whitespace around the = is ignored, as is  whitespace
         at the end of a logical line.

       • Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is
         a #.

       • When the same parameter is defined multiple times, only the last instance is remembered.

       • Uppercase and lowercase matters. Use parameter names, macros and variables exactly as specified.

STRUCTURE

       The configuration file is split into sections.

       • A section begins with the section name surrounded by square brackets, e.g. [example.com].

       • A section  name  identifies  a  domain  or  subdomain  automx  should  respond  with  autoconfiguration
         instructions upon client request.

       • A section defines services which will be sent as autoconfiguration instructions to a client.

       • Section names automx, DEFAULT and global are reserved - they have special meaning.

SERVICES

       Each  section  may  specify  one  more  services that should be provided to the client. A service must be
       defined in a section in  order  to  be  enabled.  Options  specific  to  a  service  are  given  using  a
       concatenation of a service name and the parameter it should configure.

       The  following  concatenation  of  service  name  smtp and service option _server creates the smtp_server
       parameter:

          smtp_server = mail.example.com

       Service names available in automx are shown  in  the  following  list.  The  service  options  to  create
       parameters are specified in the section called Parameters:

       imap   This  name  specifies  a service as defined in RFC 3501. The protocol to connect to this server is
              IMAP. Specifying this name is only applicable for account_type = email.

       pop    This name specifies a service as defined in RFC 1939. The protocol to connect to  this  server  is
              POP3. Specifying this name is only applicable for account_type = email.

       smtp   This name specifies an SMTP service as defined in RFC 5321. The protocol to connect to this server
              is SMTP. Specifying this name is only applicable for account_type = email.

PARAMETERS

       autoconfig (no default)
              Specifies a path to a file that contains static autoconfiguration options following to the Mozilla
              schema.

                 NOTE:
                     This parameter is valid only if backend = file has been specified.

       autodiscover (no default)
              Specifies  a  path  to  a  file  that  contains  static autoconfiguration options following to the
              Microsoft schema.

                 NOTE:
                     This parameter is valid only if backend = file has been specified.

       account_name (no default, mandatory)
              Specifies a display name in MUA account listings.

       account_name_short (no default, mandatory)
              Specifies a short display name in MUA account listings.

       account_type (default: email, mandatory)
              Specifies the account type that should be configured:

              email  Setting this option will create an email configuration.

                     NOTE:
                        The Microsoft schema specifies additional account_types. Currently automx only  supports
                        email.

       action (default: settings, mandatory)
              Specifies whether the response to the client contains configuration settings or if it should visit
              a different server or use a different address.

                 NOTE:
                     This option applies to Microsoft schema only.

              settings
                     The client should use the configuration settings sent in this response.

              backend (default: DEFAULT, mandatory)
                     Specifies the backend method to  lookup  configuration  data.  The  following  options  are
                     available:

              file   automx  should use logic provided within this section to identify a different section which
                     holds configuration settings:

                        backend = file

              filter automx should use logic provided within this section to identify a different section  which
                     holds configuration settings:

                        backend = filter

              global automx should use general settings defined in the global section:

                        backend = global

              ldap   automx  should  use  a mixture of general and individual settings. General settings are set
                     like static settings.  Individual settings should be retrieved from an LDAP query:

                        backend = ldap

                     See also automx_ldap(5) for a list of LDAP related configuration options.

              sql    automx should use a mixture of general and individual settings. General  settings  are  set
                     like static settings.  Individual settings should be retrieved from an SQL query:

                        backend = sql

                     See also automx_sql(5) for a list of SQL related configuration options.

              static automx should use general settings provided within the current section:

                        backend = static

       debug (default: no)
              Specifies if automx should note client request and server response to the (SSL) error log.

       display_name (no default, optional)
              Specifies  an  “optional  display  name  that indicates the name of the sender (...) that could be
              displayed to the user of a mail application” (see: 3.4. Address Specification in  RFC  5322).  The
              client can decide to accept or change the name.

                 NOTE:
                     This option applies to Microsoft schema only.

       domains (no default)
              Specifies a list of domains automx will output autoconfiguration information for.

              • Specify * to let automx reply for any domains listed in a section.

              domain, domain, ...
                     Specify a comma separated list of domains automx should provide autoconfiguration for.

       mobileconfig (no default)
              Specifies  a  path  to  a  file  that contains static mobileconfiguration options following to the
              Mozilla schema.

                 NOTE:
                     This parameter is valid only if backend = file has been specified.

       provider (no default, mandatory)
              The FQDN domain name of the domain that provides the configuration service:

                 provider = example.com

       section_filter (default: domainpart, optional)
              Specifies a list of one or more filters whose result outputs a section name. The filters  will  be
              used in order specified. The first match ends execution of subsequent filters.

              These  filters  will be used instead of the hard coded, internal domainpart filter, which strictly
              uses the domainpart taken from the  email  address  the  client  submitted  in  its  configuration
              request:

                 section_filters = server_1, server_2
                 server_1 = /usr/sbin/postmap -q "%u" hash:/etc/postfix/virtual_alias_domains | \
                         sed -e 's/^.*@\(\.*\)/\1/g' | grep internal.example.com
                 server_2 = /usr/sbin/postmap -q "%u" hash:/etc/postfix/virtual_alias_domains | \
                         sed -e 's/^.*@\(\.*\)/\1/g' | grep dmz.example.com

       service (default: no)
              Specifies  the  service type that should be provided in the configuration response. By default all
              services are disabled. See the section called Services for a list of valid service names.

       service_auth_identity (no default)
              Specifies the login name the client should use when it identifies the user in order to gain access
              to the service. See the section called Macros and Variables for available options.

       service_auth (no default)
              Specifies  the method the client should use when it identifies the user in order to gain access to
              the service. The following options are available:

                 NOTE:
                     Thunderbird 3.0 accepts only plain and secure. It will ignore the whole XML file, if  other
                     values are given.

              plaintext
                     The client should use the SASL mechanisms PLAIN or LOGIN to identify the user.

              encrypted
                     The client should use the SASL mechanisms CRAM-MD5 or DIGEST-MD5 to identify the user.

              ntlm   The client should use the SASL NTLM mechanism to identify the user.

              gssapi The client should use the SASL GSSAPI mechanism to identify the user.

              client-ip-address
                     The  client will not send identification data. Instead the server should recognize the user
                     based on the clients IP address.

              tls-client-cert
                     The client should send a TLS client certificate when the server requests one.

              smtp-after-pop
                     The client should authenticate using POP first, and then start sending messages  over  SMTP
                     later.

              none   The client should not send any identification data.

       service_port (no default)
              Specifies port number on which the service is offered. Typical, standardized port numbers are:

       service_server (no default)
              Specifies the IP address or hostname on which the service is offered.

       service_encryption (no default)
              Specifies  whether  the  client  should  use  a  plaintext  or  an  encrypted  transport layer for
              client-server communication. The following options are available:

              auto   The client should try to start with starttls, proceed with ssl and  settle  with  none,  if
                     only that is available.

                     NOTE:
                        This feature is not available in clients following the Mozilla schema. For these clients
                        automx will always output none as encryption level.

              none   The client should use an unencrypted transport layer.

              ssl    The client should use an SSL3 or TLS1 encrypted transport layer from the start.

                     NOTE:
                        This option is typical for smtps, pop3s  and  imaps  services  and  usually  requires  a
                        dedicated port on the server for SSL encryption only.

              starttls
                     The  client  should  begin  communication  on  an  unencrypted  port  and  then upgrade the
                     communication to TLS via the STARTTLS command.

                     NOTE:
                        This option is typical for smtp, pop3 and imap services.

       smtp_author (default: %s)
              Specifies the envelope sender address used when the client sends a message. See the section called
              Macros and Variables for available options.

              NOTE:
                 This  parameter  is  experimental.  The  feature is available for Microsoft clients only. For a
                 definition of “author” see also RFC 5598, Section 2.1 User Actors.

       smtp_default (no default)
              Specifies if this service should be used globally for all outgoing messages from all accounts.

              NOTE:
                 This feature is available to clients following the Mozilla schema only.

       sign_mobileconfig (default: no)
              Specifies whether configuration files for iOS and MacOS should be sent signed or not.  By  default
              signing is disabled.

       sign_cert (no default)
              Specifies  the  path to the cert used to sign configuration files for iOS and MacOS. The file must
              contain all certificates - certificate and all intermediate certificates concatenated.

       sign_key (no default)
              Specifies the path to the key used to sign configuration files for iOS and MacOS.

MACROS AND VARIABLES

       The following macros and variables can be used within automx to build service configuration.

       %%     This is replaced by a literal % character.

       %d     When the input key is an address of the form localpart@domainpart, this macro will be replaced  by
              the (RFC 2253) quoted domain part of the address.

       %s     When  the input key is an address of the form localpart@domainpart, this macro will be replaced by
              this (RFC 2253) quoted mail address.

       ${varname}
              The value of ${varname}, retrieved from an LDAP or SQL query, will be used.

       %u     When the input key is an address of the form localpart@domainpart, this macro will be replaced  by
              the (RFC 2253) quoted local part of the address.

AUTHORS

       Christian Roessner <cr@sys4.de>
              Wrote the program.

       Patrick Ben Koetter <p@sys4.de>
              Wrote the documentation.

SEE ALSO

       automx(8), automx.conf(5), automx_ldap(5), automx_script(5), automx_sql(5), automx-test(1)

       This document has been placed in the public domain.

                                                   02/08/2013                                     AUTOMX.CONF(5)