1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
= 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 Scalabity Protocols
== SYNOPSIS
*nngcat* --help
*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 following options may be supplied for _OPTION_.
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`.
Options that take values may be separated from their value either by an
equa
=== Generic
*-h, --help*::
Get usage help.
*-v, --verbose*::
Select verbose operation.
*-q, --silent*::
Select silent operation.
*--compat*::
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 <<nng_pair#,PAIR>> protocol
instead of version 1.
*--subscribe*=_TOPIC_::
Subscribe to _TOPIC_. This option can only be used with the
<<nng_sub#,SUBv0>> 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.
=== Protocol Selection
NOTE: At least one protocol must be selected.
*--bus, --bus0*::
Select the <<nng_bus#,BUSv0>> protocol. This protocol can send
and receive messages to and from other <<nng_bus#,BUSv0>> peers.
*--req, --req0*::
Select the <<nng_req#,REQv0>> protocol. This protocol sends
messages to <<nng_rep#,REPv0>> peers and receives replies from them.
*--rep, --rep0*::
Select the <<nng_rep#,REPv0>> protocol. This protocol receives
messages from <<nng_req#,REQv0>> peers and can send replies to them.
*--pub, --pub0*::
Select the <<nng_pub#,PUBv0>> protocol. This protocol sends
messages to <<nng_sub#,SUBv0>> peers.
*--sub, --sub0*::
Select the <<nng_sub#,SUBv0>> protocol. This protocol receives
messages from <<nng_pub#,PUBv0>> peers, and filters them based on
subscriptions set with *--subscribe*.
*--push, --push0*::
Select the <<nng_push#,PUSHv0>> protocol. This protocol sends
messages to <<nng_pull#,PULLv0>> peers. A given message is normally
only delivered to a single peer.
*--pull, --pull0*::
Select the <<nng_pull#,PULLv0>> protocol. This protocol receives
messages from <<nng_push#,PUSHv0>> peers.
*--pair0*::
Select the <<nng_pair#,PAIRv0>> protocol. This protocol can send and
receive messages with one connected <<nng_pair#,PAIRv0>> peer.
*--pair1*::
Select the <<nng_pair#,PAIRv1>> protocol. This protocol can send and
receive messages with one connected <<nng_pair#,PAIRv1>> 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 <<nng_surveyor#,SURVEYORv0>> protocol. This protocol sends
a survey request to <<nng_respondent#,RESPONDENTv0>> peers, and then
receives replies from them.
*--respondent, --respondent0*::
Select the <<nng_respondent#,RESPONDENTv0>> protocol. This protocol receives
survey requests from <<nng_survey#,SURVEYORv0>> peers, and can send a reply
to them.
=== Peer Selection
NOTE: At least one peer address must be selected.
TIP: While legacy _nanocat_ only supported one peer, _nng_ 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.
*--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`:::
Messages are printed as quoted strings, with every byte appearing as
an escaped hexadecimal value, such as `\x2E`.
`msgpack`:::
Messages are emitted as https://msgpack.org[MessagePack] "bin format"
(byte arrays).
*-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.
=== 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.
*-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 conjuction 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.
== 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
<<libnng#,libnng(3)>>,
<<nng#,nng(3)>>,
<<nng_bus#,nng_bus(7)>>,
<<nng_pair#,nng_pair(7)>>,
<<nng_pub#,nng_pub(7)>>,
<<nng_pull#,nng_pull(7)>>,
<<nng_push#,nng_push(7)>>,
<<nng_sub#,nng_sub(7)>>,
<<nng_rep#,nng_rep(7)>>,
<<nng_req#,nng_req(7)>>,
<<nng_respondent#,nng_respondent(7)>>,
<<nng_surveyor#,nng_surveyor(7)>>
|
