Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SMTPCTL(8)		FreeBSD	System Manager's Manual		    SMTPCTL(8)

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

     smtpctl command [argument ...]

     The smtpctl program controls smtpd(8).  Commands may be abbreviated to
     the minimum unambiguous prefix; for example, sh ro	for show routes.

     The mailq command is provided for compatibility with other	MTAs and is
     simply a shortcut for show	queue.

     The following commands are	available:

     discover envelope-id | message-id
	     Schedule a	single envelope, or all	envelopes with the same	mes-
	     sage ID that were manually	moved to the queue.

     encrypt [string]
	     Encrypt the password string to a representation suitable for user
	     credentials and print it to the standard output.  If string is
	     not provided, cleartext passwords are read	from standard input.

	     It	is advised to avoid providing the password as a	parameter as
	     it	will be	visible	from top(1) and	ps(1) output.

     log brief
	     Disable verbose debug logging.

     log verbose
	     Enable verbose debug logging.

	     Display updates of	some smtpd(8) internal counters	in one second
	     intervals.	 Each line reports the increment of all	counters since
	     the last update, except for some counters which are always	abso-
	     lute values.  The first line reports the current value of each
	     counter.  The fields are:

	     +o	 Current number	of active SMTP clients (absolute value).
	     +o	 New SMTP clients.
	     +o	 Disconnected clients.
	     +o	 Current number	of envelopes in	the queue (absolute value).
	     +o	 Newly enqueued	envelopes.
	     +o	 Dequeued envelopes.
	     +o	 Successful deliveries.
	     +o	 Temporary failures.
	     +o	 Permanent failures.
	     +o	 Message loops.
	     +o	 Expired envelopes.
	     +o	 Envelopes removed by the administrator.
	     +o	 Generated bounces.

     pause envelope envelope-id	| message-id | all
	     Temporarily suspend scheduling for	the envelope with the given
	     ID, envelopes with	the given message ID, or all envelopes.

     pause mda
	     Temporarily stop deliveries to local users.

     pause mta
	     Temporarily stop relaying and deliveries to remote	users.

     pause smtp
	     Temporarily stop accepting	incoming sessions.

     profile subsystem
	     Enables real-time profiling of subsystem.	Supported subsystems

	     +o	 queue,	to profile cost	of queue IO
	     +o	 imsg, to profile cost of event	handlers

     remove envelope-id	| message-id | all
	     Remove a single envelope, envelopes with the given	message	ID, or
	     all envelopes.

     resume envelope envelope-id | message-id |	all
	     Resume scheduling for the envelope	with the given ID, envelopes
	     with the given message ID,	or all envelopes.

     resume mda
	     Resume deliveries to local	users.

     resume mta
	     Resume relaying and deliveries to remote users.

     resume route route-id
	     Resume routing on disabled	route route-id.

     resume smtp
	     Resume accepting incoming sessions.

     schedule envelope-id | message-id | all
	     Mark as ready for immediate delivery a single envelope, envelopes
	     with the given message ID,	or all envelopes.

     show envelope envelope-id
	     Display envelope content for the given ID.

     show hosts
	     Display the list of known remote MX hosts.	 For each of them, it
	     shows the IP address, the canonical hostname, a reference count,
	     the number	of active connections to this host, and	the elapsed
	     time since	the last connection.

     show hoststats
	     Display status of last delivery for domains that have been	active
	     in	the last 4 hours.  It consists of the following	fields,	sepa-
	     rated by a	"|":

	     +o	 Domain.
	     +o	 UNIX timestamp	of last	delivery.
	     +o	 Status	of last	delivery.

     show message envelope-id
	     Display message content for the given ID.

     show queue
	     Display information concerning envelopes that are currently in
	     the queue.	 Each line of output describes a single	envelope.  It
	     consists of the following fields, separated by a "|":

	     +o	 Envelope ID.
	     +o	 Address family	of the client which enqueued the mail.
	     +o	 Type of delivery: one of "mta", "mda" or "bounce".
	     +o	 Various flags on the envelope.
	     +o	 Sender	address	(return	path).
	     +o	 The original recipient	address.
	     +o	 The destination address.
	     +o	 Time of creation.
	     +o	 Time of expiration.
	     +o	 Time of last delivery or relaying attempt.
	     +o	 Number	of delivery or relaying	attempts.
	     +o	 Current runstate: either "pending" or "inflight" if smtpd(8)
		 is running, or	"offline" otherwise.
	     +o	 Delay in seconds before the next attempt if pending, or time
		 elapsed if currently running.	This field is blank if
		 smtpd(8) is not running.
	     +o	 Error string for the last failed delivery or relay attempt.

     show relays
	     Display the list of currently active relays and associated	con-
	     nectors.  For each	relay, it shows	a number of counters and in-
	     formation on its internal state on	a single line.	Then comes the
	     list of connectors	(source	addresses to connect from for this re-

     show routes
	     Display status of routes currently	known by smtpd(8).  Each line
	     consists of a route number, a source address, a destination ad-
	     dress, a set of flags, the	number of connections on this route,
	     the current penalty level which determines	the amount of time the
	     route is disabled if an error occurs, and the delay before	it
	     gets reactivated.	The following flags are	defined:

	     D	 The route is currently	disabled.
	     N	 The route is new.  No SMTP session has	been established yet.
	     Q	 The route has a timeout registered to lower its penalty level
		 and possibly reactivate or discard it.

     show stats
	     Displays runtime statistics concerning smtpd(8).

     show status
	     Shows if MTA, MDA and SMTP	systems	are currently running or

     spf walk
	     Recursively look up SPF records for the domains read from stdin.
	     For example:

		   # smtpctl spf walk <	domains.txt

     trace subsystem
	     Enables real-time tracing of subsystem.  Supported	subsystems

	     +o	 imsg
	     +o	 io
	     +o	 smtp (incoming	sessions)
	     +o	 filters
	     +o	 mta (outgoing sessions)
	     +o	 bounce
	     +o	 scheduler
	     +o	 expand	(aliases/virtual/forward expansion)
	     +o	 lookup	(user/credentials lookups)
	     +o	 stat
	     +o	 rules (matched	by incoming sessions)
	     +o	 mproc
	     +o	 all

     unprofile subsystem
	     Disables real-time	profiling of subsystem.

     untrace subsystem
	     Disables real-time	tracing	of subsystem.

     update table name
	     Updates the contents of table name, for tables using the "file"

     When smtpd	receives a message, it generates a message-id for the message,
     and one envelope-id per recipient.	 The message-id	is a 32-bit random
     identifier	that is	guaranteed to be unique	on the host system.  The
     envelope-id is a 64-bit unique identifier that encodes the	message-id in
     the 32 upper bits and a random envelope identifier	in the 32 lower	bits.

     A command which specifies a message-id applies to all recipients of a
     message; a	command	which specifies	an envelope-id applies to a specific
     recipient of a message.

     /var/run/smtpd.sock     UNIX-domain socket	used for communication with


     The smtpctl program first appeared	in OpenBSD 4.6.

FreeBSD	13.0		      September	18, 2018		  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help