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, nng can support more
147           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.
236
237       -i, --interval=SEC
238           For protocols that send unsolicited data (as opposed to those  that
239           send  data only in response to received messages), this will resend
240           the outgoing message at repeating intervals of SEC seconds.
241
242       -d, --delay=SEC
243           Wait SEC seconds before sending the first outgoing message. This is
244           useful  to  let  connections establish before sending data, thereby
245           avoiding message loss.
246
247       --send-timeout=SEC
248           Give up trying to send a message after SEC seconds.
249
250   TLS Options
251       These options are only present if TLS is configured; they  are  ignored
252       when using addresses that are not secured with TLS.
253
254       -k, --insecure
255           Skip peer validation.
256
257       -E, --cert=FILE
258           Load own certificate from FILE.
259
260       --key=FILE
261           Load  own key from FILE. Should be used in conjunction with --cert.
262           If not specified, and --cert  is  specified,  then  a  single  file
263           containing  both  the private key and the associated certificate is
264           assumed.
265
266       --cacert=FILE
267           Load  CA  certificates   from   FILE.   These   CAs   ("Certificate
268           Authorities")  are used as trust roots when validating certificates
269           presented by peers.
270
271   ZeroTier Options
272       These options are only present if  ZeroTier  is  configured;  they  are
273       ignored otherwise.
274
275       --zt-home=DIRECTORY
276           Directory  for  persistent  ZeroTier node (key material, etc.) This
277           directory must already exist. Only one program may use  a  ZeroTier
278           node at a time; file locking is used to prevent this.
279

EXAMPLES

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

SEE ALSO

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