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 trace subsystem
219 Enables real-time tracing of
220 subsystem.
221 Supported subsystems are:
222 · imsg
224 · io
226 · smtp (incoming sessions)
228 · filters
230 · mta (outgoing sessions)
232 · bounce
234 · scheduler
236 · expand (aliases/virtual/forward expansion)
238 · lookup (user/credentials lookups)
240 · stat
242 · rules (matched by incoming sessions)
244 · mproc
246 · all
248 unprofile subsystem
250 Disables real-time profiling of
251 subsystem.
252 untrace subsystem
254 Disables real-time tracing of
255 subsystem.
256 update table name
258 Updates the contents of table
259 name,
260 for tables using the
261 ``file''
262 backend.
263 When
265 smtpd
266 receives a message, it generates a
267 message-id
268 for the message, and one
269 envelope-id
270 per recipient.
271 The
272 message-id
273 is a 32-bit random identifier that is guaranteed to be
274 unique on the host system.
275 The
276 envelope-id
277 is a 64-bit unique identifier that encodes the
278 message-id
279 in the 32 upper bits and a random envelope identifier
280 in the 32 lower bits.
281 A command which specifies a
283 message-id
284 applies to all recipients of a message;
285 a command which specifies an
286 envelope-id
287 applies to a specific recipient of a message.
288
290 /var/run/smtpd.sock
291 Ux -domain socket used for communication with smtpd(8).
292
294 smtpd(8)
295
297 The smtpctl program first appeared in OpenBSD 4.6.
298 $Mdocdate: September 18 2018 $ SMTPCTL(8)