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