NAME

       nngcat - command line access to Scalability Protocols

SYNOPSIS

       nngcat --help

       nngcat --version

       nngcat [OPTION]...

DESCRIPTION

       The nngcat utility provides command line access to the Scalability Protocols, making it
       possible to write shell scripts that interact with other peers in a Scalability Protocols
       topology, by both sending and receiving messages.

OPTIONS

       The possible values for OPTION are described below.

           Tip
           The nngcat utility accepts shortened versions of these options, as long as the
           supplied option is unambiguous. For example --comp can be used in lieu of --compat,
           but --re may not be used for anything because it could mean any of --req, --rep, or
           --respondent.

       When using the long form of an option (names prefixed with with --), if the option takes a
       value then the value may be supplied by appending the option with an equals sign and the
       value (e.g. --subscribe=times), by appending the option with a colon and the value (e.g.
       --subscribe:tribune) or by providing the data as the next program argument (e.g.
       --subscribe herald).

       When using short form options (a single letter prefixed with a -), if the option takes a
       value it may either be immediately appended to the value (e.g. -L5678) or provided as the
       next program argument (e.g. -L 5678).

       POSIX style option clustering of single letter options is not supported; each option must
       be presented as a separate argument to the program.

   Generic Options
       -h, --help
           Get usage help.

       -V, --version
           Print the version and exit.

       -v, --verbose
           Select verbose operation.

       -q, --silent
           Select silent operation.

       --compat
           Compatible mode. This cause nngcat to behave more like the legacy nanocat application.
           In this mode connections are made asynchronously, and the --pair option selects
           version 0 of the pair protocol instead of version 1.

       --subscribe=TOPIC
           Subscribe to TOPIC. This option can only be used with the sub protocol. The TOPIC is
           checked against the first bytes of messages received, and messages are discarded if
           they do not match. This may be specified multiple times to subscribe to multiple
           topics. If not specified at all, then a default subscription to everything is assumed.

       --count==COUNT
           Limit the number of iterations when looping to COUNT iterations. For protocols that
           only send, this will only send COUNT messages before exiting. For protocols that only
           receive, this will only receive COUNT messages before exiting. For protocols that
           involve a full exchange, this will only perform COUNT exchanges (each exchange is
           characterized by at most a single send, and one or more receives.) If COUNT is zero,
           then an infinite number of iterations is performed.

   Protocol Selection Options
           Note
           At least one protocol must be selected.

       --bus, --bus0
           Select the bus version 0 protocol. This protocol can send and receive messages to and
           from other bus version 0 peers.

       --req, --req0
           Select the req version 0 protocol. This protocol sends messages to rep version 0 peers
           and receives replies from them.

       --rep, --rep0
           Select the rep version 0 protocol. This protocol receives messages from req version 0
           peers and can send replies to them.

       --pub, --pub0
           Select the pub version 0 protocol. This protocol sends messages to sub version peers.

       --sub, --sub0
           Select the sub version 0 protocol. This protocol receives messages from pub version 0
           peers, and filters them based on subscriptions set with --subscribe.

       --push, --push0
           Select the push version 0 protocol. This protocol sends messages to pull version 0
           peers. A given message is normally only delivered to a single peer.

       --pull, --pull0
           Select the pull version 0 protocol. This protocol receives messages from push version
           0 peers.

       --pair0
           Select the pair version 0 protocol. This protocol can send and receive messages with
           one connected pair version 0 peer.

       --pair1
           Select the pair version 1 protocol. This protocol can send and receive messages with
           one connected pair version 1 peer. It is not supported in --compat mode. (Polyamorous
           mode is not supported in nngcat, although peers may be using polyamorous mode.)

       --pair
           Acts as an alias for --pair1, unless --compat mode is selected, in which case it acts
           as an alias for --pair0.

       --surveyor, --surveyor0
           Select the surveyor version 0 protocol. This protocol sends a survey request to
           respondent version 0 peers, and then receives replies from them.

       --respondent, --respondent0
           Select the respondent version 0 protocol. This protocol receives survey requests from
           surveyor version 0 peers, and can send a reply to them.

   Peer Selection Options
           Note
           At least one peer address must be selected.

           Tip
           While legacy nanocat only supported one peer, nngcat can support more than one peer on
           a given connection.

       --connect, --dial=URL
           Connect to the peer at the address specified by URL.

       --bind, --listen=URL
           Bind to, and accept connections from peers, at the address specified by URL.

       -x, --connect-ipc=PATH
           Connect to the IPC path specified by PATH. This is the same as --connect=ipc://PATH.

       -X, --bind-ipc=PATH
           Bind to the IPC path specified by PATH. This is the same as --bind=ipc://PATH.

       -l, --connect-local=PORT
           Connect to localhost at the TCP port specified by PORT. This is the same as
           --connect=tcp://127.0.0.1:PORT.

       -L, --bind-local=PORT
           Bind to the TCP port specified by PORT. This is the same as
           --bind=tcp://127.0.0.1:PORT.

   Receive Options
       Data messages received can be formatted in different ways. These options can only be
       specified when using a protocol that receives messages.

       -A, --ascii
           The same as specifying --format=ascii.

       -Q, --quoted
           The same as specifying --format=quoted.

       --hex
           The same as specifying --format=hex.

       --msgpack
           The same as specifying --format=msgpack.

       --raw
           The same as specifying --format=raw.

       --receive-timeout=SEC
           Give up receiving messages after SEC seconds pass without any received messages.

       --recv-maxsz=COUNT
           Set the maximum message size socket will accept to COUNT bytes. Messages larger than
           this will be discarded. The default is 1048576 (1 MB). To eliminate any restriction,
           use 0.

       --format=FORMAT
           Format data as indicated. The FORMAT can be any of:

           no
               No output at all.

           raw
               Raw output, every byte received is sent to standard output.

           ascii
               ASCII safe, printable ASCII is emitted verbatim, with other bytes substituted with
               . (period).

           quoted
               Messages are printed as quoted strings, using C language conventions.

           hex
                Messages are printed as quoted strings, with every byte appearing as an escaped
               hexadecimal value, such as \x2E.

           msgpack

               Messages are emitted as MessagePack <https://msgpack.org> "bin format" (byte
               arrays).

   Transmit Options
       Protocols that support sending data can use these options to select the data.

       -D, --data=DATA
           Use DATA for the body of outgoing messages.

       -F, --file=FILE
           Use FILE for the body of outgoing messages. If FILE is - the message body will be read
           from standard input.

       -i, --interval=SEC
           For protocols that send unsolicited data (as opposed to those that send data only in
           response to received messages), this will resend the outgoing message at repeating
           intervals of SEC seconds.

       -d, --delay=SEC
           Wait SEC seconds before sending the first outgoing message. This is useful to let
           connections establish before sending data, thereby avoiding message loss.

       --send-timeout=SEC
           Give up trying to send a message after SEC seconds.

   TLS Options
       These options are only present if TLS is configured; they are ignored when using addresses
       that are not secured with TLS.

       -k, --insecure
           Skip peer validation.

       -E, --cert=FILE
           Load own certificate from FILE.

       --key=FILE
           Load own key from FILE. Should be used in conjunction with --cert. If not specified,
           and --cert is specified, then a single file containing both the private key and the
           associated certificate is assumed.

       --cacert=FILE
           Load CA certificates from FILE. These CAs ("Certificate Authorities") are used as
           trust roots when validating certificates presented by peers.

   ZeroTier Options
       These options are only present if ZeroTier is configured; they are ignored otherwise.

       --zt-home=DIRECTORY
           Directory for persistent ZeroTier node (key material, etc.) This directory must
           already exist. Only one program may use a ZeroTier node at a time; file locking is
           used to prevent this.

EXAMPLES

       Echo service using request/reply.

           $ addr="tcp://127.0.0.1:4567"
           $ nngcat --rep --listen=${addr} --data="42" --quoted &
           $ nngcat --req --dial=${addr} --data="what is the answer?" --quoted
           "what is the answer?"
           "42"

       Send a chime every hour (3600 seconds).

           $ addr=ipc:///grandpa_clock
           $ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
           $ nngcat --sub --dial=${addr} --quoted &
           "cuckoo"

SEE ALSO

       libnng(3), nng(7), nng_bus(7), nng_pair(7), nng_pub(7), nng_pull(7), nng_push(7),
       nng_sub(7), nng_rep(7), nng_req(7), nng_respondent(7), nng_surveyor(7)

                                            2024-10-11                                  NNGCAT(1)