| blob | a77a551e9084c7a59dc5b4d260c6cdf01e35c38d |
1 .\" $OpenBSD: nc.1,v 1.95 2020/02/12 14:46:36 schwarze Exp $
2 .\"
3 .\" Copyright (c) 1996 David Sacerdote
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. The name of the author may not be used to endorse or promote products
15 .\" derived from this software without specific prior written permission
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .Dd $Mdocdate: February 12 2020 $
29 .Dt NC 1
30 .Os
31 .Sh NAME
32 .Nm nc
33 .Nd arbitrary TCP and UDP connections and listens
34 .Sh SYNOPSIS
35 .Nm nc
36 .Op Fl 46bCDdFhklNnrStUuvZz
37 .Op Fl I Ar length
38 .Op Fl i Ar interval
39 .Op Fl M Ar ttl
40 .Op Fl m Ar minttl
41 .Op Fl O Ar length
42 .Op Fl P Ar proxy_username
43 .Op Fl p Ar source_port
44 .Op Fl q Ar seconds
45 .Op Fl s Ar sourceaddr
46 .Op Fl T Ar keyword
47 .Op Fl V Ar rtable
48 .Op Fl W Ar recvlimit
49 .Op Fl w Ar timeout
50 .Op Fl X Ar proxy_protocol
51 .Op Fl x Ar proxy_address Ns Op : Ns Ar port
52 .Op Ar destination
53 .Op Ar port
54 .Sh DESCRIPTION
55 The
56 .Nm
57 (or
58 .Nm netcat )
59 utility is used for just about anything under the sun involving TCP,
60 UDP, or
61 .Ux Ns -domain
62 sockets.
63 It can open TCP connections, send UDP packets, listen on arbitrary
64 TCP and UDP ports, do port scanning, and deal with both IPv4 and
65 IPv6.
66 Unlike
67 .Xr telnet 1 ,
68 .Nm
69 scripts nicely, and separates error messages onto standard error instead
70 of sending them to standard output, as
71 .Xr telnet 1
72 does with some.
73 .Pp
74 Common uses include:
75 .Pp
76 .Bl -bullet -offset indent -compact
77 .It
78 simple TCP proxies
79 .It
80 shell-script based HTTP clients and servers
81 .It
82 network daemon testing
83 .It
84 a SOCKS or HTTP ProxyCommand for
85 .Xr ssh 1
86 .It
87 and much, much more
88 .El
89 .Pp
90 The options are as follows:
91 .Bl -tag -width Ds
92 .It Fl 4
93 Use IPv4 addresses only.
94 .It Fl 6
95 Use IPv6 addresses only.
96 .It Fl b
97 Allow broadcast.
98 .It Fl C
99 Send CRLF as line-ending. Each line feed (LF) character from the input
100 data is translated into CR+LF before being written to the socket. Line
101 feed characters that are already preceded with a carriage return (CR)
102 are not translated. Received data is not affected.
103 .It Fl D
104 Enable debugging on the socket.
105 .It Fl d
106 Do not attempt to read from stdin.
107 .It Fl F
108 Pass the first connected socket using
109 .Xr sendmsg 2
110 to stdout and exit.
111 This is useful in conjunction with
112 .Fl X
113 to have
114 .Nm
115 perform connection setup with a proxy but then leave the rest of the
116 connection to another program (e.g.\&
117 .Xr ssh 1
118 using the
119 .Xr ssh_config 5
120 .Cm ProxyUseFdpass
121 option).
122 Cannot be used with
123 .Fl U .
124 .It Fl h
125 Print out the
126 .Nm
127 help text and exit.
128 .It Fl I Ar length
129 Specify the size of the TCP receive buffer.
130 .It Fl i Ar interval
131 Sleep for
132 .Ar interval
133 seconds between lines of text sent and received.
134 Also causes a delay time between connections to multiple ports.
135 .It Fl k
136 When a connection is completed, listen for another one.
137 Requires
138 .Fl l .
139 When used together with the
140 .Fl u
141 option, the server socket is not connected and it can receive UDP datagrams from
142 multiple hosts.
143 .It Fl l
144 Listen for an incoming connection rather than initiating a
145 connection to a remote host.
146 The
147 .Ar destination
148 and
149 .Ar port
150 to listen on can be specified either as non-optional arguments, or with
151 options
152 .Fl s
153 and
154 .Fl p
155 respectively.
156 Cannot be used together with
157 .Fl x
158 or
159 .Fl z .
160 Additionally, any timeouts specified with the
161 .Fl w
162 option are ignored.
163 .It Fl M Ar ttl
164 Set the TTL / hop limit of outgoing packets.
165 .It Fl m Ar minttl
166 Ask the kernel to drop incoming packets whose TTL / hop limit is under
167 .Ar minttl .
168 .It Fl N
169 .Xr shutdown 2
170 the network socket after EOF on the input.
171 Some servers require this to finish their work.
172 .It Fl n
173 Do not perform domain name resolution.
174 If a name cannot be resolved without DNS, an error will be reported.
175 .It Fl O Ar length
176 Specify the size of the TCP send buffer.
177 .It Fl P Ar proxy_username
178 Specifies a username to present to a proxy server that requires authentication.
179 If no username is specified then authentication will not be attempted.
180 Proxy authentication is only supported for HTTP CONNECT proxies at present.
181 .It Fl p Ar source_port
182 Specify the source port
183 .Nm
184 should use, subject to privilege restrictions and availability.
185 .It Fl q Ar seconds
186 after EOF on stdin, wait the specified number of
187 .Ar seconds
188 and then quit. If
189 .Ar seconds
190 is negative, wait forever (default). Specifying a non-negative
191 .Ar seconds
192 implies
193 .Fl N .
194 .It Fl r
195 Choose source and/or destination ports randomly
196 instead of sequentially within a range or in the order that the system
197 assigns them.
198 .It Fl S
199 Enable the RFC 2385 TCP MD5 signature option.
200 .It Fl s Ar sourceaddr
201 Set the source address to send packets from,
202 which is useful on machines with multiple interfaces.
203 For
204 .Ux Ns -domain
205 datagram sockets, specifies the local temporary socket file
206 to create and use so that datagrams can be received.
207 Cannot be used together with
208 .Fl x .
209 .It Fl T Ar keyword
210 Change the IPv4 TOS/IPv6 traffic class value.
211 .Ar keyword
212 may be one of
213 .Cm critical ,
214 .Cm inetcontrol ,
215 .Cm lowcost ,
216 .Cm lowdelay ,
217 .Cm netcontrol ,
218 .Cm throughput ,
219 .Cm reliability ,
220 or one of the DiffServ Code Points:
221 .Cm ef ,
222 .Cm af11 No ... Cm af43 ,
223 .Cm cs0 No ... Cm cs7 ;
224 or a number in either hex or decimal.
225 .It Fl t
226 Send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
227 This makes it possible to use
228 .Nm
229 to script telnet sessions.
230 .It Fl U
231 Use
232 .Ux Ns -domain
233 sockets.
234 Cannot be used together with
235 .Fl F
236 or
237 .Fl x .
238 .It Fl u
239 Use UDP instead of TCP.
240 Cannot be used together with
241 .Fl x .
242 For
243 .Ux Ns -domain
244 sockets, use a datagram socket instead of a stream socket.
245 If a
246 .Ux Ns -domain
247 socket is used, a temporary receiving socket is created in
248 .Pa /tmp
249 unless the
250 .Fl s
251 flag is given.
252 .It Fl V Ar rtable
253 Set the routing table to be used.
254 .It Fl v
255 Produce more verbose output.
256 .It Fl W Ar recvlimit
257 Terminate after receiving
258 .Ar recvlimit
259 packets from the network.
260 .It Fl w Ar timeout
261 Connections which cannot be established or are idle timeout after
262 .Ar timeout
263 seconds.
264 The
265 .Fl w
266 flag has no effect on the
267 .Fl l
268 option, i.e.\&
269 .Nm
270 will listen forever for a connection, with or without the
271 .Fl w
272 flag.
273 The default is no timeout.
274 .It Fl X Ar proxy_protocol
275 Use
276 .Ar proxy_protocol
277 when talking to the proxy server.
278 Supported protocols are
279 .Cm 4
280 (SOCKS v.4),
281 .Cm 5
282 (SOCKS v.5)
283 and
284 .Cm connect
285 (HTTPS proxy).
286 If the protocol is not specified, SOCKS version 5 is used.
287 .It Fl x Ar proxy_address Ns Op : Ns Ar port
288 Connect to
289 .Ar destination
290 using a proxy at
291 .Ar proxy_address
292 and
293 .Ar port .
294 If
295 .Ar port
296 is not specified, the well-known port for the proxy protocol is used (1080
297 for SOCKS, 3128 for HTTPS).
298 An IPv6 address can be specified unambiguously by enclosing
299 .Ar proxy_address
300 in square brackets.
301 A proxy cannot be used with any of the options
302 .Fl lsuU .
303 .It Fl Z
304 DCCP mode.
305 .It Fl z
306 Only scan for listening daemons, without sending any data to them.
307 Cannot be used together with
308 .Fl l .
309 .El
310 .Pp
311 .Ar destination
312 can be a numerical IP address or a symbolic hostname
313 (unless the
314 .Fl n
315 option is given).
316 In general, a destination must be specified,
317 unless the
318 .Fl l
319 option is given
320 (in which case the local host is used).
321 For
322 .Ux Ns -domain
323 sockets, a destination is required and is the socket path to connect to
324 (or listen on if the
325 .Fl l
326 option is given).
327 .Pp
328 .Ar port
329 can be specified as a numeric port number or as a service name.
330 Port ranges may be specified as numeric port numbers of the form
331 .Ar nn Ns - Ns Ar mm .
332 In general,
333 a destination port must be specified,
334 unless the
335 .Fl U
336 option is given.
337 .Sh CLIENT/SERVER MODEL
338 It is quite simple to build a very basic client/server model using
339 .Nm .
340 On one console, start
341 .Nm
342 listening on a specific port for a connection.
343 For example:
344 .Pp
345 .Dl $ nc -l 1234
346 .Pp
347 .Nm
348 is now listening on port 1234 for a connection.
349 On a second console
350 .Pq or a second machine ,
351 connect to the machine and port being listened on:
352 .Pp
353 .Dl $ nc 127.0.0.1 1234
354 .Pp
355 There should now be a connection between the ports.
356 Anything typed at the second console will be concatenated to the first,
357 and vice-versa.
358 After the connection has been set up,
359 .Nm
360 does not really care which side is being used as a
361 .Sq server
362 and which side is being used as a
363 .Sq client .
364 The connection may be terminated using an
365 .Dv EOF
366 .Pq Sq ^D .
367 .Pp
368 There is no
369 .Fl c
370 or
371 .Fl e
372 option in this netcat, but you still can execute a command after connection
373 being established by redirecting file descriptors. Be cautious here because
374 opening a port and let anyone connected execute arbitrary command on your
375 site is DANGEROUS. If you really need to do this, here is an example:
376 .Pp
377 On
378 .Sq server
379 side:
380 .Pp
381 .Dl $ rm -f /tmp/f; mkfifo /tmp/f
382 .Dl $ cat /tmp/f | /bin/sh -i 2>&1 | nc -l 127.0.0.1 1234 > /tmp/f
383 .Pp
384 On
385 .Sq client
386 side:
387 .Pp
388 .Dl $ nc host.example.com 1234
389 .Dl $ (shell prompt from host.example.com)
390 .Pp
391 By doing this, you create a fifo at /tmp/f and make nc listen at port 1234
392 of address 127.0.0.1 on
393 .Sq server
394 side, when a
395 .Sq client
396 establishes a connection successfully to that port, /bin/sh gets executed
397 on
398 .Sq server
399 side and the shell prompt is given to
400 .Sq client
401 side.
402 .Pp
403 When connection is terminated,
404 .Nm
405 quits as well. Use
406 .Fl k
407 if you want it keep listening, but if the command quits this option won't
408 restart it or keep
409 .Nm
410 running. Also don't forget to remove the file descriptor once you don't need
411 it anymore:
412 .Pp
413 .Dl $ rm -f /tmp/f
414 .Pp
415 .Sh DATA TRANSFER
416 The example in the previous section can be expanded to build a
417 basic data transfer model.
418 Any information input into one end of the connection will be output
419 to the other end, and input and output can be easily captured in order to
420 emulate file transfer.
421 .Pp
422 Start by using
423 .Nm
424 to listen on a specific port, with output captured into a file:
425 .Pp
426 .Dl $ nc -l 1234 \*(Gt filename.out
427 .Pp
428 Using a second machine, connect to the listening
429 .Nm
430 process, feeding it the file which is to be transferred:
431 .Pp
432 .Dl $ nc -N host.example.com 1234 \*(Lt filename.in
433 .Pp
434 After the file has been transferred, the connection will close automatically.
435 .Sh TALKING TO SERVERS
436 It is sometimes useful to talk to servers
437 .Dq by hand
438 rather than through a user interface.
439 It can aid in troubleshooting,
440 when it might be necessary to verify what data a server is sending
441 in response to commands issued by the client.
442 For example, to retrieve the home page of a web site:
443 .Bd -literal -offset indent
444 $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
445 .Ed
446 .Pp
447 Note that this also displays the headers sent by the web server.
448 They can be filtered, using a tool such as
449 .Xr sed 1 ,
450 if necessary.
451 .Pp
452 More complicated examples can be built up when the user knows the format
453 of requests required by the server.
454 As another example, an email may be submitted to an SMTP server using:
455 .Bd -literal -offset indent
456 $ nc [\-C] localhost 25 \*(Lt\*(Lt EOF
457 HELO host.example.com
458 MAIL FROM:\*(Ltuser@host.example.com\*(Gt
459 RCPT TO:\*(Ltuser2@host.example.com\*(Gt
460 DATA
461 Body of email.
462 \&.
463 QUIT
464 EOF
465 .Ed
466 .Sh PORT SCANNING
467 It may be useful to know which ports are open and running services on
468 a target machine.
469 The
470 .Fl z
471 flag can be used to tell
472 .Nm
473 to report open ports,
474 rather than initiate a connection. Usually it's useful to turn on verbose
475 output to stderr by use this option in conjunction with
476 .Fl v
477 option.
478 .Pp
479 For example:
480 .Bd -literal -offset indent
481 $ nc \-zv host.example.com 20-30
482 Connection to host.example.com 22 port [tcp/ssh] succeeded!
483 Connection to host.example.com 25 port [tcp/smtp] succeeded!
484 .Ed
485 .Pp
486 The port range was specified to limit the search to ports 20 \- 30, and is
487 scanned by increasing order (unless the
488 .Fl r
489 flag is set).
490 .Pp
491 You can also specify a list of ports to scan, for example:
492 .Bd -literal -offset indent
493 $ nc \-zv host.example.com http 20 22-23
494 nc: connect to host.example.com 80 (tcp) failed: Connection refused
495 nc: connect to host.example.com 20 (tcp) failed: Connection refused
496 Connection to host.example.com port [tcp/ssh] succeeded!
497 nc: connect to host.example.com 23 (tcp) failed: Connection refused
498 .Ed
499 .Pp
500 The ports are scanned by the order you given (unless the
501 .Fl r
502 flag is set).
503 .Pp
504 Alternatively, it might be useful to know which server software
505 is running, and which versions.
506 This information is often contained within the greeting banners.
507 In order to retrieve these, it is necessary to first make a connection,
508 and then break the connection when the banner has been retrieved.
509 This can be accomplished by specifying a small timeout with the
510 .Fl w
511 flag, or perhaps by issuing a
512 .Qq Dv QUIT
513 command to the server:
514 .Bd -literal -offset indent
515 $ echo "QUIT" | nc host.example.com 20-30
516 SSH-1.99-OpenSSH_3.6.1p2
517 Protocol mismatch.
518 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
519 .Ed
520 .Sh EXAMPLES
521 Open a TCP connection to port 42 of host.example.com, using port 31337 as
522 the source port, with a timeout of 5 seconds:
523 .Pp
524 .Dl $ nc -p 31337 -w 5 host.example.com 42
525 .Pp
526 Open a UDP connection to port 53 of host.example.com:
527 .Pp
528 .Dl $ nc -u host.example.com 53
529 .Pp
530 Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
531 IP for the local end of the connection:
532 .Pp
533 .Dl $ nc -s 10.1.2.3 host.example.com 42
534 .Pp
535 Create and listen on a
536 .Ux Ns -domain
537 stream socket:
538 .Pp
539 .Dl $ nc -lU /var/tmp/dsocket
540 .Pp
541 Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
542 port 8080.
543 This example could also be used by
544 .Xr ssh 1 ;
545 see the
546 .Cm ProxyCommand
547 directive in
548 .Xr ssh_config 5
549 for more information.
550 .Pp
551 .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
552 .Pp
553 The same example again, this time enabling proxy authentication with username
554 .Dq ruser
555 if the proxy requires it:
556 .Pp
557 .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
558 .Sh SEE ALSO
559 .Xr cat 1 ,
560 .Xr ssh 1
561 .Sh AUTHORS
562 Original implementation by
563 .An *Hobbit* Aq Mt hobbit@avian.org .
564 .br
565 Rewritten with IPv6 support by
566 .An Eric Jackson Aq Mt ericj@monkey.org .
567 .br
568 Modified for Debian port by Aron Xu
569 .Aq aron@debian.org .
570 .Sh CAVEATS
571 UDP port scans using the
572 .Fl uz
573 combination of flags will always report success irrespective of
574 the target machine's state.
575 However,
576 in conjunction with a traffic sniffer either on the target machine
577 or an intermediary device,
578 the
579 .Fl uz
580 combination could be useful for communications diagnostics.
581 Note that the amount of UDP traffic generated may be limited either
582 due to hardware resources and/or configuration settings.