diff options
Diffstat (limited to '')
| -rw-r--r-- | debian/manpages/update-exim4.conf.8 | 346 |
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> |