# smtpctl

## NAME



           **smtpctl** , **mailq** — control the SMTP daemon
    


## SYNOPSIS



           **smtpctl** , _command_ [_argument ..._] **mailq**
    


## DESCRIPTION



           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
                   message 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.
    
           **monitor**
                   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 absolute values.  The first line reports
                   the current value of each counter.  The fields are:
    
                   **•** Current number of active SMTP clients (absolute
                       value).
                   **•** New SMTP clients.
                   **•** Disconnected clients.
                   **•** Current number of envelopes in the queue (absolute
                       value).
                   **•** Newly enqueued envelopes.
                   **•** Dequeued envelopes.
                   **•** Successful deliveries.
                   **•** Temporary failures.
                   **•** Permanent failures.
                   **•** Message loops.
                   **•** Expired envelopes.
                   **•** Envelopes removed by the administrator.
                   **•** 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 are:
    
                   **•** queue, to profile cost of queue IO
                   **•** 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, separated by a "|":
    
                   **•** Domain.
                   **•** Unix timestamp of last delivery.
                   **•** 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 "|":
    
                   **•** Envelope ID.
                   **•** Address family of the client which enqueued the mail.
                   **•** Type of delivery: one of "mta", "mda" or "bounce".
                   **•** Various flags on the envelope.
                   **•** Sender address (return path).
                   **•** The original recipient address.
                   **•** The destination address.
                   **•** Time of creation.
                   **•** Time of expiration.
                   **•** Time of last delivery or relaying attempt.
                   **•** Number of delivery or relaying attempts.
                   **•** Current runstate: either "pending" or "inflight" if
                       _smtpd_(8) is running, or "offline" otherwise.
                   **•** 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.
                   **•** Error string for the last failed delivery or relay
                       attempt.
    
           **show relays**
                   Display the list of currently active relays and associated
                   connectors.  For each relay, it shows a number of counters
                   and information on its internal state on a single line.
                   Then comes the list of connectors (source addresses to
                   connect from for this relay).
    
           **show routes**
                   Display status of routes currently known by _smtpd_(8).
                   Each line consists of a route number, a source address, a
                   destination address, 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 paused.
    
           **spf walk**
                   Recursively look up SPF records for the domains read from
                   stdin.  For example:
    
                         $ smtpctl spf walk < domains.txt
    
                   SPF records may contain macros which cannot be included in
                   a static list and must be resolved dynamically at
                   connection time.  **spf walk** cannot provide full results in
                   these cases.
    
           **trace** _subsystem_
                   Enables real-time tracing of _subsystem_.  Supported
                   subsystems are:
    
                   **•** imsg
                   **•** io
                   **•** smtp (incoming sessions)
                   **•** filters
                   **•** mta (outgoing sessions)
                   **•** bounce
                   **•** scheduler
                   **•** expand (aliases/virtual/forward expansion)
                   **•** lookup (user/credentials lookups)
                   **•** stat
                   **•** rules (matched by incoming sessions)
                   **•** mproc
                   **•** 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” backend.
    
           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.
    


## FILES



           _/var/run/smtpd.sock_     Unix-domain socket used for communication
                                   with _smtpd_(8).
    


* * *