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