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