STOMPCLT(1)

📦 version 1.6, in epel 9

💅 STOMPCLT 💅

okay so you're looking at stompclt(1) — that's the manpage from User Contributed Perl Documentation, bestie, and it's literally the versatile STOMP client. buckle up 🎀

✨ NAME ✨

stompclt — versatile STOMP client. that's it, that's the whole vibe. iconic.

🌸 SYNOPSIS 🌸

stompclt [OPTIONS]

🦋 DESCRIPTION 🦋

stompclt is a versatile tool to interact with messaging brokers speaking STOMP and/or message queues (see Messaging::Message::Queue) on disk. no cap, it does both 💖

here's the tea: it receives messages (see Messaging::Message) from an incoming module, optionally massages them (i.e. filtering and/or modifying — yes bestie, it's giving spa day for your messages 💅), and sends them to an outgoing module. depending on which modules are used, the tool can perform different operations.

here are the supported incoming modules:

broker — connect to a messaging broker using STOMP, subscribe to one or more destinations and receive the messages sent by the broker 🐝
queue — read messages from a message queue on disk

and here are the supported outgoing modules:

broker — connect to a messaging broker using STOMP and send the messages
queue — store the messages in a message queue on disk

here are some frequently used combinations (the classic ships, iykyk):

incoming broker + outgoing queue — drain some destinations, storing the messages on disk 🌊
incoming queue + outgoing broker — (re-)send messages that have been previously stored on disk, optionally with modifications (such as altering the destination) 🔁
incoming broker + outgoing broker — shovel messages from one broker to another 🚜

see the EXAMPLES sections for concrete examples — they're literally in part 2, stay tuned ✨

👑 OPTIONS 👑

--callback-code CODE — execute the given Perl code on each message, see the CALLBACK section below for more information 🧚
--callback-data KEY=VALUE... — pass this data to the user supplied callback code, see the CALLBACK section below for more information
--callback-path PATH — execute the Perl code in the given file on each message, see the CALLBACK section below for more information
--config, --conf, --cfg PATH — use the given configuration file, see the CONFIGURATION FILE section below for more information. three names, one icon 💅
--config-general KEY=VALUE... — use the given Config::General options when creating the configuration parser
--count, -c INTEGER — process at most the given number of messages; note: when using an incoming broker, to avoid consuming more messages, it is recommended to enable the --reliable option ⚠️ (fr fr, heed the note)
--daemon | --no-daemon — detach stompclt so that it becomes a daemon running in the background; debug, warning and error messages will get sent to syslog; this option can be negated 👻
--debug, -d — show debugging information 🐛
--duration SECONDS — process messages during at most the given number of seconds and then stop; can be fractional ⏱️
--heart-beat | --no-heart-beat — enable STOMP 1.1 heart-beats between stompclt and the broker(s); this option can be negated 💓
--help, -h, -? — show some help 🫶
--incoming-broker-auth STRING — use this authentication string (see Authen::Credential) to authenticate to the incoming broker; this option can be given multiple times 🔐
--incoming-broker-connect KEY=VALUE... — use these options in the STOMP CONNECT frame sent to the incoming broker
--incoming-broker-sockopts KEY=VALUE... — use these socket options when connecting to the incoming broker 🧦
--incoming-broker-stomp-debug STRING — set the STOMP debug flags (see Net::STOMP::Client) when interacting with the incoming broker
--incoming-broker-type STRING — set the incoming broker type; this can be useful when using STOMP features which are broker specific
--incoming-broker-uri URI — use this connection URI (see Net::STOMP::Client) to connect to the incoming broker 🔗
--incoming-queue KEY=VALUE... — read incoming messages from the given message queue (see Messaging::Message::Queue)
--lazy | --no-lazy — initialize the outgoing module only after having received the first message; this option can be negated 😴
--list, -l — show all supported options 📋
--loop | --no-loop — when using an incoming message queue, loop over it; this option can be negated 🔄
--manual, -m — show this manual 📖
--outgoing-broker-auth STRING — use this authentication string (see Authen::Credential) to authenticate to the outgoing broker; this option can be given multiple times
--outgoing-broker-connect KEY=VALUE... — use these options in the STOMP CONNECT frame sent to the outgoing broker
--outgoing-broker-sockopts KEY=VALUE... — use these socket options when connecting to the outgoing broker
--outgoing-broker-stomp-debug STRING — set the STOMP debug flags (see Net::STOMP::Client) when interacting with the outgoing broker
--outgoing-broker-type STRING — set the outgoing broker type; this can be useful when using STOMP features which are broker specific
--outgoing-broker-uri URI — use this connection URI (see Net::STOMP::Client) to connect to the outgoing broker
--outgoing-queue KEY=VALUE... — store outgoing messages into the given message queue (see Messaging::Message::Queue)
--pidfile PATH — use this pid file 🗂️
--prefetch INTEGER — set the prefetch value (i.e. the maximum number of messages to received without acknowledging them) on the incoming broker
--quit — tell another instance of stompclt (identified by its pid file, as specified by the --pidfile option) to quit ✌️
--reliable | --no-reliable — use STOMP features for more reliable messaging (i.e. client side acknowledgments and receipts) at the cost of less performance; this option can be negated ⚖️
--remove | --no-remove — when using an incoming message queue, remove the processed messages; this option can be negated 🗑️
--statistics, -s | --no-statistics — report statistics at the end of the execution; this option can be negated 📊
--status — get the status of another instance of stompclt (identified by its pid file, as specified by the --pidfile option); the exit code will be zero if the instance is alive and non-zero otherwise 🩺
--subscribe KEY=VALUE... — use these options in the STOMP SUBSCRIBE frame used with the incoming broker; this option can be given multiple times 📬
--timeout-broker SECONDS — use this timeout when interacting with the broker (e.g. getting receipts back); can be fractional ⏳
--timeout-client SECONDS — use this timeout for the client heart-beat; can be fractional (default: 40)
--timeout-connect SECONDS — use this timeout when connecting to the broker; can be fractional
--timeout-disconnect SECONDS — use this timeout when disconnecting from the broker; can be fractional (default: 60)
--timeout-flush SECONDS — use this timeout when attempting to send the last bytes to the broker just before disconnecting; can be fractional (default: 60) 🚿
--timeout-inactivity SECONDS — use this timeout in the incoming module to stop stompclt when no new messages have been received (aka drain mode); can be fractional
--timeout-linger SECONDS — when stopping stompclt, use this timeout to finish interacting with the broker; can be fractional
--timeout-server SECONDS — use this timeout for the server heart-beat; can be fractional (default: 10)
--timeout-status SECONDS — use this timeout when checking the status with --status; can be fractional
--unsubscribe KEY=VALUE... — use these options in the STOMP UNSUBSCRIBE frame used with the incoming broker; this option can be given multiple times and should match the --subscribe options 👋
--version — display version information
--window INTEGER — keep at most the given number of not-yet-acknowledged messages in memory 🪟

