summaryrefslogtreecommitdiffstats
path: root/debian/manpages/update-exim4.conf.8
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--debian/manpages/update-exim4.conf.8346
1 files changed, 346 insertions, 0 deletions
diff --git a/debian/manpages/update-exim4.conf.8 b/debian/manpages/update-exim4.conf.8
new file mode 100644
index 0000000..9a4efcb
--- /dev/null
+++ b/debian/manpages/update-exim4.conf.8
@@ -0,0 +1,346 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH UPDATE-EXIM4.CONF 8 "Jun 25, 2005" EXIM4
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.\" \(oqthis text is enclosed in single quotes\(cq
+.\" \(lqthis text is enclosed in double quotes\(rq
+.SH NAME
+update\-exim4.conf \- Generate exim4 configuration files.
+
+.SH SYNOPSIS
+.B update\-exim4.conf [\-v|\-\-verbose] [\-h|\-\-help] [\-\-keepcomments] [\-\-removecomments] [\-o|\-\-output file]
+
+.SH OPTIONS
+.TP
+.I \-\-check
+Generate temporary configuration file, check its validity and exit with
+either success (exitcode 0) or an error (exitcode 1). On success the
+temporary file is deleted, otherwise the file is left for further
+debugging.
+.TP
+.I \-d|\-\-confdir directory
+Read input from directory instead of /etc/exim4.
+.TP
+.I \-h|\-\-help
+Show short help message and exit
+.TP
+.I \-\-keepcomments
+Do not remove comment lines from the output file.
+.TP
+.I \-o|\-\-output file
+Write output to file instead of /var/lib/exim4/config.autogenerated.
+.TP
+.I \-\-removecomments
+Remove comment lines from the output file. [Default]
+.TP
+.I \-v|\-\-verbose
+Enable verbose mode
+
+.SH DESCRIPTION
+The script
+.B update\-exim4.conf
+generates the main configuration files
+.I /var/lib/exim4/config.autogenerated
+for
+.B Exim v4
+by merging the data in the template file
+.I /etc/exim4/exim4.conf.template
+or the ones in the
+.I /etc/exim4/conf.d
+directory tree respectively and
+.I /etc/exim4/update\-exim4.conf.conf
+to the output file
+.I /var/lib/exim4/config.autogenerated.
+.PP
+If dc_use_split_config in /etc/exim4/update\-exim4.conf.conf specifies a split
+configuration,
+.B update\-exim4.conf
+processes the /etc/exim4/conf.d subdirectories in the order main, acl,
+router, transport, retry, rewrite and auth. Within each directory it takes
+files in lexical sort order by file name. It concatenates all these files
+and makes the debconf replacement described below.
+
+If you are not using split configuration
+.B update\-exim4.conf
+concatenates
+/etc/exim4/exim4.conf.localmacros
+(if this file exists) and /etc/exim4/exim4.conf.template (in this order) and
+makes the debconf replacement described below.
+
+In either case, before outputting the result
+to /var/lib/exim4/config.autogenerated,
+.B update\-exim4.conf
+generates a number of exim configuration macros from the contents of
+dc_something from /etc/exim4/update\-exim4.conf.conf and inserts them
+into the configuration right after the definition of the exim
+configuration macro UPEX4CmacrosUPEX4C (which is only used as
+placeholder for this case). The macro definitions are bracketed
+with .ifdef clauses to allow the local admin to override the values with
+earlier definitions.
+.B update\-exim4.conf
+makes no other changes to the configuration.
+This makes it very simple to make small changes to the configuration and
+still have the benefits of debconf.
+
+On the other hand if you don't want to manage exim4.conf with debconf
+install your own handcrafted version as /etc/exim4/exim4.conf.
+Exim will use this file if it exists and ignore the autogenerated one.
+Additionally you might want to set
+.I dc_eximconfig_configtype=none
+in /etc/exim4/update\-exim4.conf.conf to stop debconf from asking you questions about exim4.
+
+.B update\-exim4.conf
+exits silently and does nothing if /etc/exim4/exim4.conf exists and \-o
+was not used to direct the output to a different file than
+/var/lib/exim4/config.autogenerated.
+
+.B update\-exim4.conf
+will only use files in the conf.d directory that have a filename which
+consists only of letters, numbers, underscores and hyphens
+([:alnum:]_\-), similar to
+.B run\-parts(8).
+Additionally,
+.B update\-exim4.conf
+will use /etc/exim4/conf.d/foo/bar.rul instead of
+/etc/exim4/conf.d/foo/bar if the .rul file exists. This is meant to be
+helpful for easy interaction with packages extending Exim.
+
+If the new configuration will be written to
+/var/lib/exim4/config.autogenerated,
+.B update\-exim4.conf
+will check the validity of the freshly generated configuration. If
+the new file is detected as invalid, update-exim4.conf leaves the old
+/var/lib/exim4/config.autogenerated untouched and exits with an error.
+
+However, there are still possible invalidities that can only be
+detected at run time. This most notably applies to errors in
+expressions that are expanded at run time.
+
+If the new configuration will be written to some other file, no
+validity checking occurs and that file will always be overwritten.
+
+.SH EXAMPLES
+You want to be able to check exim's queue as normal user: Generate a new
+file, e.g. /etc/exim4/conf.d/main/40_local_mailq, containing only the line
+.I queue_list_requires_admin = false
+
+.SH NOTES
+.B update\-exim4.conf
+changes the file permissions of the output file to the value of the environment
+variable CFILEMODE. If CFILEMODE is neither set in
+/etc/exim4/update\-exim4.conf.conf nor in the environment it defaults to 0644.
+Change this to 0640 if you are keeping sensitive information (LDAP credentials
+et. al.) in there.
+
+.SH CONFIGURATION VARIABLES
+All lists given in configuration variables are semicolon-separated. In
+the past, they used to be colon separated. This was changed to
+semicolon separation to make specification of IPv6 addresses easier.
+Backwards compatibility is preserved, so that old configurations using
+colons as separators do still work. Colons are deprecated and might
+stop working in a later release. If you need to specify a single IPv6
+address in a field that is defined as a list of host names or IP
+addresses, please prefix "<;" to explicitly specify the list separator
+as a semicolon. Otherwise, the code cannot tell an IP address from a
+colon-separated list of strange host names.
+
+Using lookups like "dsearch;something" in update-exim4.conf.conf has
+never been supported and does no longer work! If you need this, please
+convert to directly setting the appropriate macros.
+
+.B update\-exim4.conf
+evaluates these patterns in
+.B /etc/exim4/update\-exim4.conf.conf:
+.TP
+.I CFILEMODE
+The octal file mode of the generated file.
+.TP
+.I dc_eximconfig_configtype
+The main configuration type. Sets macro DC_eximconfig_configtype. The macro
+usually contains a shorthand for one of the choices for the
+\(lqGeneral type of mail configuration\(rq debconf question (See
+README.Debian).
+
+.RS
+.B dc_eximconfig_configtype <-> debconf configtype mapping:
+.PD 0.1
+.TP
+\(lqinternet\(rq
+internet site; mail is sent and received directly using SMTP
+.TP
+\(lqsmarthost\(rq
+mail sent by smarthost; received via SMTP or fetchmail
+.TP
+\(lqsatellite\(rq
+mail sent by smarthost; no local mail
+.TP
+\(lqlocal\(rq
+local delivery only; not on a network
+.TP
+\(lqnone\(rq
+no configuration at this time
+.PD
+.RE
+
+.TP
+.I dc_hide_mailname
+Boolean option that controls whether the local mailname in the headers of
+outgoing mail should be hidden. (Only effective for \(lqsmarthost\(rq and
+\(lqsatellite\(rq. Sets macro HIDE_MAILNAME.
+.TP
+.I dc_mailname_in_oh
+Internal use only Boolean option that is set by the maintainer scripts
+after adding the contents of /etc/mailname to the dc_other_hostnames
+list. This is a transition helper since it wouldn't otherwise be
+possible to see whether that domain name has been removed from
+dc_other_hostnames on purpose. This is not used by update-exim4.conf,
+and no macro is set.
+.TP
+.I ue4c_keepcomments
+Boolean option that controls whether
+.B update\-exim4.conf
+strips the comments from the target configuration file (default) or
+leaves them in. This can be overridden by the command line options
+\-\-keepcomments and \-\-removecomments. The value is not written to an
+exim macro.
+.TP
+.I dc_localdelivery
+name of the default transport for local mail delivery. Defaults to mail_spool
+if unset, use maildir_home for delivery to ~/Maildir/. Sets macro
+LOCAL_DELIVERY.
+.TP
+.I dc_local_interfaces
+List of IP addresses the Exim daemon should listen on. If this is left
+empty, Exim listens on all interfaces. Sets macro
+MAIN_LOCAL_INTERFACES only if there is a non-empty value.
+.TP
+.I dc_minimaldns
+Boolean option to activate some option to minimize DNS lookups, if set to
+\(lqtrue\(rq a macro DC_minimaldns is defined. If true, the macro
+DC_minimaldns is set to 1, and the macro
+MAIN_HARDCODE_PRIMARY_HOSTNAME is set to the appropriately
+post-processes output of hostname \-\-fqdn.
+.TP
+.I dc_other_hostnames
+is used to build the local_domains list, together with \(lqlocalhost\(rq.
+This is the list of domains for which this machine should
+consider itself the final destination. The local_domains list ends up
+in the macro MAIN_LOCAL_DOMAINS.
+.TP
+.I dc_readhost
+For \(lqsmarthost\(rq and \(lqsatellite\(rq it is possible to hide the local
+mailname in the headers of outgoing mail and replace it with this value
+instead, using rewriting. For \(lqsatellite\(rq only, this value is
+also the host to send local mail to. Sets macro DCreadhost.
+.TP
+.I dc_relay_domains
+is a list of domains for which we accept mail from anywhere on the
+Internet but which are not delivered locally, e.g. because this machine
+serves as secondary MX for these domains. Sets MAIN_RELAY_TO_DOMAINS.
+.TP
+.I dc_relay_nets
+A list of machines for which we serve as smarthost. Please note that
+127.0.0.1 and ::1 are always permitted to relay since /usr/lib/sendmail
+is available anyway and relay control doesn't make sense here. Sets
+macro MAIN_RELAY_NETS.
+.TP
+.I dc_smarthost
+List of hosts to which all outgoing mail is passed to and that takes care
+of delivering it. Each of the hosts is tried, in the order specified
+(See exim specification, chapter 20.5). All deliveries go out to TCP
+port 25 unless a different port is specified after the host name,
+separated from the host name by two colons. Colons in IPv6 addresses need
+to be doubled. If a port number follows, IP addresses may be enclosed in
+brackets, which might be the only possibility to specify delivery to an
+IPv6 address and a different port. Examples:
+.br
+.BR host.domain.example
+deliver to host looked up on DNS, tcp/25
+.br
+.BR host.domain.example::587
+deliver to host looked up on DNS, tcp/587
+.br
+.BR 192.168.2.4
+deliver to IPv4 host, tcp/25
+.br
+.BR 192.168.2.4::587
+deliver to IPv4 host, tcp/587
+.br
+.BR [192.168.2.4]::587
+deliver to IPv4 host, tcp/587
+.br
+.BR 2001::0db8::f::4::::2
+deliver to IPv6 host, tcp/25
+.br
+.BR [2001::0db8::f::4::::2]::587
+deliver to IPv6 host, tcp/587
+.br
+This is used as value of the DCsmarthost macro.
+.TP
+.I dc_use_split_config
+Boolean option that controls whether
+.B update\-exim4.conf
+uses /etc/exim4/exim4.conf.template (\(lqfalse\(rq) or the multiple files
+below /etc/exim4/conf.d (\(lqtrue\(rq) as input. This does not set any
+macros.
+.TP
+.I The macro MAIN_PACKAGE_VERSION is set to Debian's Version number of
+the package being installed for convenient inclusion in the
+configuration.
+
+.SH RECOMMENDED USAGE
+If you are running exim as daemon (as it is in the default setup of the
+Debian packages) you should not invoke
+.B update\-exim4.conf
+directly when exim is running. For SMTP receiving or queue running,
+exim forks, and the new processes would use the new configuration file,
+while the original main exim daemon would still use the old configuration
+file. You should use
+.I invoke\-rc.d exim4 restart
+instead.
+
+.SH BUGS
+This manual page needs a major re-work. If somebody knows better groff
+than us and has more experience in writing manual pages, any patches
+would be greatly appreciated.
+
+.SH FILES
+.LP
+.TP
+.B /var/lib/exim4/config.autogenerated
+Exim's main configuration file
+.LP
+.TP
+.B /etc/exim4/exim4.conf
+Optional manually managed Exim main configuration file. Takes precedence over
+debconf managed one if it exists.
+.LP
+.TP
+.B /etc/exim4/update-exim4.conf.conf
+Configuration file being written by exim4-config maintainer scripts,
+which may be hand-edited, and is read as input by update-exim4.conf.
+
+.SH SEE ALSO
+.BR exim (8),
+.BR exim4-config_files(5),
+/usr/share/doc/exim4\-base/ and for general notes and details about interaction
+with debconf
+/usr/share/doc/exim4\-base/README.Debian.gz
+
+.SH AUTHOR
+Andreas Metzler <ametzler at debian.org>
+.br
+Marc Haber <mh+debian-packages@zugschlus.de>