Wez Furlong
7f4a929ca2
This commit implements a kumomta-specific message transfer protocol that is intended to be used to migrate messages from one kumomta node to another. The transfer is carried out using an HTTP POST request to the destination node's http listener. The request includes the full message metadata and body, in a compressed form. An xfer request can be made via `kcli xfer` (and thus also via an HTTP API endpoint). It works similarly to a rebind operation; you specify the criteria to be used to match scheduled queues, along with the target node for the xfer, and kumomta will find matching queues, drain out the messages, make an adjustment to the metadata to capture current scheduling information, and then place the messages into an xfer queue. The xfer queue has hard-coded scheduling queue configuration of its own, with the base retry interval set to 10 seconds, which should be suitably aggressive for the intended use case. You may apply shaping to affect the number of concurrent requests in a similar way to how TSA shaping is configured. On the receiving side, the incoming xfer sanity check to prohibit trying to xfer to itself. The spool id of the Message is not suitable to be reused verbatim on another node (spool ids include the local mac address and creation timestamp information, as well as a random component), so the receiving side will derive an id that should be suitable for use on that node. The originating node id and spool id will be preserved in metadata to aid in tracing. It is possible for an xfer request to target an existing xfer queue, so that you can correct/update the target in various circumstances. In that situation the messages will be "simply" moved from the source queue to the destination queue. It is possible to cancel an xfer request via `kcli xfer-cancel` (and thus also via an HTTP API endpoint). You specify the target queue, which must be an xfer queue, and it will have its messages drained and the metadata changes that were applied when the xfer was initiated will be reversed, allowing the messages to then be reinserted into their originating queue. refs: https://github.com/KumoCorp/kumomta/issues/311
2.6 KiB
Command-Line Help for kcli
This document contains the help content for the kcli command-line program.
kcli
KumoMTA CLI.
Interacts with a KumoMTA instance via its HTTP API endpoint. To use it, you must be running an HTTP listener.
The default is to assume that KumoMTA is running a listener at http://127.0.0.1:8000 (which is in the default configuration), but otherwise you can override this either via the --endpoint parameter or KUMO_KCLI_ENDPOINT environment variable.
Full docs available at: https://docs.kumomta.com
Usage: kcli [OPTIONS] <COMMAND>
Subcommands:
-
bounce— Administratively bounce messages in matching queues -
bounce-list— Returns list of current administrative bounce rules -
bounce-cancel— Cancels an admin bounce entry -
rebind— Rebind messages from matching queues into different queue(s) -
suspend— Administratively suspend messages in matching queues -
suspend-list— Returns list of current administrative suspend rules -
suspend-cancel— Cancels an admin suspend entry -
suspend-ready-q— Administratively suspend the ready queue for an egress path -
suspend-ready-q-list— Returns list of current ready queue/egress path suspend rules -
suspend-ready-q-cancel— Cancels an admin suspend entry for a ready queue/egress path -
set-log-filter— Changes the diagnostic log filter -
inspect-message— Returns information about a message in the spool -
inspect-sched-q— Returns information about a scheduled queue -
provider-summary— Prints a summary of the aggregate state of the queues from the perspective of the provider or destination site -
queue-summary— Prints a summary of the state of the queues, for a human to read -
trace-smtp-client— Trace outgoing sessions made by the SMTP service -
trace-smtp-server— Trace incoming connections made to the SMTP service -
top— Continually update and show what's happening in kumod -
xfer— Transfer messages from matching queues to an alternative kumomta node -
xfer-cancel— Cancels a message transfer that was initiated via the xfer subcommand. You specify the name of the xfer queue associated with the transfer and matching messages will be taken out of that queue and returned to their originating queue
Options
--endpoint <ENDPOINT>— URL to reach the KumoMTA HTTP API. You may set KUMO_KCLI_ENDPOINT in the environment to specify this without explicitly using --endpoint. If not specified, http://127.0.0.1:8000 will be assumed