to list all the available options in a compact form, type:

$ stompclt -l

🎀 CONFIGURATION FILE 🎀

stompclt can read its options from a configuration file. for this, the Config::General module is used and the option names are the same as on the command line. for instance:

daemon = true
pidfile = /var/run/stompclt.pid
incoming-queue = path=/var/spool/stompclt
outgoing-broker-uri = stomp://broker.acme.com:6163
outgoing-broker-auth = "plain name=guest pass=guest"

alternatively, options can be nested (aesthetic ✨):

<outgoing-broker>
    uri = stomp://broker.acme.com:6163
    auth = "plain name=guest pass=guest"
</outgoing-broker>

or even:

<outgoing>
    <broker>
        uri = stomp://broker.acme.com:6163
        <auth>
            scheme = plain
            name = guest
            pass = guest
        </auth>
    </broker>
</outgoing>

and the rule you gotta remember: the options specified on the command line have precedence over the ones found in the configuration file. command line stays the main character 👑

💖 CALLBACK 💖

okay so bestie, stompclt can be handed actual Perl code to run on every single message it processes. iconic, right? This is your little backstage pass, and it can be used for different purposes:

massaging: the code can change any part of the message, including setting or removing header fields
filtering: the code can decide if the message must be given to the outgoing module or not
displaying: the code can print any part of the message
copying: the code can store a copy of the message into files or message queues

To use callbacks, you gotta use the --callback-path or --callback-code option. The Perl code must provide functions with the following signature:

start(DATA) — (optional) this gets called when the program starts, with the supplied data (see the --callback-data option) as a hash reference
check(MESSAGE) — (mandatory) this gets called when the program has one message to process; it gets the message (see Messaging::Message) and must return either a message (it could be the same one or a new one) or a string describing why the message has been dropped
idle() — (optional) this gets called when the program has no message to process
stop() — (optional) this gets called when the program stops

The code can be put in a file, on the command line or in the stompclt configuration file, using the "here document" syntax.

Here is an example (to be put in the stompclt configuration file) that prints on stdout a JSON array of messages:

callback-code = <<EOF
    my($count);
    sub start ($) {
        $count = 0;
    }
    sub check ($) {
        my($msg) = @_;
        print($count++ ? "," : "[");
        print($msg->serialize(), "\n");
        return($msg);
    }
    sub stop () {
        print($count ? "]\n" : "[]\n");
    }
EOF

For simple callback code that only needs the check subroutine, it is enough to supply the "inside code". If the subroutine definition is missing, the supplied code will be wrapped with:

sub check ($) {
    my($msg) = @_;
    local *hdr = $msg->header();
    local *bdy = $msg->body_ref();
    ... your code goes here ...
    return($msg);
}

This allows for instance to remove the message-id header with something like:

$ stompclt ... --callback-code 'delete($hdr{"message-id"})'

Or to filter on message bodies with:

