1NC6(1) General Commands Manual NC6(1)
2
6 nc6 - network swiss army knife
7
9 nc6 [options...] hostname port
10 nc6 -l -p port [-s addr] [options...] [hostname] [port]
11
13 netcat6 is a simple unix utility which reads and writes data across
14 network connections, using the TCP or UDP protocol over IPv4 or IPv6
15 networks. It is designed to be a reliable "back-end" tool that can be
16 used directly or easily driven by other programs and scripts. At the
17 same time, it is a feature-rich network debugging and exploration tool,
18 since it can create almost any kind of connection you would need and
19 has several interesting built-in capabilities. netcat6 , or nc6 as the
20 actual program is named, should have been supplied long ago as another
21 one of those cryptic but standard Unix tools.
22 In the simplest usage, " nc6 host port " creates a TCP connection to
24 the given port on the given target host. Your standard input is then
25 sent to the host, and anything that comes back across the connection is
26 sent to your standard output. This continues indefinitely, until the
27 network side of the connection shuts down. Note that this behavior is
28 different from most other applications which shut everything down and
29 exit after an end-of-file on the standard input (though this style of
30 operation can easily be enabled).
31 netcat6 can also function as a server, by listening for inbound connec‐
33 tions on arbitrary ports and then doing the same reading and writing.
34 With minor limitations, netcat6 doesn't really care if it runs in
35 "client" or "server" mode -- it still shovels data back and forth until
36 there isn't any more left. In this manual page, these two working
37 modes are referred as "connect mode" and "listen mode", respectively.
38
40 -4 Forces the use of IPv4.
41 -6 Forces the use of IPv6 and inhibits the use IPV4-mapped
43 addresses.
44 -b, --bluetooth
46 With this option set, netcat6 will use bluetooth to estab‐
47 lish connections. By default the L2CAP protocol will be
48 used (also see '--sco').
49 --buffer-size=BYTES
51 Set the buffer size for the local and remote endpoints.
52 netcat6 does all reads into these buffers, so they should
53 be large enough to minimize excessive reads from the
54 socket and in UDP mode it should be large enough to
55 receive an entire datagram (also see '--nru'). By
56 default, the buffer size is 8 kilobytes for TCP connec‐
57 tions and 128 kilobytes for UDP.
58 --continuous Enable continuous accepting of connections in listen mode,
60 like inetd. Must be used with --exec to specify the com‐
61 mand to run locally (try 'nc6 --continuous --exec cat -l
62 -p <port>' to make a simple echo server).
63 --disable-nagle
65 Disable the use of the Nagle algorithm for TCP connections
66 (see "NAGLE ALGORITHM").
67 -e, --exec=CMD
69 Exec the listed CMD after a connect is established. All
70 input from the remote client will be available on stdin to
71 the command, and all output from the command will be sent
72 back to the remote client.
73 -h, --help Display a brief help listing.
75 --half-close Properly handle (and send) TCP half closes for protocols
77 that support them (eg. TCP). See "HALF CLOSE".
78 -l, --listen Selects listen mode (for inbound connects).
80 --mtu=BYTES Set the Maximum Transmission Unit for the remote endpoint
82 (network transmits). This is only really useful for data‐
83 gram protocols like UDP. For TCP the MTU is determined by
84 the kernel and this will only affect the amount that is
85 passed to the kernel at any one time. There is no default
86 MTU for TCP connections (and there should be no need to
87 change this), and for UDP it is 8 kilobytes.
88 -n Disables DNS queries - you'll have to use numeric IP
90 address instead of hostnames.
91 --no-reuseaddr
93 Disables the SO_REUSEADDR socket option (this is only use‐
94 ful in listen mode).
95 --nru=BYTES Set the miNimum Receive Unit for the remote endpoint (net‐
97 work receives). Note that this does not mean that every
98 network read will get the specified number of bytes, only
99 that nc6 MUST be able to receive at least that amount of
100 data when a read is done. This is only really useful for
101 datagram protocols like UDP where the entire datagram must
102 be received in one call or it is truncated. The default
103 NRU for TCP connections is 1 byte, and 65536 bytes for
104 UDP.
105 -p, --port=PORT
107 Sets the port number for the local endpoint of the connec‐
108 tion.
109 -q, --hold-timeout=SEC1[:SEC2]
111 Sets the hold timeout(s) (see "TIMEOUTS"). Specifying
112 just one value will set the hold timeout on the local end‐
113 point, specifying a second value will set the hold timeout
114 on the remote endpoint as well. Either value can be '0'
115 (for instant timeout) or '-' (for no hold timeout, eg.
116 infinite hold).
117 -t, --idle-timeout=SEC
119 Sets the idle timeout (see "TIMEOUTS").
120 --rcvbuf-size=SIZE
122 Specify the size to be used for the kernel receive buffer
123 for network sockets.
124 --recv-only Only receive data, don't transmit. This also disables any
126 hold timeouts.
127 -s, --address=ADDRESS
129 Sets the source address for the local endpoint of the con‐
130 nection.
131 --sco With this option set, netcat6 with use SCO over bluetooth
133 (note that '-b' or '--bluetooth' must also be specified).
134 --send-only Only send data, don't receive. This also disables any
136 hold timeouts.
137 --sndbuf-size=SIZE
139 Specify the size to be used for the kernel send buffer for
140 network sockets.
141 -u, --udp With this option set, netcat6 will use UDP as the trans‐
143 port protocol (TCP is the default).
144 -v Enable verbose mode. This gives some basic information
146 about what netcat6 is doing. Use it twice for extra ver‐
147 bosity.
148 --version Print netcat6 version and exit.
150 -w, --timeout=SECONDS
152 Timeout for network connects and accepts (see "TIMEOUTS").
153 -x, --transfer
155 File transfer mode (see "FILE TRANSFER"). If listen mode
156 is specified, this is equivalent to "--recv-only --buffer-
157 size=65536" otherwise it is equivalent to "--send-only
158 --buffer-size=65536". -X, --rev-transfer Reverse file
159 transfer mode (see "FILE TRANSFER"). This transfers in
160 the opposite direction to normal transfer. If listen mode
161 is specified, this is equivalent to "--send-only --buffer-
162 size=65536" otherwise it is equivalent to "--recv-only
163 --buffer-size=65536".
164
166 UDP support in netcat6 works very well in both connect and in listen
167 mode. When using UDP in listen mode netcat6 accepts UDP packets from
168 any source that matches the optional address and/or port specified (if
169 it was specified). However, once the first packet is received, netcat6
170 will only receive packets from that client in future. This is done by
171 putting the UDP socket into "connected" state (see udp(4) and con‐
172 nect(2)). Packets from other sources are discarded by the kernel and
173 an ICMP unreachable response is sent.
174 When connecting to a remote host using UDP, nc6 will report that the
176 connection is open regardless of whether a remote server is listening.
177 This is because UDP is a connectionless protocol, and hence no connec‐
178 tion establishment is actually required. However, after sending the
179 first packet of data, a server may reply with an ICMP unreachable
180 response causing nc6 to exit with a 'Connection refused' error message.
181 netcat6 allows for fine control over the buffer sizes, MTU's and NRU's
183 for the connection, which is especially useful for UDP connections.
184 See the --buffer-size, --mtu and --nru options.
185
187 netcat6 currently implements a connect/accept timeout, and idle time‐
188 out, and hold timeouts on both the remote and local endpoints.
189 · The connect/accept timeout is optional and is specified with the -w
191 or --timeout option. If a connection cannot be established within
192 the specified time, nc6 will exit with a non-zero exit status. If
193 the option is not specified, nc6 will wait forever when listening
194 for new connections (in listen mode), and will use the standard
195 operating system timeout when trying to connect to remote systems.
196 Note that the connect timeout is essentially ignored when creating
197 UDP connections to a remote server, as UDP is a connectionless pro‐
198 tocol.
199 · The idle timeout is optional and is specified with the -t or
201 --idle-timeout option. If no data is sent or received from the
202 remote host in the specified time, nc6 will exit with a non-zero
203 exit status. The default is to not timeout idle connections.
204 · The hold timeouts specify how long the connection should be held
206 open after a given endpoint can no longer be read from (because EOF
207 was received). When the hold timeout occurs for a given endpoint,
208 no more data is read from the opposite endpoint. After data read
209 from the timed out endpoint has been sent, then the connection is
210 closed and nc6 exits.
211 For example, setting the hold time of the local endpoint to 5 would
213 cause reading from the remote system to stop 5 seconds after stdin
214 is closed (eg. by using ^D to send EOF). All buffered data to be
215 sent to the remote system is then sent, after which nc6 exits suc‐
216 cessfully (if no errors occurred).
217 By default, the hold timeout is disabled for the local endpoint
219 (essentially an 'infinite' timeout), and the hold timeout is set to
220 0 for the remote endpoint (an 'instant' timeout). This means that
221 nc6 effectively exits immediately when the read from the remote
222 server is closed.
223 In half close mode (see "HALF CLOSE") all hold timeouts are dis‐
225 abled by default.
226
228 netcat6 can be used to transfer files and data streams efficiently,
229 using the ´-x' or '--transfer' command line option (or the '-X' and
230 '--rev-transfer' equivalents for transfer in the opposite direction).
231 For example, to transfer a file from machine 'foo.example.com' to
233 machine ´bar.example.com', one would use the following technique.
234 On 'bar', set up a listening nc6 on any local port:
236 bar$ nc6 -x -l -p 7676 > targetfile
238 Then on 'foo', use nc6 to send the file to the listening nc6:
240 foo$ nc6 -x bar.example.com 7676 < sourcefile
242 You can also use file transfer mode to pipe the output of programs over
244 networks. For example, you can use tar with nc6 to copy entire direc‐
245 tories:
246 bar$ nc6 -x -l -p 7676 | tar xpzf -
248 foo$ tar cpzf - /home | nc6 -x bar.example.com 7676
250 The '-x' or '--transfer' option is just an alias for various other
252 options which set the direction of transfer and increase the buffer
253 sizes used. In listen mode, it is equivalent to "--recv-only --buffer-
254 size=65536" otherwise it is equivalent to "--send-only --buffer-
255 size=65536".
256 The normal file transfer mode options assume the file will be sent TO
258 the netcat6 process that is in listen mode, FROM the netcat6 process
259 that is connecting to it. To transfer the other way use the -X or
260 --rev-transfer options.
261
263 Stream based data transfers, such as TCP, have 2 separate streams - the
264 receive and the transmit stream. Contrary to common belief, the
265 streams can be closed independently of each other - in TCP this is
266 called a half-close.
267 In standard mode, netcat6 closes the entire remote connection when it
269 detects that the remote receive stream has been closed. This is a com‐
270 mon operation for most TCP applications, because it is unusual that a
271 server will keep accepting data after it has indicated that it will no
272 longer send any. netcat6 also doesn't close it's remote transmit when
273 it has no more data to send (eg. when EOF has been received on stdin),
274 so as not to confuse remote servers by making them think that netcat6
275 isn't listening for data any more.
276 However, some servers do make active use of TCP half-closes, and the
278 default operation of netcat6 doesn't work well with these services.
279 For example, when using netcat6 to simulate a HTTP server, some HTTP
280 clients close their transmit stream after they send their request. In
281 default mode, netcat6 will close the entire connection before sending
282 the response back to the client.
283 However, by specifying the "--half-close" option, netcat6 will keep
285 trying to send data to the remote server after the receive stream has
286 closed. It will also close the remote transmit stream when there is no
287 more data to send (EOF has been received on stdin).
288
290 Named after its creator, John Nagle, the Nagle algorithm is used to
291 combine together small writes to a TCP stream and thus decrease the
292 number of packets that must be sent out on the network.
293 This was designed as a means for dealing with what Nagle called the
295 small packet problem, created when an application generates data one
296 byte at a time, causing the network to be overloaded with packets. A
297 single character originating from a keyboard could result in the an
298 entire packet (the single byte plus packet headers) being sent onto the
299 network.
300 The algorithm can, under some situations, add a small delay before the
302 data is sent out on the wire - so as to allow for this concatenation to
303 occur. This is done in such a way that it is generally unnoticeable
304 for normal applications, including interactive applications.
305 There are some situations, such as real-time protocols, that can be
307 adversely affected by this small delay, which is why it is possible to
308 disable the Nagle algorithm on most systems, using the TCP_NODELAY
309 socket option.
310 netcat6 provides the '--disable-nagle' command line option to disable
312 the Nagle algorithm for the connection.
313
315 netcat6 attempts to exit cleanly (exit value 0) when all data was sent
316 or received successfully, and to exit with an error value otherwise.
317 However, the specific definition of successfully varies depending on
318 the way nc6 is run.
319 In normal mode, nc6 exits successfully when all data from the remote
321 machine has been received (up to and including an EOF), and the data
322 has been output to the stdout without any errors. It DOES NOT indicate
323 whether all data read from stdin has been successfully sent to the
324 remote machine.
325 In --half-close mode, nc6 exists successfully when an EOF has been
327 received from both the remote machine AND from stdin, and all data has
328 been successfully sent. Thus the exit status indicates that all data
329 was transfered successfully.
330 If hold timeouts (see "TIMEOUTS") have been set for either the remote
332 or local endpoint, nc6 will exit successfully if all buffered data from
333 the endpoint that timed out is successfully sent. It DOES NOT indicate
334 whether all data from the opposite endpoint was sent (or even read).
335 For connectionless protocols like UDP there is no way of determining
337 whether the remote system has stopped sending data, or if it will
338 accept further data sent. So in UDP mode, nc6 will either never exit
339 (until interrupted via ctrl-C) or will exit after an error when sending
340 data to the remote system, in which case the exit code is a failure
341 (exit value 1).
342
344 This man page is current for version 1.0 of netcat6
345
347 GPL.
348
350 Mauro Tortonesi <mauro@deepspace6.net>
351 Chris Leishman <chris@leishman.org>
352 The original netcat was written by a guy we know as the Hobbit <hob‐
354 bit@avian.org>.
355 NC6(1)