.\" Man page generated from reStructuredText.
.
.TH AUTOMX.CONF 5 "02/08/2013" "" "automx"
.SH NAME
automx.conf \- automx configuration parameters
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.sp
The \fBautomx\fP automx.conf configuration file specifies all parameters that control
the \fBautomx\fP configuration system. Parameters not specified in automx.conf are
left at their default values.
.SH SYNTAX
.sp
The general format of the automx.conf file is as follows:
.INDENT 0.0
.IP \(bu 2
Each logical line has the form \fBparameter = value\fP. Whitespace around the \fB=\fP is ignored, as is whitespace at the end of a logical line.
.IP \(bu 2
Empty lines and whitespace\-only lines are ignored, as are lines whose first non\-whitespace character is a \fB#\fP.
.IP \(bu 2
When the same parameter is defined multiple times, only the last instance is remembered.
.IP \(bu 2
Uppercase and lowercase matters. Use parameter names, macros and variables exactly as specified.
.UNINDENT
.SH STRUCTURE
.sp
The configuration file is split into sections.
.INDENT 0.0
.IP \(bu 2
A section begins with the section name surrounded by square brackets, e.g. \fB[example.com]\fP.
.IP \(bu 2
A section name identifies a domain or subdomain automx should respond with autoconfiguration instructions upon client request.
.IP \(bu 2
A section defines services which will be sent as autoconfiguration instructions to a client.
.IP \(bu 2
Section names \fBautomx\fP, \fBDEFAULT\fP and \fBglobal\fP are reserved \- they have special meaning.
.UNINDENT
.SH SERVICES
.sp
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.
.sp
The following concatenation of service name smtp and service option _server
creates the smtp_server parameter:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
smtp_server = mail.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Service names available in automx are shown in the following list. The service
options to create parameters are specified in the section called \fI\%Parameters\fP:
.INDENT 0.0
.TP
.B 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.
.TP
.B 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.
.TP
.B 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.
.UNINDENT
.SH PARAMETERS
.INDENT 0.0
.TP
.B autoconfig (no default)
Specifies a path to a file that contains static autoconfiguration
options following to the Mozilla schema.
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This parameter is valid only if backend = file has been specified.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B autodiscover (no default)
Specifies a path to a file that contains static autoconfiguration
options following to the Microsoft schema.
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This parameter is valid only if backend = file has been specified.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B account_name (no default, mandatory)
Specifies a display name in MUA account listings.
.TP
.B account_name_short (no default, mandatory)
Specifies a short display name in MUA account listings.
.TP
.B account_type (default: email, mandatory)
Specifies the account type that should be configured:
.INDENT 7.0
.TP
.B email
Setting this option will create an email configuration.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
The Microsoft schema specifies additional account_types. Currently automx only supports email.
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B 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.
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option applies to Microsoft schema only.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B settings
The client should use the configuration settings sent in this
response.
.TP
.B backend (default: DEFAULT, mandatory)
Specifies the backend method to lookup configuration data. The
following options are available:
.TP
.B file
automx should use logic provided within this section to
identify a different section which holds configuration
settings:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = file
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B filter
automx should use logic provided within this section to
identify a different section which holds configuration
settings:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = filter
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B global
automx should use general settings defined in the global
section:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = global
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B 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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = ldap
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See also automx_ldap(5) for a list of LDAP related configuration options.
.TP
.B 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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = sql
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
See also automx_sql(5) for a list of SQL related configuration options.
.TP
.B static
automx should use general settings provided within the
current section:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
backend = static
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B debug (default: no)
Specifies if automx should note client request and server response to
the (SSL) error log.
.TP
.B 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.
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option applies to Microsoft schema only.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B domains (no default)
Specifies a list of domains automx will output autoconfiguration
information for.
.INDENT 7.0
.IP \(bu 2
Specify \fB*\fP to let automx reply for any domains listed in a
section.
.UNINDENT
.INDENT 7.0
.TP
.B domain, domain, ...
Specify a comma separated list of domains automx should
provide autoconfiguration for.
.UNINDENT
.TP
.B mobileconfig (no default)
Specifies a path to a file that contains static mobileconfiguration
options following to the Mozilla schema.
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This parameter is valid only if backend = file has been specified.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B provider (no default, mandatory)
The FQDN domain name of the domain that provides the configuration
service:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
provider = example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B 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.
.sp
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:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
section_filters = server_1, server_2
server_1 = /usr/sbin/postmap \-q "%u" hash:/etc/postfix/virtual_alias_domains | \e
        sed \-e \(aqs/^.*@\e(\e.*\e)/\e1/g\(aq | grep internal.example.com
server_2 = /usr/sbin/postmap \-q "%u" hash:/etc/postfix/virtual_alias_domains | \e
        sed \-e \(aqs/^.*@\e(\e.*\e)/\e1/g\(aq | grep dmz.example.com
.ft P
.fi
.UNINDENT
.UNINDENT
.TP
.B 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
\fI\%Services\fP for a list of valid service names.
.TP
.B 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
\fI\%Macros and Variables\fP for available options.
.TP
.B 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:
.INDENT 7.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Thunderbird 3.0 accepts only \fBplain\fP and \fBsecure\fP. It will ignore the whole XML file, if other values are given.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B plaintext
The client should use the SASL mechanisms PLAIN or LOGIN
to identify the user.
.TP
.B encrypted
The client should use the SASL mechanisms CRAM\-MD5 or
DIGEST\-MD5 to identify the user.
.TP
.B ntlm
The client should use the SASL NTLM mechanism to identify
the user.
.TP
.B gssapi
The client should use the SASL GSSAPI mechanism to
identify the user.
.TP
.B client\-ip\-address
The client will not send identification data. Instead the
server should recognize the user based on the clients IP
address.
.TP
.B tls\-client\-cert
The client should send a TLS client certificate when the
server requests one.
.TP
.B smtp\-after\-pop
The client should authenticate using POP first, and then
start sending messages over SMTP later.
.TP
.B none
The client should not send any identification data.
.UNINDENT
.TP
.B service_port (no default)
Specifies port number on which the service is offered. Typical,
standardized port numbers are:
.TP
.B service_server (no default)
Specifies the IP address or hostname on which the service is offered.
.TP
.B 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:
.INDENT 7.0
.TP
.B auto
The client should try to start with starttls, proceed with
ssl and settle with none, if only that is available.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This feature is not available in clients following the Mozilla schema. For these clients automx will always output none as encryption level.
.UNINDENT
.UNINDENT
.TP
.B none
The client should use an unencrypted transport layer.
.TP
.B ssl
The client should use an SSL3 or TLS1 encrypted transport
layer from the start.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This option is typical for smtps, pop3s and imaps services and usually requires a dedicated port on the server for SSL encryption only.
.UNINDENT
.UNINDENT
.TP
.B starttls
The client should begin communication on an unencrypted
port and then upgrade the communication to TLS via the
STARTTLS command.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This option is typical for smtp, pop3 and imap services.
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B smtp_author (default: %s)
Specifies the envelope sender address used when the client sends a
message. See the section called \fI\%Macros and Variables\fP for available
options.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.TP
.B smtp_default (no default)
Specifies if this service should be used globally for all outgoing
messages from all accounts.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This feature is available to clients following the Mozilla schema only.
.UNINDENT
.UNINDENT
.TP
.B sign_mobileconfig (default: no)
Specifies whether configuration files for iOS and MacOS should be sent
signed or not. By default signing is disabled.
.TP
.B 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.
.TP
.B sign_key (no default)
Specifies the path to the key used to sign configuration files for iOS
and MacOS.
.UNINDENT
.SH MACROS AND VARIABLES
.sp
The following macros and variables can be used within automx to build service
configuration.
.INDENT 0.0
.TP
.B %%
This is replaced by a literal \fB%\fP character.
.TP
.B %d
When the input key is an address of the form \fI\%localpart@domainpart\fP, this
macro will be replaced by the (RFC 2253) quoted domain part of the
address.
.TP
.B %s
When the input key is an address of the form \fI\%localpart@domainpart\fP, this
macro will be replaced by this (RFC 2253) quoted mail address.
.TP
.B ${varname}
The value of ${varname}, retrieved from an LDAP or SQL query, will be
used.
.TP
.B %u
When the input key is an address of the form \fI\%localpart@domainpart\fP, this
macro will be replaced by the (RFC 2253) quoted local part of the
address.
.UNINDENT
.SH AUTHORS
.INDENT 0.0
.TP
.B Christian Roessner <\fI\%cr@sys4.de\fP>
Wrote the program.
.TP
.B Patrick Ben Koetter <\fI\%p@sys4.de\fP>
Wrote the documentation.
.UNINDENT
.SH SEE ALSO
.sp
\fI\%automx(8)\fP, \fI\%automx.conf(5)\fP, \fI\%automx_ldap(5)\fP, \fI\%automx_script(5)\fP, \fI\%automx_sql(5)\fP, \fI\%automx\-test(1)\fP
.SH COPYRIGHT
This document has been placed in the public domain.
.\" Generated by docutils manpage writer.
.