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
76 Temporarily suspend scheduling for the envelope with the
77 given ID, or all envelopes with the given message ID.
78 pause envelope all
80 Temporarily suspend scheduling all the envelopes.
81 pause mda
83 Temporarily stop deliveries to local users.
84 pause mta
86 Temporarily stop relaying and deliveries to remote users.
87 pause smtp
89 Temporarily stop accepting incoming sessions.
90 profile subsystem
92 Enables real-time profiling of subsystem. Supported sub‐
93 systems are:
94 · queue, to profile cost of queue IO
96 · imsg, to profile cost of event handlers
98 remove envelope-id | message-id
100 Remove a single envelope, or all envelopes with the same
101 message ID.
102 remove all
104 Remove all envelopes.
105 resume envelope envelope-id | message-id
107 Resume scheduling for the envelope with the given ID, or
108 all envelopes with the given message ID.
109 resume envelope all
111 Resume scheduling all the envelopes.
112 resume mda
114 Resume deliveries to local users.
115 resume mta
117 Resume relaying and deliveries to remote users.
118 resume route route-id
120 Resume routing on disabled route route-id.
121 resume smtp
123 Resume accepting incoming sessions.
124 schedule all
126 Mark all envelopes as ready for immediate delivery.
127 schedule envelope-id | message-id
129 Mark a single envelope, or all envelopes with the same mes‐
130 sage ID, as ready for immediate delivery.
131 show envelope envelope-id
133 Display envelope content for the given ID.
134 show hosts
136 Display the list of known remote MX hosts. For each of
137 them, it shows the IP address, the canonical hostname, a
138 reference count, the number of active connections to this
139 host, and the elapsed time since the last connection.
140 show hoststats
142 Display status of last delivery for domains that have been
143 active in the last 4 hours. It consists of the following
144 fields, separated by a "|":
145 · Domain.
147 · Ux timestamp of last delivery.
149 · Status of last delivery.
151 show message envelope-id
153 Display message content for the given ID.
154 show queue
156 Display information concerning envelopes that are currently
157 in the queue. Each line of output describes a single enve‐
158 lope. It consists of the following fields, separated by a
159 "|":
160 · Envelope ID.
162 · Address family of the client which enqueued the mail.
164 · Type of delivery: one of "mta", "mda" or "bounce".
166 · Various flags on the envelope.
168 · Sender address (return path).
170 · The original recipient address.
172 · The destination address.
174 · Time of creation.
176 · Time of expiration.
178 · Time of last delivery or relaying attempt.
180 · Number of delivery or relaying attempts.
182 · Current runstate: either "pending" or "inflight" if
184 smtpd(8) is running, or "offline" otherwise.
185 · Delay in seconds before the next attempt if pending,
187 or time ellapsed if currently running. This field is
188 blank if smtpd(8) is not running.
189 · Error string for the last failed delivery or relay
191 attempt.
192 show relays
194 Display the list of currently active relays and associated
195 connectors. For each relay, it shows a number of counters
196 and information on its internal state on a single line.
197 Then comes the list of connectors (source addresses to con‐
198 nect from for this relay).
199 show routes
201 Display status of routes currently known by smtpd(8). Each
202 line consists of a route number, a source address, a desti‐
203 nation address, a set of flags, the number of connections
204 on this route, the current penalty level which determines
205 the amount of time the route is disabled if an error
206 occurs, and the delay before it gets reactivated. The fol‐
207 lowing flags are defined:
208 D The route is currently disabled.
210 N The route is new. No SMTP session has been estab‐
212 lished yet.
213 Q The route has a timeout registered to lower its
215 penalty level and possibly reactivate or discard it.
216 show stats
218 Displays runtime statistics concerning smtpd(8).
219 show status
221 Shows if MTA, MDA and SMTP systems are currently running or
222 paused.
223 trace subsystem
225 Enables real-time tracing of subsystem. Supported subsys‐
226 tems 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 uncorrupt message-id
255 Move all envelopes with the given message ID from corrupt
256 bucket back to queue.
257 unprofile subsystem
259 Disables real-time profiling of subsystem.
260 untrace subsystem
262 Disables real-time tracing of subsystem.
263 update table name
265 Updates the contents of table name, for tables using the
266 ``file'' backend.
267 When smtpd receives a message, it generates a message-id for the mes‐
269 sage, and one envelope-id per recipient. The message-id is a 32-bit
270 random identifier that is guaranteed to be unique on the host system.
271 The envelope-id is a 64-bit unique identifier that encodes the message-
272 id in the 32 upper bits and a random envelope identifier in the 32
273 lower bits.
274 A command which specifies a message-id applies to all recipients of a
276 message; a command which specifies an envelope-id applies to a specific
277 recipient of a message.
278
280 /var/run/smtpd.sock
281 Ux -domain socket used for communication with smtpd(8).
282
284 smtpd(8)
285
287 The smtpctl program first appeared in OpenBSD 4.6.
288 $Mdocdate: May 23 2017 $ SMTPCTL(8)