1SMTPCTL(8) System Manager's Manual SMTPCTL(8)
2
3
4
6 smtpctl, mailq - control the Simple Mail Transfer Protocol daemon
7
9 smtpctl command [argument ...]
10 mailq
11
13 The smtpctl program controls smtpd(8). Commands may be abbreviated to
14 the minimum unambiguous prefix; for example, sh ro for show routes.
15
16 The mailq command is provided for compatibility with other MTAs and is
17 simply a shortcut for show queue.
18
19 The following commands are available:
20
21 discover envelope-id | message-id
22 Schedule a single envelope, or all envelopes with the same
23 message ID that were manually moved to the queue.
24
25 encrypt [string]
26 Encrypt the password string to a representation suitable
27 for user credentials and print it to the standard output.
28 If string is not provided, cleartext passwords are read
29 from standard input.
30
31 It is advised to avoid providing the password as a parameter as it
32 will be visible from top(1) and ps(1) output.
33
34 log brief
35 Disable verbose debug logging.
36
37 log verbose
38 Enable verbose debug logging.
39
40 monitor
41 Display updates of some smtpd(8) internal counters in one
42 second intervals. Each line reports the increment of all
43 counters since the last update, except for some counters
44 which are always absolute values. The first line reports
45 the current value of each counter. The fields are:
46
47 · Current number of active SMTP clients (absolute
48 value).
49
50 · New SMTP clients.
51
52 · Disconnected clients.
53
54 · Current number of envelopes in the queue (absolute
55 value).
56
57 · Newly enqueued envelopes.
58
59 · Dequeued envelopes.
60
61 · Successful deliveries.
62
63 · Temporary failures.
64
65 · Permanent failures.
66
67 · Message loops.
68
69 · Expired envelopes.
70
71 · Envelopes removed by the administrator.
72
73 · Generated bounces.
74
75 pause envelope envelope-id | message-id | all
76 Temporarily suspend scheduling for the envelope with the
77 given ID, envelopes with the given message ID, or all
78 envelopes.
79
80 pause mda
81 Temporarily stop deliveries to local users.
82
83 pause mta
84 Temporarily stop relaying and deliveries to remote users.
85
86 pause smtp
87 Temporarily stop accepting incoming sessions.
88
89 profile subsystem
90 Enables real-time profiling of subsystem. Supported sub‐
91 systems are:
92
93 · queue, to profile cost of queue IO
94
95 · imsg, to profile cost of event handlers
96
97 remove envelope-id | message-id | all
98 Remove a single envelope, envelopes with the given message
99 ID, or all envelopes.
100
101 resume envelope envelope-id | message-id | all
102 Resume scheduling for the envelope with the given ID,
103 envelopes with the given message ID, or all envelopes.
104
105 resume mda
106 Resume deliveries to local users.
107
108 resume mta
109 Resume relaying and deliveries to remote users.
110
111 resume route route-id
112 Resume routing on disabled route route-id.
113
114 resume smtp
115 Resume accepting incoming sessions.
116
117 schedule envelope-id | message-id | all
118 Mark as ready for immediate delivery a single envelope,
119 envelopes with the given message ID, or all envelopes.
120
121 show envelope envelope-id
122 Display envelope content for the given ID.
123
124 show hosts
125 Display the list of known remote MX hosts. For each of
126 them, it shows the IP address, the canonical hostname, a
127 reference count, the number of active connections to this
128 host, and the elapsed time since the last connection.
129
130 show hoststats
131 Display status of last delivery for domains that have been
132 active in the last 4 hours. It consists of the following
133 fields, separated by a "|":
134
135 · Domain.
136
137 · Ux timestamp of last delivery.
138
139 · Status of last delivery.
140
141 show message envelope-id
142 Display message content for the given ID.
143
144 show queue
145 Display information concerning envelopes that are currently
146 in the queue. Each line of output describes a single enve‐
147 lope. It consists of the following fields, separated by a
148 "|":
149
150 · Envelope ID.
151
152 · Address family of the client which enqueued the mail.
153
154 · Type of delivery: one of "mta", "mda" or "bounce".
155
156 · Various flags on the envelope.
157
158 · Sender address (return path).
159
160 · The original recipient address.
161
162 · The destination address.
163
164 · Time of creation.
165
166 · Time of expiration.
167
168 · Time of last delivery or relaying attempt.
169
170 · Number of delivery or relaying attempts.
171
172 · Current runstate: either "pending" or "inflight" if
173 smtpd(8) is running, or "offline" otherwise.
174
175 · Delay in seconds before the next attempt if pending,
176 or time elapsed if currently running. This field is
177 blank if smtpd(8) is not running.
178
179 · Error string for the last failed delivery or relay
180 attempt.
181
182 show relays
183 Display the list of currently active relays and associated
184 connectors. For each relay, it shows a number of counters
185 and information on its internal state on a single line.
186 Then comes the list of connectors (source addresses to con‐
187 nect from for this relay).
188
189 show routes
190 Display status of routes currently known by smtpd(8). Each
191 line consists of a route number, a source address, a desti‐
192 nation address, a set of flags, the number of connections
193 on this route, the current penalty level which determines
194 the amount of time the route is disabled if an error
195 occurs, and the delay before it gets reactivated. The fol‐
196 lowing flags are defined:
197
198 D The route is currently disabled.
199
200 N The route is new. No SMTP session has been estab‐
201 lished yet.
202
203 Q The route has a timeout registered to lower its
204 penalty level and possibly reactivate or discard it.
205
206 show stats
207 Displays runtime statistics concerning smtpd(8).
208
209 show status
210 Shows if MTA, MDA and SMTP systems are currently running or
211 paused.
212
213 spf walk
214 Recursively look up SPF records for the domains read from
215 stdin. For example:
216 $ smtpctl spf walk < domains.txt
217
218 SPF records may contain macros which cannot be included in a static list and
219 must be resolved dynamically at connection time.
220 spf walk
221 cannot provide full results in these cases.
222
223 trace subsystem
224 Enables real-time tracing of
225 subsystem.
226 Supported subsystems are:
227
228 · imsg
229
230 · io
231
232 · smtp (incoming sessions)
233
234 · filters
235
236 · mta (outgoing sessions)
237
238 · bounce
239
240 · scheduler
241
242 · expand (aliases/virtual/forward expansion)
243
244 · lookup (user/credentials lookups)
245
246 · stat
247
248 · rules (matched by incoming sessions)
249
250 · mproc
251
252 · all
253
254 unprofile subsystem
255 Disables real-time profiling of
256 subsystem.
257
258 untrace subsystem
259 Disables real-time tracing of
260 subsystem.
261
262 update table name
263 Updates the contents of table
264 name,
265 for tables using the
266 ``file''
267 backend.
268
269 When
270 smtpd
271 receives a message, it generates a
272 message-id
273 for the message, and one
274 envelope-id
275 per recipient.
276 The
277 message-id
278 is a 32-bit random identifier that is guaranteed to be
279 unique on the host system.
280 The
281 envelope-id
282 is a 64-bit unique identifier that encodes the
283 message-id
284 in the 32 upper bits and a random envelope identifier
285 in the 32 lower bits.
286
287 A command which specifies a
288 message-id
289 applies to all recipients of a message;
290 a command which specifies an
291 envelope-id
292 applies to a specific recipient of a message.
293
295 /var/run/smtpd.sock
296 Ux -domain socket used for communication with smtpd(8).
297
299 smtpd(8)
300
302 The smtpctl program first appeared in OpenBSD 4.6.
303
304
305
306 $Mdocdate: September 14 2020 $ SMTPCTL(8)