= nngcat(1)
|
//
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
//
|
// This document is supplied under the terms of the MIT License, a
|
// copy of which should be located in the distribution where this
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
// found online at https://opensource.org/licenses/MIT.
|
//
|
|
== 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. (((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 xref:nng_pair.7.adoc[_pair_] protocol instead of version 1.
|
|
*--subscribe*=_TOPIC_::
|
Subscribe to _TOPIC_. This option can only be used with the
|
xref:nng_sub.7.adoc[_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 xref:nng_bus.7.adoc[_bus_] version 0 protocol.
|
This protocol can send and receive messages to and from other _bus_ version 0
|
peers.
|
|
*--req, --req0*::
|
Select the xref:nng_req.7.adoc[_req_] version 0 protocol.
|
This protocol sends messages to xref:nng_rep.7.adoc[_rep_] version 0
|
peers and receives replies from them.
|
|
*--rep, --rep0*::
|
Select the xref:nng_rep.7.adoc[_rep_] version 0 protocol.
|
This protocol receives messages from xref:nng_req.7.adoc[_req_] version 0 peers
|
and can send replies to them.
|
|
*--pub, --pub0*::
|
Select the xref:nng_pub.7.adoc[_pub_] version 0 protocol.
|
This protocol sends messages to xref:nng_sub.7.adoc[_sub_] version peers.
|
|
*--sub, --sub0*::
|
Select the xref:nng_sub.7.adoc[_sub_] version 0 protocol.
|
This protocol receives messages from xref:nng_pub.7.adoc[_pub_] version
|
0 peers, and filters them based on subscriptions set with *--subscribe*.
|
|
*--push, --push0*::
|
Select the xref:nng_push.7.adoc[_push_] version 0 protocol.
|
This protocol sends messages to xref:nng_pull.7.adoc[_pull_] version 0 peers.
|
A given message is normally only delivered to a single peer.
|
|
*--pull, --pull0*::
|
Select the xref:nng_pull.7.adoc[_pull_] version 0 protocol.
|
This protocol receives
|
messages from xref:nng_push.7.adoc[_push_] version 0 peers.
|
|
*--pair0*::
|
Select the xref:nng_pair.7.adoc[_pair_] version 0 protocol.
|
This protocol can send and receive messages with one connected _pair_
|
version 0 peer.
|
|
*--pair1*::
|
Select the xref:nng_pair.7.adoc[_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 xref:nng_surveyor.7.adoc[_surveyor_] version 0 protocol.
|
This protocol sends a survey request to xref:nng_respondent.7.adoc[_respondent_]
|
version 0 peers, and then receives replies from them.
|
|
*--respondent, --respondent0*::
|
Select the xref:nng_respondent.7.adoc[_respondent_] version 0 protocol.
|
This protocol receives survey requests from xref:nng_surveyor.7.adoc[_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`::: (((hex))) Messages are printed as quoted strings, with every byte appearing as an escaped hexadecimal value, such as `\x2E`.
|
|
`msgpack`::: (((msgpack)))(((MessagePack)))
|
Messages are emitted as https://msgpack.org[MessagePack] "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.
|
[source,sh]
|
----
|
$ 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).
|
[source,sh]
|
----
|
$ addr=ipc:///grandpa_clock
|
$ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
|
$ nngcat --sub --dial=${addr} --quoted &
|
"cuckoo"
|
----
|
|
== SEE ALSO
|
|
[.text-left]
|
xref:libnng.3.adoc[libnng(3)],
|
xref:nng.7.adoc[nng(7)],
|
xref:nng_bus.7.adoc[nng_bus(7)],
|
xref:nng_pair.7.adoc[nng_pair(7)],
|
xref:nng_pub.7.adoc[nng_pub(7)],
|
xref:nng_pull.7.adoc[nng_pull(7)],
|
xref:nng_push.7.adoc[nng_push(7)],
|
xref:nng_sub.7.adoc[nng_sub(7)],
|
xref:nng_rep.7.adoc[nng_rep(7)],
|
xref:nng_req.7.adoc[nng_req(7)],
|
xref:nng_respondent.7.adoc[nng_respondent(7)],
|
xref:nng_surveyor.7.adoc[nng_surveyor(7)]
|
