1SMTPCTL(8) System Manager's Manual SMTPCTL(8)
2
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 The mailq command is provided for compatibility with other MTAs and is
17 simply a shortcut for show queue.
18 The following commands are available:
20 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 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 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 log brief
35 Disable verbose debug logging.
36 log verbose
38 Enable verbose debug logging.
39 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 · Current number of active SMTP clients (absolute
48 value).
49 · New SMTP clients.
51 · Disconnected clients.
53 · Current number of envelopes in the queue (absolute
55 value).
56 · Newly enqueued envelopes.
58 · Dequeued envelopes.
60 · Successful deliveries.
62 · Temporary failures.
64 · Permanent failures.
66 · Message loops.
68 · Expired envelopes.
70 · Envelopes removed by the administrator.
72 · Generated bounces.
74 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 pause mda
81 Temporarily stop deliveries to local users.
82 pause mta
84 Temporarily stop relaying and deliveries to remote users.
85 pause smtp
87 Temporarily stop accepting incoming sessions.
88 profile subsystem
90 Enables real-time profiling of subsystem. Supported sub‐
91 systems are:
92 · queue, to profile cost of queue IO
94 · imsg, to profile cost of event handlers
96 remove envelope-id | message-id | all
98 Remove a single envelope, envelopes with the given message
99 ID, or all envelopes.
100 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 resume mda
106 Resume deliveries to local users.
107 resume mta
109 Resume relaying and deliveries to remote users.
110 resume route route-id
112 Resume routing on disabled route route-id.
113 resume smtp
115 Resume accepting incoming sessions.
116 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 show envelope envelope-id
122 Display envelope content for the given ID.
123 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 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 · Domain.
136 · Ux timestamp of last delivery.
138 · Status of last delivery.
140 show message envelope-id
142 Display message content for the given ID.
143 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 · Envelope ID.
151 · Address family of the client which enqueued the mail.
153 · Type of delivery: one of "mta", "mda" or "bounce".
155 · Various flags on the envelope.
157 · Sender address (return path).
159 · The original recipient address.
161 · The destination address.
163 · Time of creation.
165 · Time of expiration.
167 · Time of last delivery or relaying attempt.
169 · Number of delivery or relaying attempts.
171 · Current runstate: either "pending" or "inflight" if
173 smtpd(8) is running, or "offline" otherwise.
174 · 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 · Error string for the last failed delivery or relay
180 attempt.
181 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 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 D The route is currently disabled.
199 N The route is new. No SMTP session has been estab‐
201 lished yet.
202 Q The route has a timeout registered to lower its
204 penalty level and possibly reactivate or discard it.
205 show stats
207 Displays runtime statistics concerning smtpd(8).
208 show status
210 Shows if MTA, MDA and SMTP systems are currently running or
211 paused.
212 spf walk
214 Recursively look up SPF records for the domains read from
215 stdin. For example:
216 $ smtpctl spf walk < domains.txt
217 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 trace subsystem
224 Enables real-time tracing of
225 subsystem.
226 Supported subsystems are:
227 · imsg
229 · io
231 · smtp (incoming sessions)
233 · filters
235 · mta (outgoing sessions)
237 · bounce
239 · scheduler
241 · expand (aliases/virtual/forward expansion)
243 · lookup (user/credentials lookups)
245 · stat
247 · rules (matched by incoming sessions)
249 · mproc
251 · all
253 unprofile subsystem
255 Disables real-time profiling of
256 subsystem.
257 untrace subsystem
259 Disables real-time tracing of
260 subsystem.
261 update table name
263 Updates the contents of table
264 name,
265 for tables using the
266 ``file''
267 backend.
268 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 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 $Mdocdate: September 14 2020 $ SMTPCTL(8)