$ stompclt ... --callback-code 'return("skip") unless $bdy =~ /error/'

🦋 SUBSCRIPTIONS 🦋

In the case of an incoming broker, stompclt deals with the subscriptions defined by the --subscribe option. slay.

Regardless of the --reliable option, subscriptions are always made using receipts. Also, if missing, an id header is always added.

Here is for instance how to create a named durable topic subscription using Apollo:

$ stompclt ... --subscribe 'destination=/topic/foo persistent=true id=mysub'

By default, when it finishes, stompclt does not unsubscribe. It simply disconnects from the broker and the latter will perform the necessary cleanup when terminating the STOMP connection. no cap, that's the default vibe.

If the --unsubscribe option is given, even if it is empty, stompclt will explicitly unsubscribe before disconnecting, also using receipts.

Here is for instance how to destroy, when stompclt ends, the durable topic subscription created above:

$ stompclt ... --unsubscribe 'persistent=true'

There is no need to give the subscription id in the --unsubscribe option because, by default, it comes from the matching --subscribe option. it just knows, bestie ✨

🎀 UDP SUPPORT 🎀

stompclt has experimental UDP support (outgoing only). This has been tested with Apollo.

To use it, simply specify an outgoing URI that uses UDP such as:

$ stompclt ... --outgoing-broker-uri udp://broker.acme.com:6163

Features such as authentication, heart beating, reliability and socket options are not supported over UDP. so don't expect the whole menu over UDP, okay? 💀

🌈 EXAMPLES 🌈

🚀 SENDING 🚀

Here is an example of a configuration file for a message sender daemon (from queue to broker), forcing the persistent header to true (something which is highly recommended for reliable messaging) and setting the destination:

# define the source message queue
<incoming-queue>
    path = /var/spool/sender
</incoming-queue>
# modify the message header on the fly
callback-code = <<EOF
    $hdr{destination} = "/queue/app1.data";
    $hdr{persistent} = "true";
EOF
# define the destination broker
<outgoing-broker>
    uri = "stomp://broker.acme.com:6163"
</outgoing-broker>
# miscellaneous options
reliable = true
pidfile = /var/run/sender.pid
daemon = true
loop = true
remove = true

🍓 RECEIVING 🍓

Here is an example of a configuration file for a message receiver daemon (from broker to queue):

# define the source broker
<incoming-broker>
    uri = "stomp://broker.acme.com:6163"
    <auth>
        scheme = plain
        name = receiver
        pass = secret
    </auth>
</incoming-broker>
# define the subscriptions
<subscribe>
    destination = /queue/app1.data
</subscribe>
<subscribe>
    destination = /queue/app2.data
</subscribe>
# define the destination message queue
<outgoing-queue>
    path = /var/spool/receiver
</outgoing-queue>
# miscellaneous options
pidfile = /var/run/receiver.pid
daemon = true

Here is how to use the configuration file above with some options overridden on the command line to drain the queues in the foreground:

$ stompclt --config test.conf --no-daemon --timeout-inactivity 10

🧚 SHOVELING 🧚

Here is an example of a configuration file for a message shoveler (from broker to broker), clearing some headers on the fly so that messages can be replayed safely:

# define the source broker
<incoming-broker>
    uri = "stomp://broker.acme.com:6163"
</incoming-broker>
# define the subscriptions
<subscribe>
    destination = /queue/app1.data
</subscribe>
<subscribe>
    destination = /queue/app2.data
</subscribe>
# define the destination broker
<outgoing-broker>
    uri = "stomp://dev-broker.acme.com:6163"
</outgoing-broker>
# modify the message so that it can be replayed
callback-code = <<EOF
    foreach my $name (qw(message-id timestamp expires)) {
        delete($hdr{$name});
    }
EOF

👑 TAPPING 👑

Callback code can also be used to tap messages, i.e. get a copy of all messages processed by stompclt. Here is some callback code for this purpose that could for instance be merged with the shoveling code above. It also shows how to use the --callback-data option:

callback-code = <<EOF
    my($queue);
    sub start ($) {
        my($data) = @_;
        $queue = Messaging::Message::Queue->new($data);
    }
    sub check ($) {
        my($msg) = @_;
        $queue->add_message($msg);
        return($msg);
    }
EOF

Callback data must be given to specify which message queue to use:

$ stompclt --config tap.conf --callback-data "path=/tmp/tap type=DQS"

💜 SEE ALSO 💜

Authen::Credential, Config::General, Messaging::Message, Messaging::Message::Queue, Net::STOMP::Client.

🌸 AUTHOR 🌸

Lionel Cons <http://cern.ch/lionel.cons>

and that's the whole vibe, bestie 💅✨ this page is STOMPCLT(1), from perl v5.32.1, dated 2019-07-27 — iconic manual-page energy, no cap 🫶

📦 where this page comes from

epel 9: stompclt 1.6-3.el9 · GPL+ or Artistic
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms