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