1NNGCAT(1) NNG Reference Manual NNGCAT(1)
2
6 nngcat - command line access to Scalability Protocols
7
9 nngcat --help
10 nngcat --version
12 nngcat [OPTION]...
14
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
22 The possible values for OPTION are described below.
23 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 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 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 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 Generic Options
47 -h, --help
48 Get usage help.
49 -V, --version
51 Print the version and exit.
52 -v, --verbose
54 Select verbose operation.
55 -q, --silent
57 Select silent operation.
58 --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 --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 --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 Protocol Selection Options
84 Note
85 At least one protocol must be selected.
86 --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 --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 --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 --pub, --pub0
100 Select the pub version 0 protocol. This protocol sends messages to
101 sub version peers.
102 --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 --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 --pull, --pull0
114 Select the pull version 0 protocol. This protocol receives messages
115 from push version 0 peers.
116 --pair0
118 Select the pair version 0 protocol. This protocol can send and
119 receive messages with one connected pair version 0 peer.
120 --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 --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 --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 --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 Peer Selection Options
142 Note
143 At least one peer address must be selected.
144 Tip
146 While legacy nanocat only supported one peer, nngcat can support
147 more than one peer on a given connection.
148 --connect, --dial=URL
150 Connect to the peer at the address specified by URL.
151 --bind, --listen=URL
153 Bind to, and accept connections from peers, at the address
154 specified by URL.
155 -x, --connect-ipc=PATH
157 Connect to the IPC path specified by PATH. This is the same as
158 --connect=ipc://PATH.
159 -X, --bind-ipc=PATH
161 Bind to the IPC path specified by PATH. This is the same as
162 --bind=ipc://PATH.
163 -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 -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 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 -A, --ascii
178 The same as specifying --format=ascii.
179 -Q, --quoted
181 The same as specifying --format=quoted.
182 --hex
184 The same as specifying --format=hex.
185 --msgpack
187 The same as specifying --format=msgpack.
188 --raw
190 The same as specifying --format=raw.
191 --receive-timeout=SEC
193 Give up receiving messages after SEC seconds pass without any
194 received messages.
195 --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 --format=FORMAT
202 Format data as indicated. The FORMAT can be any of:
203 no
205 No output at all.
206 raw
208 Raw output, every byte received is sent to standard output.
209 ascii
211 ASCII safe, printable ASCII is emitted verbatim, with other
212 bytes substituted with . (period).
213 quoted
215 Messages are printed as quoted strings, using C language
216 conventions.
217 hex
219 Messages are printed as quoted strings, with every byte
220 appearing as an escaped hexadecimal value, such as \x2E.
221 msgpack
223 Messages are emitted as MessagePack <https://msgpack.org> "bin
225 format" (byte arrays).
226 Transmit Options
228 Protocols that support sending data can use these options to select the
229 data.
230 -D, --data=DATA
232 Use DATA for the body of outgoing messages.
233 -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 -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 -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 --send-timeout=SEC
249 Give up trying to send a message after SEC seconds.
250 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 -k, --insecure
256 Skip peer validation.
257 -E, --cert=FILE
259 Load own certificate from FILE.
260 --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 --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 ZeroTier Options
273 These options are only present if ZeroTier is configured; they are
274 ignored otherwise.
275 --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
282 Echo service using request/reply.
283 $ 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 Send a chime every hour (3600 seconds).
291 $ addr=ipc:///grandpa_clock
293 $ nngcat --pub --listen=${addr} --data "cuckoo" --interval 3600 &
294 $ nngcat --sub --dial=${addr} --quoted &
295 "cuckoo"
296
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 2023-07-20 NNGCAT(1)