1NNGCAT(1)                    NNG Reference Manual                    NNGCAT(1)
2
3
4

NAME

6       nngcat - command line access to Scalability Protocols
7

SYNOPSIS

9       nngcat --help
10
11       nngcat --version
12
13       nngcat [OPTION]...
14

DESCRIPTION

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

OPTIONS

22       The possible values for OPTION are described below.
23
24           Tip
25           The nngcat utility accepts shortened versions of these options, as
26           long as the supplied option is unambiguous. For example --comp can
27           be used in lieu of --compat, but --re may not be used for anything
28           because it could mean any of --req, --rep, or --respondent.
29
30       When using the long form of an option (names prefixed with with --), if
31       the option takes a value then the value may be supplied by appending
32       the option with an equals sign and the value (e.g. --subscribe=times),
33       by appending the option with a colon and the value (e.g.
34       --subscribe:tribune) or by providing the data as the next program
35       argument (e.g. --subscribe herald).
36
37       When using short form options (a single letter prefixed with a -), if
38       the option takes a value it may either be immediately appended to the
39       value (e.g. -L5678) or provided as the next program argument (e.g. -L
40       5678).
41
42       POSIX style option clustering of single letter options is not
43       supported; each option must be presented as a separate argument to the
44       program.
45
46   Generic Options
47       -h, --help
48           Get usage help.
49
50       -V, --version
51           Print the version and exit.
52
53       -v, --verbose
54           Select verbose operation.
55
56       -q, --silent
57           Select silent operation.
58
59       --compat
60           Compatible mode. This cause nngcat to behave more like the legacy
61           nanocat application. In this mode connections are made
62           asynchronously, and the --pair option selects version 0 of the pair
63           protocol instead of version 1.
64
65       --subscribe=TOPIC
66           Subscribe to TOPIC. This option can only be used with the sub
67           protocol. The TOPIC is checked against the first bytes of messages
68           received, and messages are discarded if they do not match. This may
69           be specified multiple times to subscribe to multiple topics. If not
70           specified at all, then a default subscription to everything is
71           assumed.
72
73       --count==COUNT
74           Limit the number of iterations when looping to COUNT iterations.
75           For protocols that only send, this will only send COUNT messages
76           before exiting. For protocols that only receive, this will only
77           receive COUNT messages before exiting. For protocols that involve a
78           full exchange, this will only perform COUNT exchanges (each
79           exchange is characterized by at most a single send, and one or more
80           receives.) If COUNT is zero, then an infinite number of iterations
81           is performed.
82
83   Protocol Selection Options
84           Note
85           At least one protocol must be selected.
86
87       --bus, --bus0
88           Select the bus version 0 protocol. This protocol can send and
89           receive messages to and from other bus version 0 peers.
90
91       --req, --req0
92           Select the req version 0 protocol. This protocol sends messages to
93           rep version 0 peers and receives replies from them.
94
95       --rep, --rep0
96           Select the rep version 0 protocol. This protocol receives messages
97           from req version 0 peers and can send replies to them.
98
99       --pub, --pub0
100           Select the pub version 0 protocol. This protocol sends messages to
101           sub version peers.
102
103       --sub, --sub0
104           Select the sub version 0 protocol. This protocol receives messages
105           from pub version 0 peers, and filters them based on subscriptions
106           set with --subscribe.
107
108       --push, --push0
109           Select the push version 0 protocol. This protocol sends messages to
110           pull version 0 peers. A given message is normally only delivered to
111           a single peer.
112
113       --pull, --pull0
114           Select the pull version 0 protocol. This protocol receives messages
115           from push version 0 peers.
116
117       --pair0
118           Select the pair version 0 protocol. This protocol can send and
119           receive messages with one connected pair version 0 peer.
120
121       --pair1
122           Select the pair version 1 protocol. This protocol can send and
123           receive messages with one connected pair version 1 peer. It is not
124           supported in --compat mode. (Polyamorous mode is not supported in
125           nngcat, although peers may be using polyamorous mode.)
126
127       --pair
128           Acts as an alias for --pair1, unless --compat mode is selected, in
129           which case it acts as an alias for --pair0.
130
131       --surveyor, --surveyor0
132           Select the surveyor version 0 protocol. This protocol sends a
133           survey request to respondent version 0 peers, and then receives
134           replies from them.
135
136       --respondent, --respondent0
137           Select the respondent version 0 protocol. This protocol receives
138           survey requests from surveyor version 0 peers, and can send a reply
139           to them.
140
141   Peer Selection Options
142           Note
143           At least one peer address must be selected.
144
145           Tip
146           While legacy nanocat only supported one peer, nngcat can support
147           more than one peer on a given connection.
148
149       --connect, --dial=URL
150           Connect to the peer at the address specified by URL.
151
152       --bind, --listen=URL
153           Bind to, and accept connections from peers, at the address
154           specified by URL.
155
156       -x, --connect-ipc=PATH
157           Connect to the IPC path specified by PATH. This is the same as
158           --connect=ipc://PATH.
159
160       -X, --bind-ipc=PATH
161           Bind to the IPC path specified by PATH. This is the same as
162           --bind=ipc://PATH.
163
164       -l, --connect-local=PORT
165           Connect to localhost at the TCP port specified by PORT. This is the
166           same as --connect=tcp://127.0.0.1:PORT.
167
168       -L, --bind-local=PORT
169           Bind to the TCP port specified by PORT. This is the same as
170           --bind=tcp://127.0.0.1:PORT.
171
172   Receive Options
173       Data messages received can be formatted in different ways. These
174       options can only be specified when using a protocol that receives
175       messages.
176
177       -A, --ascii
178           The same as specifying --format=ascii.
179
180       -Q, --quoted
181           The same as specifying --format=quoted.
182
183       --hex
184           The same as specifying --format=hex.
185
186       --msgpack
187           The same as specifying --format=msgpack.
188
189       --raw
190           The same as specifying --format=raw.
191
192       --receive-timeout=SEC
193           Give up receiving messages after SEC seconds pass without any
194           received messages.
195
196       --recv-maxsz=COUNT
197           Set the maximum message size socket will accept to COUNT bytes.
198           Messages larger than this will be discarded. The default is 1048576
199           (1 MB). To eliminate any restriction, use 0.
200
201       --format=FORMAT
202           Format data as indicated. The FORMAT can be any of:
203
204           no
205               No output at all.
206
207           raw
208               Raw output, every byte received is sent to standard output.
209
210           ascii
211               ASCII safe, printable ASCII is emitted verbatim, with other
212               bytes substituted with . (period).
213
214           quoted
215               Messages are printed as quoted strings, using C language
216               conventions.
217
218           hex
219                Messages are printed as quoted strings, with every byte
220               appearing as an escaped hexadecimal value, such as \x2E.
221
222           msgpack
223
224               Messages are emitted as MessagePack <https://msgpack.org> "bin
225               format" (byte arrays).
226
227   Transmit Options
228       Protocols that support sending data can use these options to select the
229       data.
230
231       -D, --data=DATA
232           Use DATA for the body of outgoing messages.
233
234       -F, --file=FILE
235           Use FILE for the body of outgoing messages. If FILE is - the
236           message body will be read from standard input.
237
238       -i, --interval=SEC
239           For protocols that send unsolicited data (as opposed to those that
240           send data only in response to received messages), this will resend
241           the outgoing message at repeating intervals of SEC seconds.
242
243       -d, --delay=SEC
244           Wait SEC seconds before sending the first outgoing message. This is
245           useful to let connections establish before sending data, thereby
246           avoiding message loss.
247
248       --send-timeout=SEC
249           Give up trying to send a message after SEC seconds.
250
251   TLS Options
252       These options are only present if TLS is configured; they are ignored
253       when using addresses that are not secured with TLS.
254
255       -k, --insecure
256           Skip peer validation.
257
258       -E, --cert=FILE
259           Load own certificate from FILE.
260
261       --key=FILE
262           Load own key from FILE. Should be used in conjunction with --cert.
263           If not specified, and --cert is specified, then a single file
264           containing both the private key and the associated certificate is
265           assumed.
266
267       --cacert=FILE
268           Load CA certificates from FILE. These CAs ("Certificate
269           Authorities") are used as trust roots when validating certificates
270           presented by peers.
271
272   ZeroTier Options
273       These options are only present if ZeroTier is configured; they are
274       ignored otherwise.
275
276       --zt-home=DIRECTORY
277           Directory for persistent ZeroTier node (key material, etc.) This
278           directory must already exist. Only one program may use a ZeroTier
279           node at a time; file locking is used to prevent this.
280

EXAMPLES

282       Echo service using request/reply.
283
284           $ addr="tcp://127.0.0.1:4567"
285           $ nngcat --rep --listen=${addr} --data="42" --quoted &
286           $ nngcat --req --dial=${addr} --data="what is the answer?" --quoted
287           "what is the answer?"
288           "42"
289
290       Send a chime every hour (3600 seconds).
291
292           $ addr=ipc:///grandpa_clock
293           $ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
294           $ nngcat --sub --dial=${addr} --quoted &
295           "cuckoo"
296

SEE ALSO

298       libnng(3), nng(7), nng_bus(7), nng_pair(7), nng_pub(7), nng_pull(7),
299       nng_push(7), nng_sub(7), nng_rep(7), nng_req(7), nng_respondent(7),
300       nng_surveyor(7)
301
302
303
304                                  2023-07-20                         NNGCAT(1)
Impressum