1.\" $OpenBSD: smtpctl.8,v 1.65 2020/09/14 09:48:08 martijn Exp $ 2.\" 3.\" Copyright (c) 2006 Pierre-Yves Ritschard <pyr@openbsd.org> 4.\" Copyright (c) 2012 Gilles Chehade <gilles@poolp.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: September 14 2020 $ 19.Dt SMTPCTL 8 20.Os 21.Sh NAME 22.Nm smtpctl , 23.Nm mailq 24.Nd control the Simple Mail Transfer Protocol daemon 25.Sh SYNOPSIS 26.Nm 27.Ar command 28.Op Ar argument ... 29.Nm mailq 30.Sh DESCRIPTION 31The 32.Nm 33program controls 34.Xr smtpd 8 . 35Commands may be abbreviated to the minimum unambiguous prefix; for example, 36.Cm sh ro 37for 38.Cm show routes . 39.Pp 40The 41.Nm mailq 42command is provided for compatibility with other MTAs 43and is simply a shortcut for 44.Cm show queue . 45.Pp 46The following commands are available: 47.Bl -tag -width Ds 48.It Cm discover Ar envelope-id | message-id 49Schedule a single envelope, or all envelopes with the same message ID 50that were manually moved to the queue. 51.It Cm encrypt Op Ar string 52Encrypt the password 53.Ar string 54to a representation suitable for user credentials and print it to the 55standard output. 56If 57.Ar string 58is not provided, cleartext passwords are read from standard input. 59.Pp 60It is advised to avoid providing the password as a parameter as it will be 61visible from 62.Xr top 1 63and 64.Xr ps 1 65output. 66.It Cm log brief 67Disable verbose debug logging. 68.It Cm log verbose 69Enable verbose debug logging. 70.It Cm monitor 71Display updates of some 72.Xr smtpd 8 73internal counters in one second intervals. 74Each line reports the increment of all counters since the last update, 75except for some counters which are always absolute values. 76The first line reports the current value of each counter. 77The fields are: 78.Pp 79.Bl -bullet -compact 80.It 81Current number of active SMTP clients (absolute value). 82.It 83New SMTP clients. 84.It 85Disconnected clients. 86.It 87Current number of envelopes in the queue (absolute value). 88.It 89Newly enqueued envelopes. 90.It 91Dequeued envelopes. 92.It 93Successful deliveries. 94.It 95Temporary failures. 96.It 97Permanent failures. 98.It 99Message loops. 100.It 101Expired envelopes. 102.It 103Envelopes removed by the administrator. 104.It 105Generated bounces. 106.El 107.It Cm pause envelope Ar envelope-id | message-id | Cm all 108Temporarily suspend scheduling for the envelope with the given ID, 109envelopes with the given message ID, 110or all envelopes. 111.It Cm pause mda 112Temporarily stop deliveries to local users. 113.It Cm pause mta 114Temporarily stop relaying and deliveries to 115remote users. 116.It Cm pause smtp 117Temporarily stop accepting incoming sessions. 118.It Cm profile Ar subsystem 119Enables real-time profiling of 120.Ar subsystem . 121Supported subsystems are: 122.Pp 123.Bl -bullet -compact 124.It 125queue, to profile cost of queue IO 126.It 127imsg, to profile cost of event handlers 128.El 129.It Cm remove Ar envelope-id | message-id | Cm all 130Remove a single envelope, 131envelopes with the given message ID, 132or all envelopes. 133.It Cm resume envelope Ar envelope-id | message-id | Cm all 134Resume scheduling for the envelope with the given ID, 135envelopes with the given message ID, 136or all envelopes. 137.It Cm resume mda 138Resume deliveries to local users. 139.It Cm resume mta 140Resume relaying and deliveries to remote users. 141.It Cm resume route Ar route-id 142Resume routing on disabled route 143.Ar route-id . 144.It Cm resume smtp 145Resume accepting incoming sessions. 146.It Cm schedule Ar envelope-id | message-id | Cm all 147Mark as ready for immediate delivery 148a single envelope, 149envelopes with the given message ID, 150or all envelopes. 151.It Cm show envelope Ar envelope-id 152Display envelope content for the given ID. 153.It Cm show hosts 154Display the list of known remote MX hosts. 155For each of them, it shows the IP address, the canonical hostname, 156a reference count, the number of active connections to this host, 157and the elapsed time since the last connection. 158.It Cm show hoststats 159Display status of last delivery for domains that have been active in the 160last 4 hours. 161It consists of the following fields, separated by a "|": 162.Pp 163.Bl -bullet -compact 164.It 165Domain. 166.It 167.Ux 168timestamp of last delivery. 169.It 170Status of last delivery. 171.El 172.It Cm show message Ar envelope-id 173Display message content for the given ID. 174.It Cm show queue 175Display information concerning envelopes that are currently in the queue. 176Each line of output describes a single envelope. 177It consists of the following fields, separated by a "|": 178.Pp 179.Bl -bullet -compact 180.It 181Envelope ID. 182.It 183Address family of the client which enqueued the mail. 184.It 185Type of delivery: one of "mta", "mda" or "bounce". 186.It 187Various flags on the envelope. 188.It 189Sender address (return path). 190.It 191The original recipient address. 192.It 193The destination address. 194.It 195Time of creation. 196.It 197Time of expiration. 198.It 199Time of last delivery or relaying attempt. 200.It 201Number of delivery or relaying attempts. 202.It 203Current runstate: either "pending" or "inflight" if 204.Xr smtpd 8 205is running, or "offline" otherwise. 206.It 207Delay in seconds before the next attempt if pending, or time elapsed 208if currently running. 209This field is blank if 210.Xr smtpd 8 211is not running. 212.It 213Error string for the last failed delivery or relay attempt. 214.El 215.It Cm show relays 216Display the list of currently active relays and associated connectors. 217For each relay, it shows a number of counters and information on its 218internal state on a single line. 219Then comes the list of connectors 220(source addresses to connect from for this relay). 221.It Cm show routes 222Display status of routes currently known by 223.Xr smtpd 8 . 224Each line consists of a route number, a source address, a destination 225address, a set of flags, the number of connections on this 226route, the current penalty level which determines the amount of time 227the route is disabled if an error occurs, and the delay before it 228gets reactivated. 229The following flags are defined: 230.Pp 231.Bl -tag -width xx -compact 232.It D 233The route is currently disabled. 234.It N 235The route is new. 236No SMTP session has been established yet. 237.It Q 238The route has a timeout registered to lower its penalty level and possibly 239reactivate or discard it. 240.El 241.It Cm show stats 242Displays runtime statistics concerning 243.Xr smtpd 8 . 244.It Cm show status 245Shows if MTA, MDA and SMTP systems are currently running or paused. 246.It Cm spf walk 247Recursively look up SPF records for the domains read from stdin. 248For example: 249.Bd -literal -offset indent 250$ smtpctl spf walk < domains.txt 251.Ed 252.Pp 253SPF records may contain macros which cannot be included in a static list and 254must be resolved dynamically at connection time. 255.Cm spf walk 256cannot provide full results in these cases. 257.It Cm trace Ar subsystem 258Enables real-time tracing of 259.Ar subsystem . 260Supported subsystems are: 261.Pp 262.Bl -bullet -compact 263.It 264imsg 265.It 266io 267.It 268smtp (incoming sessions) 269.It 270filters 271.It 272mta (outgoing sessions) 273.It 274bounce 275.It 276scheduler 277.It 278expand (aliases/virtual/forward expansion) 279.It 280lookup (user/credentials lookups) 281.It 282stat 283.It 284rules (matched by incoming sessions) 285.It 286mproc 287.It 288all 289.El 290.It Cm unprofile Ar subsystem 291Disables real-time profiling of 292.Ar subsystem . 293.It Cm untrace Ar subsystem 294Disables real-time tracing of 295.Ar subsystem . 296.It Cm update table Ar name 297Updates the contents of table 298.Ar name , 299for tables using the 300.Dq file 301backend. 302.El 303.Pp 304When 305.Nm smtpd 306receives a message, it generates a 307.Ar message-id 308for the message, and one 309.Ar envelope-id 310per recipient. 311The 312.Ar message-id 313is a 32-bit random identifier that is guaranteed to be 314unique on the host system. 315The 316.Ar envelope-id 317is a 64-bit unique identifier that encodes the 318.Ar message-id 319in the 32 upper bits and a random envelope identifier 320in the 32 lower bits. 321.Pp 322A command which specifies a 323.Ar message-id 324applies to all recipients of a message; 325a command which specifies an 326.Ar envelope-id 327applies to a specific recipient of a message. 328.Sh FILES 329.Bl -tag -width "/var/run/smtpd.sockXXX" -compact 330.It Pa /var/run/smtpd.sock 331.Ux Ns -domain 332socket used for communication with 333.Xr smtpd 8 . 334.El 335.Sh SEE ALSO 336.Xr smtpd 8 337.Sh HISTORY 338The 339.Nm 340program first appeared in 341.Ox 4.6 . 342