1.\" $OpenBSD: smtpctl.8,v 1.58 2016/09/04 09:33:49 eric 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 4 2016 $ 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 108Temporarily suspend scheduling for the envelope with the given ID, 109or all envelopes with the given message ID. 110.It Cm pause envelope all 111Temporarily suspend scheduling all the envelopes. 112.It Cm pause mda 113Temporarily stop deliveries to local users. 114.It Cm pause mta 115Temporarily stop relaying and deliveries to 116remote users. 117.It Cm pause smtp 118Temporarily stop accepting incoming sessions. 119.It Cm profile Ar subsystem 120Enables real-time profiling of 121.Ar subsystem . 122Supported subsystems are: 123.Pp 124.Bl -bullet -compact 125.It 126queue, to profile cost of queue IO 127.It 128imsg, to profile cost of event handlers 129.El 130.It Cm remove Ar envelope-id | message-id 131Remove a single envelope, or all envelopes with the same message ID. 132.It Cm remove all 133Remove all envelopes. 134.It Cm resume envelope Ar envelope-id | message-id 135Resume scheduling for the envelope with the given ID, 136or all envelopes with the given message ID. 137.It Cm resume envelope all 138Resume scheduling all the envelopes. 139.It Cm resume mda 140Resume deliveries to local users. 141.It Cm resume mta 142Resume relaying and deliveries to remote users. 143.It Cm resume route Ar route-id 144Resume routing on disabled route 145.Ar route-id . 146.It Cm resume smtp 147Resume accepting incoming sessions. 148.It Cm schedule all 149Mark all envelopes as ready for immediate delivery. 150.It Cm schedule Ar envelope-id | message-id 151Mark a single envelope, or all envelopes with the same message ID, 152as ready for immediate delivery. 153.It Cm show envelope Ar envelope-id 154Display envelope content for the given ID. 155.It Cm show hosts 156Display the list of known remote MX hosts. 157For each of them, it shows the IP address, the canonical hostname, 158a reference count, the number of active connections to this host, 159and the elapsed time since the last connection. 160.It Cm show hoststats 161Display status of last delivery for domains that have been active in the 162last 4 hours. 163It consists of the following fields, separated by a "|": 164.Pp 165.Bl -bullet -compact 166.It 167Domain. 168.It 169.Ux 170timestamp of last delivery. 171.It 172Status of last delivery. 173.El 174.It Cm show message Ar envelope-id 175Display message content for the given ID. 176.It Cm show queue 177Display information concerning envelopes that are currently in the queue. 178Each line of output describes a single envelope. 179It consists of the following fields, separated by a "|": 180.Pp 181.Bl -bullet -compact 182.It 183Envelope ID. 184.It 185Address family of the client which enqueued the mail. 186.It 187Type of delivery: one of "mta", "mda" or "bounce". 188.It 189Various flags on the envelope. 190.It 191Sender address (return path). 192.It 193The original recipient address. 194.It 195The destination address. 196.It 197Time of creation. 198.It 199Time of expiration. 200.It 201Time of last delivery or relaying attempt. 202.It 203Number of delivery or relaying attempts. 204.It 205Current runstate: either "pending" or "inflight" if 206.Xr smtpd 8 207is running, or "offline" otherwise. 208.It 209Delay in seconds before the next attempt if pending, or time ellapsed 210if currently running. 211This field is blank if 212.Xr smtpd 8 213is not running. 214.It 215Error string for the last failed delivery or relay attempt. 216.El 217.It Cm show relays 218Display the list of currently active relays and associated connectors. 219For each relay, it shows a number of counters and information on its 220internal state on a single line. 221Then comes the list of connectors 222(source addresses to connect from for this relay). 223.It Cm show routes 224Display status of routes currently known by 225.Xr smtpd 8 . 226Each line consists of a route number, a source address, a destination 227address, a set of flags, the number of connections on this 228route, the current penalty level which determines the amount of time 229the route is disabled if an error occurs, and the delay before it 230gets reactivated. 231The following flags are defined: 232.Pp 233.Bl -tag -width xx -compact 234.It D 235The route is currently disabled. 236.It N 237The route is new. 238No SMTP session has been established yet. 239.It Q 240The route has a timeout registered to lower its penalty level and possibly 241reactivate or discard it. 242.El 243.It Cm show stats 244Displays runtime statistics concerning 245.Xr smtpd 8 . 246.It Cm show status 247Shows if MTA, MDA and SMTP systems are currently running or paused. 248.It Cm trace Ar subsystem 249Enables real-time tracing of 250.Ar subsystem . 251Supported subsystems are: 252.Pp 253.Bl -bullet -compact 254.It 255imsg 256.It 257io 258.It 259smtp (incoming sessions) 260.It 261filters 262.It 263mta (outgoing sessions) 264.It 265bounce 266.It 267scheduler 268.It 269expand (aliases/virtual/forward expansion) 270.It 271lookup (user/credentials lookups) 272.It 273stat 274.It 275rules (matched by incoming sessions) 276.It 277mproc 278.It 279all 280.El 281.It Cm uncorrupt Ar message-id 282Move all envelopes with the given message ID from corrupt bucket back to queue. 283.It Cm unprofile Ar subsystem 284Disables real-time profiling of 285.Ar subsystem . 286.It Cm untrace Ar subsystem 287Disables real-time tracing of 288.Ar subsystem . 289.It Cm update table Ar name 290For table backends that provide caching, causes 291.Xr smtpd 8 292to update the cache. 293.El 294.Pp 295When 296.Nm smtpd 297receives a message, it generates a 298.Ar message-id 299for the message, and one 300.Ar envelope-id 301per recipient. 302The 303.Ar message-id 304is a 32-bit random identifier that is guaranteed to be 305unique on the host system. 306The 307.Ar envelope-id 308is a 64-bit unique identifier that encodes the 309.Ar message-id 310in the 32 upper bits and a random envelope identifier 311in the 32 lower bits. 312.Pp 313A command which specifies a 314.Ar message-id 315applies to all recipients of a message; 316a command which specifies an 317.Ar envelope-id 318applies to a specific recipient of a message. 319.Sh FILES 320.Bl -tag -width "/var/run/smtpd.sockXXX" -compact 321.It Pa /var/run/smtpd.sock 322.Ux Ns -domain 323socket used for communication with 324.Xr smtpd 8 . 325.El 326.Sh SEE ALSO 327.Xr smtpd 8 328.Sh HISTORY 329The 330.Nm 331program first appeared in 332.Ox 4.6 . 333