Commit | Line | Data |
---|---|---|
de45f55a AM |
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 | |
89fb561f AM |
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. | |
de45f55a AM |
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 | |
de45f55a AM |
43 | .I \-o|\-\-output file |
44 | Write output to file instead of /var/lib/exim4/config.autogenerated. | |
45 | .TP | |
89fb561f AM |
46 | .I \-\-removecomments |
47 | Remove comment lines from the output file. [Default] | |
48 | .TP | |
49 | .I \-v|\-\-verbose | |
50 | Enable verbose mode | |
de45f55a AM |
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 | |
89fb561f | 154 | stop working in a later release. If you need to specify a single IPv6 |
de45f55a AM |
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 | |
89fb561f | 344 | Andreas Metzler <ametzler at debian.org> |
de45f55a AM |
345 | .br |
346 | Marc Haber <mh+debian-packages@zugschlus.de> |