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 EXIM_DB 8 "December 26, 2012" | |
6 | .\" Please adjust this date whenever revising the manpage. | |
7 | .\" Up to date for 4.80 | |
8 | .\" | |
9 | .\" Some roff macros, for reference: | |
10 | .\" .nh disable hyphenation | |
11 | .\" .hy enable hyphenation | |
12 | .\" .ad l left justify | |
13 | .\" .ad b justify to both left and right margins | |
14 | .\" .nf disable filling | |
15 | .\" .fi enable filling | |
16 | .\" .br insert line break | |
17 | .\" .sp <n> insert n+1 empty lines | |
18 | .\" for manpage-specific macros, see man(7) | |
19 | .\" \(oqthis text is enclosed in single quotes\(cq | |
20 | .\" \(lqthis text is enclosed in double quotes\(rq | |
21 | .SH NAME | |
22 | exim_db \- Exim's hint databases maintenance (exim_dumpdb, exim_fixdb, exim_tidydb) | |
23 | .SH SYNOPSIS | |
24 | .B exim_dumpdb | |
25 | .I spooldir database | |
26 | .br | |
27 | .B exim_fixdb | |
28 | .I spooldir database | |
29 | .br | |
30 | .B exim_tidydb | |
31 | .I [\-f] [\-t time] spooldir database | |
32 | ||
33 | .SH DESCRIPTION | |
34 | Three utility programs are provided for maintaining the DBM files that | |
35 | Exim uses to contain its delivery hint information. | |
36 | Each program requires two arguments. | |
37 | The first specifies the name of Exim's spool directory, and the second is | |
38 | the name of the database it is to operate on. | |
39 | These are as follows: | |
40 | .TP | |
41 | .B retry | |
42 | the database of retry information | |
43 | .TP | |
44 | .B wait\-<transport name> | |
45 | databases of information about messages waiting for remote hosts | |
46 | .TP | |
47 | .B callout | |
48 | the callout cache | |
49 | .TP | |
50 | .B ratelimit | |
51 | the data for implementing the ratelimit ACL condition | |
52 | .TP | |
53 | .B misc | |
54 | other hints data (for example, for serializing ETRN runs) | |
55 | .P | |
56 | The entire contents of a database are written to the standard output by the | |
57 | .B exim_dumpdb | |
58 | program, which has no options or arguments other than the spool | |
59 | and database names. | |
60 | For example, to dump the retry database: | |
61 | ||
62 | .I exim_dumpdb /var/spool/exim4 retry | |
63 | ||
64 | Two lines of output are produced for each entry: | |
65 | .nf | |
66 | T:mail.ref.example:192.168.242.242 146 77 Connection refused | |
67 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * | |
68 | ||
69 | .fi | |
70 | The first item on the first line is the key of the record. | |
71 | It starts with one of the letters R, or T, depending on whether it refers | |
72 | to a routing or transport retry. | |
73 | For a local delivery, the next part is the local address; for a remote | |
74 | delivery it is the name of the remote host, followed by its failing IP | |
75 | address (unless \(lqretry_include_ip_address\(rq is set false on the smtp | |
76 | transport). If the remote port is not the standard one (port 25), it is | |
77 | added to the IP address. | |
78 | Then there follows an error code, an additional error code, and a | |
79 | textual description of the error. | |
80 | ||
81 | The three times on the second line are the time of first failure, the time of | |
82 | the last delivery attempt, and the computed time for the next attempt. | |
83 | The line ends with an asterisk if the cutoff time for the last retry rule | |
84 | has been exceeded. | |
85 | ||
86 | Each output line from | |
87 | .B exim_dumpdb | |
88 | for the | |
89 | .I wait\-xxx | |
90 | databases consists of a host name followed by a list of ids for messages | |
91 | that are or were waiting to be delivered to that host. | |
92 | If there are a very large number for any one host, continuation records, | |
93 | with a sequence number added to the host name, may be seen. | |
94 | The data in these records is often out of date, because a message may be | |
95 | routed to several alternative hosts, and Exim makes no effort to keep | |
96 | cross-references. | |
97 | ||
98 | The | |
99 | .B exim_tidydb | |
100 | utility program is used to tidy up the contents of a hints database. | |
101 | If run with no options, it removes all records that are more than 30 days | |
102 | old. The age is calculated from the date and time that the record was last | |
103 | updated. Note that, in the case of the retry database, it is not the time | |
104 | since the first delivery failure. Information about a host that has been | |
105 | down for more than 30 days will remain in the database, provided that the | |
106 | record is updated sufficiently often. | |
107 | ||
108 | The cutoff date can be altered by means of the \-t option, which must be | |
109 | followed by a time. | |
110 | For example, to remove all records older than a week from the retry | |
111 | database: | |
112 | ||
113 | .I exim_tidydb \-t 7d /var/spool/exim4 retry | |
114 | ||
115 | Both the | |
116 | .I wait\-xxx | |
117 | and | |
118 | .I retry | |
119 | databases contain items that involve message ids. | |
120 | In the former these appear as data in records keyed by host - they were | |
121 | messages that were waiting for that host - and in the latter they are the | |
122 | keys for retry information for messages that have suffered certain types | |
123 | of error. | |
124 | When \(lqexim_tidydb\(rq is run, a check is made to ensure that message ids in | |
125 | database records are those of messages that are still on the queue. | |
126 | Message ids for messages that no longer exist are removed from \(lqwait\-\(rqxxx | |
127 | records, and if this leaves any records empty, they are deleted. | |
128 | For the \(lqretry\(rq database, records whose keys are non-existent message | |
129 | ids are removed. | |
130 | The | |
131 | .B exim_tidydb | |
132 | utility outputs comments on the standard output whenever it removes | |
133 | information from the database. | |
134 | ||
135 | Certain records are automatically removed by Exim when they are no longer | |
136 | needed, but others are not. For example, if all the MX hosts for a domain | |
137 | are down, a retry record is created for each one. If the primary MX host | |
138 | comes back first, its record is removed when Exim successfully delivers to | |
139 | it, but the records for the others remain because Exim has not tried to use | |
140 | those hosts. | |
141 | ||
142 | It is important, therefore, to run \(lqexim_tidydb\(rq periodically on all | |
143 | the hints databases. You should do this at a quiet time of day, because it | |
144 | requires a database to be locked (and therefore inaccessible to Exim) while | |
145 | it does its work. Removing records from a DBM file does not normally make | |
146 | the file smaller, but all the common DBM libraries are able to re-use the | |
147 | space that is released. After an initial phase of increasing in size, the | |
148 | databases normally reach a point at which they no longer get any bigger, as | |
149 | long as they are regularly tidied. | |
150 | ||
151 | Warning: If you never run \(lqexim_tidydb\(rq, the space used by the hints | |
152 | databases is likely to keep on increasing. | |
153 | ||
154 | The | |
155 | .B exim_fixdb | |
156 | program is a utility for interactively modifying databases. | |
157 | Its main use is for testing Exim, but it might also be occasionally useful | |
158 | for getting round problems in a live system. | |
159 | It has no options, and its interface is somewhat crude. | |
160 | On entry, it prompts for input with a right angle-bracket. | |
161 | A key of a database record can then be entered, and the data for that | |
162 | record is displayed. | |
163 | ||
164 | If \(oqd\(cq is typed at the next prompt, the entire record is deleted. | |
165 | For all except the | |
166 | .I retry | |
167 | database, that is the only operation that can be carried out. | |
168 | For the | |
169 | .I retry | |
170 | database, each field is output preceded by a number, and data for individual | |
171 | fields can be changed by typing the field number followed by new data, for | |
172 | example: | |
173 | ||
174 | > 4 951102:1000 | |
175 | ||
176 | resets the time of the next delivery attempt. | |
177 | Time values are given as a sequence of digit pairs for year, month, day, | |
178 | hour, and minute. | |
179 | Colons can be used as optional separators. | |
180 | ||
181 | .SH BUGS | |
182 | This manual page needs a major re-work. If somebody knows better groff | |
183 | than us and has more experience in writing manual pages, any patches | |
184 | would be greatly appreciated. | |
185 | ||
186 | .SH SEE ALSO | |
187 | .BR exim (8), | |
188 | /usr/share/doc/exim4\-base/ | |
189 | ||
190 | .SH AUTHOR | |
191 | This manual page was stitched together from spec.txt by | |
192 | Andreas Metzler <ametzler at downhill.at.eu.org>, | |
193 | for the Debian GNU/Linux system (but may be used by others). |