Using the kcli Command-Line Client

KumoMTA comes with several API endpoints to make administration of the server easier for common tasks, and additionally comes with the kcli command-line client which provides access to the APIs for local administrative tasks.

The kcli client is located at /opt/kumomta/sbin/kcli and requires a configured HTTP Listener to function.

At minimum, the kcli client must be passed an endpoint and a command:

kcli --endpoint http://127.0.0.1:8000 bounce-list

There is no default endpoint, but our examples use http://127.0.0.1:8000 both in the configuration of the HTTP listener and the use of the kcli client.

Bouncing Messages

The kcli client can be used to administratively bounce messages currently queued in the server with the following format:

kcli --endpoint http://127.0.0.1:8000 bounce --everything --reason purge
{
  "id": "0234c7c9-afd3-49f9-9a4c-a1cc37fcc53b",
  "bounced": {},
  "total_bounced": 0
}

Allowed arguments for the bounce command include:

domain

Optional string. The domain name to match. If omitted, any domain will match.

campaign

Optional string. The campaign name to match. If omitted, any campaign will match.

tenant

Optional string. The tenant to match. If omitted, any tenant will match.

!!! danger If you specify none of domain, campaign or tenant, then ALL queues will be bounced.

With great power, comes great responsibility!

reason

Required. Reason to log in the delivery log.

duration

Optional duration string. Defaults to "5m". Specifies how long this bounce directive remains active.

While active, newly injected messages that match the bounce criteria will also be bounced.

See the Bounce API page of the Reference Manual for more information.

Listing Current Bounces

You can list the currently active bounce commands with the following command:

kcli --endpoint http://127.0.0.1:8000 bounce-list
[
  {
    "id": "169c3dc0-6518-41ef-bfbb-1f0ae426cb32",
    "campaign": null,
    "tenant": null,
    "domain": null,
    "reason": "purge",
    "duration": "4m 50s 207ms 320us 231ns",
    "bounced": {
      "wezfurlong.org": 1
    },
    "total_bounced": 1
  }
]

See the Admin Bounce List API page of the Reference Manual for more information.

Removing a Bounce

Because bounce commands default to a five-minute duration, messages will continue to bounce after the command has been issued. This helps with scenarios such as when a campaign needs to be aborted, but the entire campaign may not have been injected at the time the command was issued.

Sometimes after a bounce has been issued there is a need to cancel the bounce before the time window has expired. Once a bounce command's ID is determined with the bounce-list command, the bounce can be canceled with the bounce-cancel command:

kcli --endpoint http://127.0.0.1:8000 bounce-cancel --id 169c3dc0-6518-41ef-bfbb-1f0ae426cb32
removed 0234c7c9-afd3-49f9-9a4c-a1cc37fcc53b

See the Bounce Cancel API page of the Reference Manual for more information.

Setting The Diagnostic Log Level

While the log level is typically set in your configuration, it can also be set on an ad-hoc basis using the set-log-filter command in kcli:

kcli --endpoint http://127.0.0.1:8000 set-log-filter 'kumod=trace'
OK

See the Set Diagnostic Log Filter page of the Reference Manual for more information.

3.6 KiB Raw Blame History