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