mirror of
https://github.com/mailscope/kumomta.git
synced 2026-09-09 12:02:14 +00:00
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# 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](../configuration/httplisteners.md) to function.
|
|
|
|
At minimum, the `kcli` client must be passed an endpoint and a command:
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
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](../../reference/http/api_admin_bounce_v1.md) page of the Reference Manual for more information.
|
|
|
|
## Listing Current Bounces
|
|
|
|
You can list the currently active bounce commands with the following command:
|
|
|
|
```console
|
|
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](../../reference/http/api_admin_bounce_list_v1.md) 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:
|
|
|
|
```console
|
|
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](../../reference/http/api_admin_bounce_cancel_v1.md) 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`:
|
|
|
|
```console
|
|
kcli --endpoint http://127.0.0.1:8000 set-log-filter 'kumod=trace'
|
|
OK
|
|
```
|
|
|
|
See the [Set Diagnostic Log Filter](../../reference/kumo/set_diagnostic_log_filter.md) page of the Reference Manual for more information. |