Annotation of src/usr.bin/nc/nc.1, Revision 1.88
1.88 ! jsing 1: .\" $OpenBSD: nc.1,v 1.87 2017/07/15 18:11:47 jmc Exp $
1.1 deraadt 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: .\"
1.87 jmc 28: .Dd $Mdocdate: July 15 2017 $
1.3 aaron 29: .Dt NC 1
1.4 deraadt 30: .Os
1.1 deraadt 31: .Sh NAME
32: .Nm nc
1.28 jmc 33: .Nd arbitrary TCP and UDP connections and listens
1.2 deraadt 34: .Sh SYNOPSIS
1.1 deraadt 35: .Nm nc
1.70 jmc 36: .Op Fl 46cDdFhklNnrStUuvz
37: .Op Fl C Ar certfile
38: .Op Fl e Ar name
39: .Op Fl H Ar hash
1.47 jmc 40: .Op Fl I Ar length
1.1 deraadt 41: .Op Fl i Ar interval
1.70 jmc 42: .Op Fl K Ar keyfile
1.73 jca 43: .Op Fl M Ar ttl
44: .Op Fl m Ar minttl
1.47 jmc 45: .Op Fl O Ar length
1.77 beck 46: .Op Fl o Ar staplefile
1.42 djm 47: .Op Fl P Ar proxy_username
1.28 jmc 48: .Op Fl p Ar source_port
1.70 jmc 49: .Op Fl R Ar CAfile
1.57 jeremy 50: .Op Fl s Ar source
1.69 beck 51: .Op Fl T Ar keyword
1.54 guenther 52: .Op Fl V Ar rtable
1.85 bluhm 53: .Op Fl W Ar recvlimit
1.6 aaron 54: .Op Fl w Ar timeout
1.33 djm 55: .Op Fl X Ar proxy_protocol
1.71 schwarze 56: .Op Fl x Ar proxy_address Ns Op : Ns Ar port
1.83 beck 57: .Op Fl Z Ar peercertfile
1.57 jeremy 58: .Op Ar destination
1.48 sobrado 59: .Op Ar port
1.1 deraadt 60: .Sh DESCRIPTION
61: The
1.6 aaron 62: .Nm
1.1 deraadt 63: (or
64: .Nm netcat )
1.57 jeremy 65: utility is used for just about anything under the sun involving TCP,
66: UDP, or
67: .Ux Ns -domain
68: sockets.
1.13 ericj 69: It can open TCP connections, send UDP packets, listen on arbitrary
70: TCP and UDP ports, do port scanning, and deal with both IPv4 and
71: IPv6.
1.7 aaron 72: Unlike
1.1 deraadt 73: .Xr telnet 1 ,
1.6 aaron 74: .Nm
1.1 deraadt 75: scripts nicely, and separates error messages onto standard error instead
1.6 aaron 76: of sending them to standard output, as
1.24 pvalchev 77: .Xr telnet 1
1.6 aaron 78: does with some.
1.1 deraadt 79: .Pp
80: Common uses include:
1.7 aaron 81: .Pp
82: .Bl -bullet -offset indent -compact
1.1 deraadt 83: .It
1.3 aaron 84: simple TCP proxies
1.1 deraadt 85: .It
1.28 jmc 86: shell-script based HTTP clients and servers
1.1 deraadt 87: .It
1.13 ericj 88: network daemon testing
1.1 deraadt 89: .It
1.33 djm 90: a SOCKS or HTTP ProxyCommand for
91: .Xr ssh 1
92: .It
1.1 deraadt 93: and much, much more
94: .El
95: .Pp
96: The options are as follows:
97: .Bl -tag -width Ds
1.13 ericj 98: .It Fl 4
99: Forces
100: .Nm
101: to use IPv4 addresses only.
102: .It Fl 6
103: Forces
104: .Nm
105: to use IPv6 addresses only.
1.70 jmc 106: .It Fl C Ar certfile
1.69 beck 107: Specifies the filename from which the public key part of the TLS
1.70 jmc 108: certificate is loaded, in PEM format.
109: May only be used with TLS.
1.69 beck 110: .It Fl c
1.70 jmc 111: If using a TCP socket to connect or listen, use TLS.
112: Illegal if not using TCP sockets.
1.32 markus 113: .It Fl D
114: Enable debugging on the socket.
1.29 tedu 115: .It Fl d
116: Do not attempt to read from stdin.
1.69 beck 117: .It Fl e Ar name
1.70 jmc 118: Specify the name that must be present in the peer certificate when using TLS.
1.69 beck 119: Illegal if not using TLS.
1.64 djm 120: .It Fl F
121: Pass the first connected socket using
122: .Xr sendmsg 2
123: to stdout and exit.
124: This is useful in conjunction with
125: .Fl X
126: to have
127: .Nm
128: perform connection setup with a proxy but then leave the rest of the
1.65 jmc 129: connection to another program (e.g.\&
1.64 djm 130: .Xr ssh 1
131: using the
132: .Xr ssh_config 5
1.68 tobias 133: .Cm ProxyUseFdpass
1.64 djm 134: option).
1.70 jmc 135: .It Fl H Ar hash
1.69 beck 136: Specifies the required hash string of the peer certificate when using TLS.
137: The string format required is that used by
138: .Xr tls_peer_cert_hash 3 .
139: Illegal if not using TLS, and may not be used with -T noverify.
1.13 ericj 140: .It Fl h
141: Prints out
142: .Nm
143: help.
1.47 jmc 144: .It Fl I Ar length
1.46 djm 145: Specifies the size of the TCP receive buffer.
1.13 ericj 146: .It Fl i Ar interval
1.1 deraadt 147: Specifies a delay time interval between lines of text sent and received.
148: Also causes a delay time between connections to multiple ports.
1.70 jmc 149: .It Fl K Ar keyfile
1.69 beck 150: Specifies the filename from which the private key
1.70 jmc 151: is loaded in PEM format.
152: May only be used with TLS.
1.13 ericj 153: .It Fl k
154: Forces
155: .Nm
1.21 ericj 156: to stay listening for another connection after its current connection
1.13 ericj 157: is completed.
1.28 jmc 158: It is an error to use this option without the
159: .Fl l
160: option.
1.61 haesbaer 161: When used together with the
162: .Fl u
163: option, the server socket is not connected and it can receive UDP datagrams from
164: multiple hosts.
1.1 deraadt 165: .It Fl l
1.13 ericj 166: Used to specify that
1.6 aaron 167: .Nm
1.13 ericj 168: should listen for an incoming connection rather than initiate a
1.7 aaron 169: connection to a remote host.
1.28 jmc 170: It is an error to use this option in conjunction with the
171: .Fl p ,
172: .Fl s ,
173: or
174: .Fl z
175: options.
1.36 jmc 176: Additionally, any timeouts specified with the
1.35 jmc 177: .Fl w
1.36 jmc 178: option are ignored.
1.73 jca 179: .It Fl M Ar ttl
1.74 jmc 180: Set the TTL / hop limit of outgoing packets.
1.73 jca 181: .It Fl m Ar minttl
1.74 jmc 182: Ask the kernel to drop incoming packets whose TTL / hop limit is under
1.73 jca 183: .Ar minttl .
1.62 sthen 184: .It Fl N
185: .Xr shutdown 2
186: the network socket after EOF on the input.
187: Some servers require this to finish their work.
1.1 deraadt 188: .It Fl n
1.21 ericj 189: Do not do any DNS or service lookups on any specified addresses,
190: hostnames or ports.
1.47 jmc 191: .It Fl O Ar length
192: Specifies the size of the TCP send buffer.
1.77 beck 193: .It Fl o Ar staplefile
194: Specifies the filename from which to load data to be stapled
195: during the TLS handshake.
1.81 jmc 196: The file is expected to contain an OCSP response from an OCSP server in
1.78 jmc 197: DER format.
1.77 beck 198: May only be used with TLS and when a certificate is being used.
1.42 djm 199: .It Fl P Ar proxy_username
200: Specifies a username to present to a proxy server that requires authentication.
201: If no username is specified then authentication will not be attempted.
202: Proxy authentication is only supported for HTTP CONNECT proxies at present.
1.28 jmc 203: .It Fl p Ar source_port
1.1 deraadt 204: Specifies the source port
1.6 aaron 205: .Nm
1.1 deraadt 206: should use, subject to privilege restrictions and availability.
1.28 jmc 207: It is an error to use this option in conjunction with the
208: .Fl l
209: option.
1.70 jmc 210: .It Fl R Ar CAfile
211: Specifies the filename from which the root CA bundle for certificate
212: verification is loaded, in PEM format.
213: Illegal if not using TLS.
214: The default is
1.69 beck 215: .Pa /etc/ssl/cert.pem .
1.1 deraadt 216: .It Fl r
1.13 ericj 217: Specifies that source and/or destination ports should be chosen randomly
218: instead of sequentially within a range or in the order that the system
1.21 ericj 219: assigns them.
1.28 jmc 220: .It Fl S
221: Enables the RFC 2385 TCP MD5 signature option.
1.57 jeremy 222: .It Fl s Ar source
1.3 aaron 223: Specifies the IP of the interface which is used to send the packets.
1.56 jeremy 224: For
225: .Ux Ns -domain
226: datagram sockets, specifies the local temporary socket file
227: to create and use so that datagrams can be received.
1.28 jmc 228: It is an error to use this option in conjunction with the
229: .Fl l
230: option.
1.69 beck 231: .It Fl T Ar keyword
232: Change IPv4 TOS value or TLS options.
233: For TLS options
234: .Ar keyword
1.87 jmc 235: may be one of:
236: .Ar noverify ,
1.70 jmc 237: which disables certificate verification;
1.69 beck 238: .Ar noname ,
1.75 beck 239: which disables certificate name checking;
1.70 jmc 240: .Ar clientcert ,
1.75 beck 241: which requires a client certificate on incoming connections; or
242: .Ar muststaple ,
1.76 jmc 243: which requires the peer to provide a valid stapled OCSP response
244: with the handshake.
1.88 ! jsing 245: The following TLS options specify a value in the form of a key=value pair:
! 246: .Ar ciphers ,
! 247: which allows the supported TLS ciphers to be specified (see
! 248: .Xr tls_config_set_ciphers 3
! 249: for further details);
! 250: .Ar protocols ,
! 251: which allows the supported TLS protocols to be specified (see
! 252: .Xr tls_config_parse_protocols 3
! 253: for further details).
1.76 jmc 254: It is illegal to specify TLS options if not using TLS.
1.70 jmc 255: .Pp
1.69 beck 256: For IPv4 TOS value
257: .Ar keyword
1.58 haesbaer 258: may be one of
259: .Ar critical ,
260: .Ar inetcontrol ,
261: .Ar lowdelay ,
262: .Ar netcontrol ,
263: .Ar throughput ,
264: .Ar reliability ,
265: or one of the DiffServ Code Points:
266: .Ar ef ,
267: .Ar af11 ... af43 ,
268: .Ar cs0 ... cs7 ;
269: or a number in either hex or decimal.
1.1 deraadt 270: .It Fl t
271: Causes
1.6 aaron 272: .Nm
1.25 jmc 273: to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
1.7 aaron 274: This makes it possible to use
1.6 aaron 275: .Nm
1.7 aaron 276: to script telnet sessions.
1.28 jmc 277: .It Fl U
1.51 sobrado 278: Specifies to use
1.52 sobrado 279: .Ux Ns -domain
280: sockets.
1.1 deraadt 281: .It Fl u
1.13 ericj 282: Use UDP instead of the default option of TCP.
1.56 jeremy 283: For
284: .Ux Ns -domain
285: sockets, use a datagram socket instead of a stream socket.
286: If a
287: .Ux Ns -domain
288: socket is used, a temporary receiving socket is created in
289: .Pa /tmp
290: unless the
291: .Fl s
292: flag is given.
1.54 guenther 293: .It Fl V Ar rtable
294: Set the routing table to be used.
1.1 deraadt 295: .It Fl v
1.13 ericj 296: Have
1.6 aaron 297: .Nm
1.13 ericj 298: give more verbose output.
1.85 bluhm 299: .It Fl W Ar recvlimit
300: Terminate after receiving
301: .Ar recvlimit
302: packets from the network.
1.26 jmc 303: .It Fl w Ar timeout
1.59 fgsch 304: Connections which cannot be established or are idle timeout after
1.26 jmc 305: .Ar timeout
1.59 fgsch 306: seconds.
1.26 jmc 307: The
308: .Fl w
309: flag has no effect on the
310: .Fl l
311: option, i.e.\&
312: .Nm
313: will listen forever for a connection, with or without the
314: .Fl w
315: flag.
316: The default is no timeout.
1.43 jmc 317: .It Fl X Ar proxy_protocol
1.28 jmc 318: Requests that
319: .Nm
1.33 djm 320: should use the specified protocol when talking to the proxy server.
321: Supported protocols are
322: .Dq 4
323: (SOCKS v.4),
324: .Dq 5
325: (SOCKS v.5)
326: and
327: .Dq connect
328: (HTTPS proxy).
329: If the protocol is not specified, SOCKS version 5 is used.
1.71 schwarze 330: .It Fl x Ar proxy_address Ns Op : Ns Ar port
1.19 jakob 331: Requests that
332: .Nm
333: should connect to
1.57 jeremy 334: .Ar destination
1.33 djm 335: using a proxy at
1.28 jmc 336: .Ar proxy_address
337: and
338: .Ar port .
339: If
340: .Ar port
1.33 djm 341: is not specified, the well-known port for the proxy protocol is used (1080
342: for SOCKS, 3128 for HTTPS).
1.82 jca 343: An IPv6 address can be specified unambiguously by enclosing
344: .Ar proxy_address
345: in square brackets.
1.84 jmc 346: .It Fl Z Ar peercertfile
347: Specifies the filename in which the peer supplied certificates will be saved
348: in PEM format.
349: May only be used with TLS.
1.1 deraadt 350: .It Fl z
351: Specifies that
1.6 aaron 352: .Nm
1.13 ericj 353: should just scan for listening daemons, without sending any data to them.
1.28 jmc 354: It is an error to use this option in conjunction with the
355: .Fl l
356: option.
357: .El
1.35 jmc 358: .Pp
1.57 jeremy 359: .Ar destination
1.35 jmc 360: can be a numerical IP address or a symbolic hostname
361: (unless the
362: .Fl n
363: option is given).
1.57 jeremy 364: In general, a destination must be specified,
1.35 jmc 365: unless the
366: .Fl l
367: option is given
368: (in which case the local host is used).
1.57 jeremy 369: For
370: .Ux Ns -domain
371: sockets, a destination is required and is the socket path to connect to
372: (or listen on if the
373: .Fl l
374: option is given).
1.35 jmc 375: .Pp
1.48 sobrado 376: .Ar port
1.72 beck 377: can be a specified as a numeric port number, or as a service name.
378: Ports may be specified in a range of the form nn-mm.
1.35 jmc 379: In general,
380: a destination port must be specified,
381: unless the
382: .Fl U
1.57 jeremy 383: option is given.
1.28 jmc 384: .Sh CLIENT/SERVER MODEL
385: It is quite simple to build a very basic client/server model using
386: .Nm .
387: On one console, start
388: .Nm
389: listening on a specific port for a connection.
390: For example:
391: .Pp
392: .Dl $ nc -l 1234
393: .Pp
394: .Nm
395: is now listening on port 1234 for a connection.
396: On a second console
397: .Pq or a second machine ,
398: connect to the machine and port being listened on:
399: .Pp
400: .Dl $ nc 127.0.0.1 1234
401: .Pp
402: There should now be a connection between the ports.
403: Anything typed at the second console will be concatenated to the first,
404: and vice-versa.
405: After the connection has been set up,
406: .Nm
407: does not really care which side is being used as a
408: .Sq server
409: and which side is being used as a
410: .Sq client .
411: The connection may be terminated using an
412: .Dv EOF
413: .Pq Sq ^D .
414: .Sh DATA TRANSFER
415: The example in the previous section can be expanded to build a
416: basic data transfer model.
417: Any information input into one end of the connection will be output
418: to the other end, and input and output can be easily captured in order to
419: emulate file transfer.
420: .Pp
421: Start by using
422: .Nm
423: to listen on a specific port, with output captured into a file:
424: .Pp
425: .Dl $ nc -l 1234 \*(Gt filename.out
426: .Pp
427: Using a second machine, connect to the listening
428: .Nm
429: process, feeding it the file which is to be transferred:
430: .Pp
1.66 jmc 431: .Dl $ nc -N host.example.com 1234 \*(Lt filename.in
1.28 jmc 432: .Pp
433: After the file has been transferred, the connection will close automatically.
434: .Sh TALKING TO SERVERS
435: It is sometimes useful to talk to servers
436: .Dq by hand
437: rather than through a user interface.
438: It can aid in troubleshooting,
439: when it might be necessary to verify what data a server is sending
440: in response to commands issued by the client.
441: For example, to retrieve the home page of a web site:
1.40 jmc 442: .Bd -literal -offset indent
1.55 guenther 443: $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
1.40 jmc 444: .Ed
1.28 jmc 445: .Pp
446: Note that this also displays the headers sent by the web server.
447: They can be filtered, using a tool such as
448: .Xr sed 1 ,
449: if necessary.
450: .Pp
451: More complicated examples can be built up when the user knows the format
452: of requests required by the server.
453: As another example, an email may be submitted to an SMTP server using:
454: .Bd -literal -offset indent
455: $ nc localhost 25 \*(Lt\*(Lt EOF
456: HELO host.example.com
1.44 jmc 457: MAIL FROM:\*(Ltuser@host.example.com\*(Gt
458: RCPT TO:\*(Ltuser2@host.example.com\*(Gt
1.28 jmc 459: DATA
460: Body of email.
461: \&.
462: QUIT
463: EOF
464: .Ed
465: .Sh PORT SCANNING
466: It may be useful to know which ports are open and running services on
467: a target machine.
468: The
469: .Fl z
470: flag can be used to tell
1.22 markus 471: .Nm
1.39 jmc 472: to report open ports,
473: rather than initiate a connection.
1.28 jmc 474: For example:
475: .Bd -literal -offset indent
1.39 jmc 476: $ nc -z host.example.com 20-30
1.28 jmc 477: Connection to host.example.com 22 port [tcp/ssh] succeeded!
478: Connection to host.example.com 25 port [tcp/smtp] succeeded!
479: .Ed
480: .Pp
481: The port range was specified to limit the search to ports 20 \- 30.
482: .Pp
483: Alternatively, it might be useful to know which server software
484: is running, and which versions.
485: This information is often contained within the greeting banners.
486: In order to retrieve these, it is necessary to first make a connection,
487: and then break the connection when the banner has been retrieved.
488: This can be accomplished by specifying a small timeout with the
489: .Fl w
490: flag, or perhaps by issuing a
491: .Qq Dv QUIT
492: command to the server:
493: .Bd -literal -offset indent
494: $ echo "QUIT" | nc host.example.com 20-30
495: SSH-1.99-OpenSSH_3.6.1p2
496: Protocol mismatch.
497: 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
498: .Ed
1.1 deraadt 499: .Sh EXAMPLES
1.37 jmc 500: Open a TCP connection to port 42 of host.example.com, using port 31337 as
1.28 jmc 501: the source port, with a timeout of 5 seconds:
502: .Pp
1.37 jmc 503: .Dl $ nc -p 31337 -w 5 host.example.com 42
1.69 beck 504: .Pp
1.88 ! jsing 505: Open a TCP connection to port 443 of www.example.com, and negotiate TLS with
! 506: any supported TLS protocol version and "compat" ciphers:
! 507: .Pp
! 508: .Dl $ nc -cv -T protocols=all -T ciphers=compat www.example.com 443
! 509: .Pp
1.70 jmc 510: Open a TCP connection to port 443 of www.google.ca, and negotiate TLS.
1.88 ! jsing 511: Check for a different name in the certificate for validation:
1.69 beck 512: .Pp
1.88 ! jsing 513: .Dl $ nc -cv -e adsf.au.doubleclick.net www.google.ca 443
1.28 jmc 514: .Pp
1.37 jmc 515: Open a UDP connection to port 53 of host.example.com:
1.28 jmc 516: .Pp
1.37 jmc 517: .Dl $ nc -u host.example.com 53
1.28 jmc 518: .Pp
1.37 jmc 519: Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
1.28 jmc 520: IP for the local end of the connection:
521: .Pp
1.37 jmc 522: .Dl $ nc -s 10.1.2.3 host.example.com 42
1.28 jmc 523: .Pp
1.51 sobrado 524: Create and listen on a
1.52 sobrado 525: .Ux Ns -domain
1.57 jeremy 526: stream socket:
1.28 jmc 527: .Pp
528: .Dl $ nc -lU /var/tmp/dsocket
1.33 djm 529: .Pp
1.37 jmc 530: Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
1.38 jmc 531: port 8080.
532: This example could also be used by
533: .Xr ssh 1 ;
534: see the
535: .Cm ProxyCommand
536: directive in
537: .Xr ssh_config 5
538: for more information.
1.33 djm 539: .Pp
1.37 jmc 540: .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
1.42 djm 541: .Pp
542: The same example again, this time enabling proxy authentication with username
543: .Dq ruser
544: if the proxy requires it:
545: .Pp
546: .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
1.1 deraadt 547: .Sh SEE ALSO
1.38 jmc 548: .Xr cat 1 ,
549: .Xr ssh 1
1.15 smart 550: .Sh AUTHORS
551: Original implementation by *Hobbit*
1.63 schwarze 552: .Aq Mt hobbit@avian.org .
1.28 jmc 553: .br
554: Rewritten with IPv6 support by
1.63 schwarze 555: .An Eric Jackson Aq Mt ericj@monkey.org .
1.39 jmc 556: .Sh CAVEATS
1.60 lum 557: UDP port scans using the
1.39 jmc 558: .Fl uz
1.60 lum 559: combination of flags will always report success irrespective of
560: the target machine's state.
561: However,
562: in conjunction with a traffic sniffer either on the target machine
563: or an intermediary device,
564: the
565: .Fl uz
566: combination could be useful for communications diagnostics.
567: Note that the amount of UDP traffic generated may be limited either
568: due to hardware resources and/or configuration settings.