nngcat

nngcat is a command-line peer for Scalability Protocols. It is useful for testing services, building small shell-script integrations, demonstrating topologies, and inspecting messages without writing a custom program.

Every nngcat invocation has the same basic shape:

nngcat --PROTOCOL --dial URL [send-options] [receive-options]
nngcat --PROTOCOL --listen URL [send-options] [receive-options]

At least one protocol option and at least one peer address are required. The selected protocol determines whether the command sends messages, receives messages, or performs an exchange involving both.

Use nngcat --help for command-line help and nngcat --version to print the version.

Basic Examples

This starts a reply peer that always answers 42, then sends one request to it:

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

The requester prints both the request and reply:

"what is the answer?"
"42"

This publishes a message once per hour over IPC and receives it with a subscriber:

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

The subscriber prints:

"cuckoo"

Choosing a Protocol

Exactly one protocol family should be selected for a command.

nngcat does not support PAIR v1 polyamorous mode, although peers may use it.

Connecting and Listening

Use --dial or --connect to connect to a peer:

nngcat --req --dial tcp://127.0.0.1:4567 --data "status"

Use --listen or --bind to accept connections from peers:

nngcat --rep --listen tcp://127.0.0.1:4567 --data "ok"

Unlike the legacy nanocat tool, nngcat can use more than one peer address in a single invocation.

Shortcut options are available for common TCP and IPC addresses:

Sending Data

Protocols that send messages use --data or --file to choose the outgoing message body:

nngcat --push --dial tcp://127.0.0.1:9000 --data "hello"
nngcat --push --dial tcp://127.0.0.1:9000 --file payload.bin

If --file - is used, the message body is read from standard input.

For protocols that send unsolicited messages, such as PUB or PUSH, --interval repeats the outgoing message and --delay waits before sending the first message. A delay is often useful with PUB sockets because subscribers may need time to connect before the first message is sent.

nngcat --pub --listen tcp://127.0.0.1:9000 --data tick --delay 1 --interval 5

Use --send-timeout to give up if a send cannot complete within the requested number of seconds.

Receiving Data

Protocols that receive messages can format output in several ways:

The format can be selected with --format FORMAT or one of the convenience aliases:

For SUB sockets, use --subscribe TOPIC to receive only messages whose initial bytes match TOPIC. This option may be used more than once. If no subscription is supplied, nngcat subscribes to all messages.

Use --receive-timeout to stop waiting after the requested number of seconds, and --recv-maxsz to set the largest message size accepted by the socket. The default receive limit is 1 MiB. Use --recv-maxsz 0 to remove the limit.

TLS

TLS options are used only with TLS-secured addresses, such as tls+tcp:// URLs. They are ignored for non-TLS transports.

Use --cacert FILE to supply certificate authorities for peer validation. Use --cert FILE and --key FILE to present a local certificate and private key. If --cert is supplied without --key, the certificate file is expected to contain both the certificate and private key.

--insecure disables peer validation. This is useful for local testing with self-signed certificates, but it should not be used for production traffic.

Option Syntax

Long options start with --. If a long option takes a value, the value can be supplied with an equals sign, with a colon, or as the next argument:

nngcat --subscribe=times
nngcat --subscribe:tribune
nngcat --subscribe herald

Short options start with -. If a short option takes a value, the value can be attached to the option or supplied as the next argument:

nngcat -L5678
nngcat -L 5678

Long options may be abbreviated as long as the abbreviation is unambiguous. For example, --comp can be used instead of --compat, but --re is ambiguous because it could mean --req, --rep, or --respondent.

POSIX-style clustering of short options is not supported. Each short option must be supplied as a separate argument.

Option Reference

Generic Options

Protocol Selection Options

Peer Selection Options

Receive Options

Transmit Options

TLS Options