debian/manpages/update-exim4.conf.8

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" First parameter, NAME, should be all caps
   3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
   4 .\" other parameters are allowed: see man(7), man(1)
   5 .TH UPDATE-EXIM4.CONF 8 "Jun 25, 2005" EXIM4
   6 .\" Please adjust this date whenever revising the manpage.
   7 .\"
   8 .\" Some roff macros, for reference:
   9 .\" .nh        disable hyphenation
  10 .\" .hy        enable hyphenation
  11 .\" .ad l      left justify
  12 .\" .ad b      justify to both left and right margins
  13 .\" .nf        disable filling
  14 .\" .fi        enable filling
  15 .\" .br        insert line break
  16 .\" .sp <n>    insert n+1 empty lines
  17 .\" for manpage-specific macros, see man(7)
  18 .\" \(oqthis text is enclosed in single quotes\(cq
  19 .\" \(lqthis text is enclosed in double quotes\(rq
  20 .SH NAME
  21 update\-exim4.conf \- Generate exim4 configuration files.
  22
  23 .SH SYNOPSIS
  24 .B update\-exim4.conf [\-v|\-\-verbose] [\-h|\-\-help] [\-\-keepcomments] [\-\-removecomments] [\-o|\-\-output file]
  25
  26 .SH OPTIONS
  27 .TP
  28 .I \-v|\-\-verbose
  29 Enable verbose mode
  30 .TP
  31 .I \-h|\-\-help
  32 Show short help message and exit
  33 .TP
  34 .I \-\-keepcomments
  35 Do not remove comment lines from the output file.
  36 .TP
  37 .I \-\-removecomments
  38 Remove comment lines from the output file. [Default]
  39 .TP
  40 .I \-o|\-\-output file
  41 Write output to file instead of /var/lib/exim4/config.autogenerated.
  42 .TP
  43 .I \-d|\-\-confdir directory
  44 Read input from directory instead of /etc/exim4.
  45
  46 .SH DESCRIPTION
  47 The script
  48 .B update\-exim4.conf
  49 generates the main configuration files
  50 .I /var/lib/exim4/config.autogenerated
  51 for
  52 .B Exim v4
  53 by merging the data in the template file
  54 .I /etc/exim4/exim4.conf.template
  55 or the ones in the
  56 .I /etc/exim4/conf.d
  57 directory tree respectively and
  58 .I /etc/exim4/update\-exim4.conf.conf
  59 to the output file
  60 .I /var/lib/exim4/config.autogenerated.
  61 .PP
  62 If dc_use_split_config in /etc/exim4/update\-exim4.conf.conf specifies a split
  63 configuration,
  64 .B update\-exim4.conf
  65 processes the /etc/exim4/conf.d subdirectories in the order main, acl,
  66 router, transport, retry, rewrite and auth. Within each directory it takes
  67 files in lexical sort order by file name. It concatenates all these files
  68 and makes the debconf replacement described below.
  69
  70 If you are not using split configuration
  71 .B update\-exim4.conf
  72 concatenates
  73 /etc/exim4/exim4.conf.localmacros
  74 (if this file exists) and /etc/exim4/exim4.conf.template (in this order) and
  75 makes the debconf replacement described below.
  76
  77 In either case, before outputting the result
  78 to /var/lib/exim4/config.autogenerated,
  79 .B update\-exim4.conf
  80 generates a number of exim configuration macros from the contents of
  81 dc_something from /etc/exim4/update\-exim4.conf.conf and inserts them
  82 into the configuration right after the definition of the exim
  83 configuration macro UPEX4CmacrosUPEX4C (which is only used as
  84 placeholder for this case). The macro definitions are bracketed
  85 with .ifdef clauses to allow the local admin to override the values with
  86 earlier definitions.
  87 .B update\-exim4.conf
  88 makes no other changes to the configuration.
  89 This makes it very simple to make small changes to the configuration and
  90 still have the benefits of debconf.
  91
  92 On the other hand if you don't want to manage exim4.conf with debconf
  93 install your own handcrafted version as /etc/exim4/exim4.conf.
  94 Exim will use this file if it exists and ignore the autogenerated one.
  95 Additionally you might want to set
  96 .I dc_eximconfig_configtype=none
  97 in /etc/exim4/update\-exim4.conf.conf to stop debconf from asking you questions about exim4.
  98
  99 .B update\-exim4.conf
 100 exits silently and does nothing if /etc/exim4/exim4.conf exists and \-o
 101 was not used to direct the output to a different file than
 102 /var/lib/exim4/config.autogenerated.
 103
 104 .B update\-exim4.conf
 105 will only use files in the conf.d directory that have a filename which
 106 consists only of letters, numbers, underscores and hyphens
 107 ([:alnum:]_\-), similar to
 108 .B run\-parts(8).
 109 Additionally,
 110 .B update\-exim4.conf
 111 will use /etc/exim4/conf.d/foo/bar.rul instead of
 112 /etc/exim4/conf.d/foo/bar if the .rul file exists. This is meant to be
 113 helpful for easy interaction with packages extending Exim.
 114
 115 If the new configuration will be written to
 116 /var/lib/exim4/config.autogenerated,
 117 .B update\-exim4.conf
 118 will check the validity of the freshly generated configuration. If
 119 the new file is detected as invalid, update-exim4.conf leaves the old
 120 /var/lib/exim4/config.autogenerated untouched and exits with an error.
 121
 122 However, there are still possible invalidities that can only be
 123 detected at run time. This most notably applies to errors in
 124 expressions that are expanded at run time.
 125
 126 If the new configuration will be written to some other file, no
 127 validity checking occurs and that file will always be overwritten.
 128
 129 .SH EXAMPLES
 130 You want to be able to check exim's queue as normal user: Generate a new
 131 file, e.g. /etc/exim4/conf.d/main/40_local_mailq, containing only the line
 132 .I queue_list_requires_admin = false
 133
 134 .SH NOTES
 135 .B update\-exim4.conf
 136 changes the file permissions of the output file to the value of the environment
 137 variable CFILEMODE. If CFILEMODE is neither set in
 138 /etc/exim4/update\-exim4.conf.conf nor in the environment it defaults to 0644.
 139 Change this to 0640 if you are keeping sensitive information (LDAP credentials
 140 et. al.) in there.
 141
 142 .SH CONFIGURATION VARIABLES
 143 All lists given in configuration variables are semicolon-separated. In
 144 the past, they used to be colon separated. This was changed to
 145 semicolon separation to make specification of IPv6 addresses easier.
 146 Backwards compatibility is preserved, so that old configurations using
 147 colons as separators do still work. Colons are deprecated and might
 148 stop working in a later release. If you need to specifiy a single IPv6
 149 address in a field that is defined as a list of host names or IP
 150 addresses, please prefix "<;" to explicitly specify the list separator
 151 as a semicolon. Otherwise, the code cannot tell an IP address from a
 152 colon-separated list of strange host names.
 153
 154 Using lookups like "dsearch;something" in update-exim4.conf.conf has
 155 never been supported and does no longer work! If you need this, please
 156 convert to directly setting the appropriate macros.
 157
 158 .B update\-exim4.conf
 159 evaluates these patterns in
 160 .B /etc/exim4/update\-exim4.conf.conf:
 161 .TP
 162 .I CFILEMODE
 163 The octal file mode of the generated file.
 164 .TP
 165 .I dc_eximconfig_configtype
 166 The main configuration type. Sets macro DC_eximconfig_configtype. The macro
 167 usually contains a shorthand for one of the choices for the
 168 \(lqGeneral type of mail configuration\(rq debconf question (See
 169 README.Debian).
 170
 171 .RS
 172 .B  dc_eximconfig_configtype <-> debconf configtype mapping:
 173 .PD 0.1
 174 .TP
 175 \(lqinternet\(rq
 176 internet site; mail is sent and received directly using SMTP
 177 .TP
 178 \(lqsmarthost\(rq
 179 mail sent by smarthost; received via SMTP or fetchmail
 180 .TP
 181 \(lqsatellite\(rq
 182 mail sent by smarthost; no local mail
 183 .TP
 184 \(lqlocal\(rq
 185 local delivery only; not on a network
 186 .TP
 187 \(lqnone\(rq
 188 no configuration at this time
 189 .PD
 190 .RE
 191
 192 .TP
 193 .I dc_hide_mailname
 194 Boolean option that controls whether the local mailname in the headers of
 195 outgoing mail should be hidden. (Only effective for \(lqsmarthost\(rq and
 196 \(lqsatellite\(rq. Sets macro HIDE_MAILNAME.
 197 .TP
 198 .I dc_mailname_in_oh
 199 Internal use only Boolean option that is set by the maintainer scripts
 200 after adding the contents of /etc/mailname to the dc_other_hostnames
 201 list. This is a transition helper since it wouldn't otherwise be
 202 possible to see whether that domain name has been removed from
 203 dc_other_hostnames on purpose. This is not used by update-exim4.conf,
 204 and no macro is set.
 205 .TP
 206 .I ue4c_keepcomments
 207 Boolean option that controls whether
 208 .B update\-exim4.conf
 209 strips the comments from the target configuration file (default) or
 210 leaves them in. This can be overridden by the command line options
 211 \-\-keepcomments and \-\-removecomments. The value is not written to an
 212 exim macro.
 213 .TP
 214 .I dc_localdelivery
 215 name of the default transport for local mail delivery. Defaults to mail_spool
 216 if unset, use maildir_home for delivery to ~/Maildir/. Sets macro
 217 LOCAL_DELIVERY.
 218 .TP
 219 .I dc_local_interfaces
 220 List of IP addresses the Exim daemon should listen on. If this is left
 221 empty, Exim listens on all interfaces. Sets macro
 222 MAIN_LOCAL_INTERFACES only if there is a non-empty value.
 223 .TP
 224 .I dc_minimaldns
 225 Boolean option to activate some option to minimize DNS lookups, if set to
 226 \(lqtrue\(rq a macro DC_minimaldns is defined. If true, the macro
 227 DC_minimaldns is set to 1, and the macro
 228 MAIN_HARDCODE_PRIMARY_HOSTNAME is set to the appropriately
 229 post-processes output of hostname \-\-fqdn.
 230 .TP
 231 .I dc_other_hostnames
 232 is used to build the local_domains list, together with \(lqlocalhost\(rq.
 233 This is the list of domains for which this machine should
 234 consider itself the final destination. The local_domains list ends up
 235 in the macro MAIN_LOCAL_DOMAINS.
 236 .TP
 237 .I dc_readhost
 238 For \(lqsmarthost\(rq and \(lqsatellite\(rq it is possible to hide the local
 239 mailname in the headers of outgoing mail and replace it with this value
 240 instead, using rewriting. For \(lqsatellite\(rq only, this value is
 241 also the host to send local mail to. Sets macro DCreadhost.
 242 .TP
 243 .I dc_relay_domains
 244 is a list of domains for which we accept mail from anywhere on the
 245 Internet but which are not delivered locally, e.g. because this machine
 246 serves as secondary MX for these domains. Sets MAIN_RELAY_TO_DOMAINS.
 247 .TP
 248 .I dc_relay_nets
 249 A list of machines for which we serve as smarthost. Please note that
 250 127.0.0.1 and ::1 are always permitted to relay since /usr/lib/sendmail
 251 is available anyway and relay control doesn't make sense here. Sets
 252 macro MAIN_RELAY_NETS.
 253 .TP
 254 .I dc_smarthost
 255 List of hosts to which all outgoing mail is passed to and that takes care
 256 of delivering it. Each of the hosts is tried, in the order specified
 257 (See exim specification, chapter 20.5). All deliveries go out to TCP
 258 port 25 unless a different port is specified after the host name,
 259 separated from the host name by two colons. Colons in IPv6 addresses need
 260 to be doubled. If a port number follows, IP addresses may be enclosed in
 261 brackets, which might be the only possibility to specify delivery to an
 262 IPv6 address and a different port. Examples:
 263 .br
 264 .BR host.domain.example
 265 deliver to host looked up on DNS, tcp/25
 266 .br
 267 .BR host.domain.example::587
 268 deliver to host looked up on DNS, tcp/587
 269 .br
 270 .BR 192.168.2.4
 271 deliver to IPv4 host, tcp/25
 272 .br
 273 .BR 192.168.2.4::587
 274 deliver to IPv4 host, tcp/587
 275 .br
 276 .BR [192.168.2.4]::587
 277 deliver to IPv4 host, tcp/587
 278 .br
 279 .BR 2001::0db8::f::4::::2
 280 deliver to IPv6 host, tcp/25
 281 .br
 282 .BR [2001::0db8::f::4::::2]::587
 283 deliver to IPv6 host, tcp/587
 284 .br
 285 This is used as value of the DCsmarthost macro.
 286 .TP
 287 .I dc_use_split_config
 288 Boolean option that controls whether
 289 .B update\-exim4.conf
 290 uses /etc/exim4/exim4.conf.template (\(lqfalse\(rq) or the multiple files
 291 below /etc/exim4/conf.d (\(lqtrue\(rq) as input. This does not set any
 292 macros.
 293 .TP
 294 .I The macro MAIN_PACKAGE_VERSION is set to Debian's Version number of
 295 the package being installed for convenient inclusion in the
 296 configuration.
 297
 298 .SH RECOMMENDED USAGE
 299 If you are running exim as daemon (as it is in the default setup of the
 300 Debian packages) you should not invoke
 301 .B update\-exim4.conf
 302 directly when exim is running. For SMTP receiving or queue running,
 303 exim forks, and the new processes would use the new configuration file,
 304 while the original main exim daemon would still use the old configuration
 305 file. You should use
 306 .I invoke\-rc.d exim4 restart
 307 instead.
 308
 309 .SH BUGS
 310 This manual page needs a major re-work. If somebody knows better groff
 311 than us and has more experience in writing manual pages, any patches
 312 would be greatly appreciated.
 313
 314 .SH FILES
 315 .LP
 316 .TP
 317 .B /var/lib/exim4/config.autogenerated
 318 Exim's main configuration file
 319 .LP
 320 .TP
 321 .B /etc/exim4/exim4.conf
 322 Optional manually managed Exim main configuration file. Takes precedence over
 323 debconf managed one if it exists.
 324 .LP
 325 .TP
 326 .B /etc/exim4/update-exim4.conf.conf
 327 Configuration file being written by exim4-config maintainer scripts,
 328 which may be hand-edited, and is read as input by update-exim4.conf.
 329
 330 .SH SEE ALSO
 331 .BR exim (8),
 332 .BR exim4-config_files(5),
 333 /usr/share/doc/exim4\-base/ and for general notes and details about interaction
 334 with debconf
 335 /usr/share/doc/exim4\-base/README.Debian.gz
 336
 337 .SH AUTHOR
 338 Andreas Metzler <ametzler at downhill.at.eu.org>
 339 .br
 340 Marc Haber <mh+debian-packages@zugschlus.de>