1SMTPCTL(8)                  System Manager's Manual                 SMTPCTL(8)
2
3
4

NAME

6       smtpctl, mailq - control the Simple Mail Transfer Protocol daemon
7

SYNOPSIS

9       smtpctl command [argument ...]
10       mailq
11

DESCRIPTION

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

FILES

295            /var/run/smtpd.sock
296                   Ux -domain socket used for communication with smtpd(8).
297

SEE ALSO

299       smtpd(8)
300

HISTORY

302       The smtpctl program first appeared in OpenBSD 4.6.
303
304
305
306                        $Mdocdate: September 14 2020 $              SMTPCTL(8)
Impressum