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