| 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> |