Annotation of src/usr.bin/nc/nc.1, Revision 1.56
1.56 ! jeremy 1: .\" $OpenBSD: nc.1,v 1.55 2010/07/25 07:51:39 guenther 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.56 ! jeremy 28: .Dd $Mdocdate: July 25 2010 $
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.31 jmc 36: .Bk -words
1.32 markus 37: .Op Fl 46DdhklnrStUuvz
1.47 jmc 38: .Op Fl I Ar length
1.1 deraadt 39: .Op Fl i Ar interval
1.47 jmc 40: .Op Fl O Ar length
1.42 djm 41: .Op Fl P Ar proxy_username
1.28 jmc 42: .Op Fl p Ar source_port
43: .Op Fl s Ar source_ip_address
1.41 dtucker 44: .Op Fl T Ar ToS
1.54 guenther 45: .Op Fl V Ar rtable
1.6 aaron 46: .Op Fl w Ar timeout
1.33 djm 47: .Op Fl X Ar proxy_protocol
1.28 jmc 48: .Oo Xo
49: .Fl x Ar proxy_address Ns Oo : Ns
1.53 schwarze 50: .Ar port Oc
51: .Xc Oc
1.1 deraadt 52: .Op Ar hostname
1.48 sobrado 53: .Op Ar port
1.31 jmc 54: .Ek
1.1 deraadt 55: .Sh DESCRIPTION
56: The
1.6 aaron 57: .Nm
1.1 deraadt 58: (or
59: .Nm netcat )
1.13 ericj 60: utility is used for just about anything under the sun involving TCP
61: or UDP.
62: It can open TCP connections, send UDP packets, listen on arbitrary
63: TCP and UDP ports, do port scanning, and deal with both IPv4 and
64: IPv6.
1.7 aaron 65: Unlike
1.1 deraadt 66: .Xr telnet 1 ,
1.6 aaron 67: .Nm
1.1 deraadt 68: scripts nicely, and separates error messages onto standard error instead
1.6 aaron 69: of sending them to standard output, as
1.24 pvalchev 70: .Xr telnet 1
1.6 aaron 71: does with some.
1.1 deraadt 72: .Pp
73: Common uses include:
1.7 aaron 74: .Pp
75: .Bl -bullet -offset indent -compact
1.1 deraadt 76: .It
1.3 aaron 77: simple TCP proxies
1.1 deraadt 78: .It
1.28 jmc 79: shell-script based HTTP clients and servers
1.1 deraadt 80: .It
1.13 ericj 81: network daemon testing
1.1 deraadt 82: .It
1.33 djm 83: a SOCKS or HTTP ProxyCommand for
84: .Xr ssh 1
85: .It
1.1 deraadt 86: and much, much more
87: .El
88: .Pp
89: The options are as follows:
90: .Bl -tag -width Ds
1.13 ericj 91: .It Fl 4
92: Forces
93: .Nm
94: to use IPv4 addresses only.
95: .It Fl 6
96: Forces
97: .Nm
98: to use IPv6 addresses only.
1.32 markus 99: .It Fl D
100: Enable debugging on the socket.
1.29 tedu 101: .It Fl d
102: Do not attempt to read from stdin.
1.13 ericj 103: .It Fl h
104: Prints out
105: .Nm
106: help.
1.47 jmc 107: .It Fl I Ar length
1.46 djm 108: Specifies the size of the TCP receive buffer.
1.13 ericj 109: .It Fl i Ar interval
1.1 deraadt 110: Specifies a delay time interval between lines of text sent and received.
111: Also causes a delay time between connections to multiple ports.
1.13 ericj 112: .It Fl k
113: Forces
114: .Nm
1.21 ericj 115: to stay listening for another connection after its current connection
1.13 ericj 116: is completed.
1.28 jmc 117: It is an error to use this option without the
118: .Fl l
119: option.
1.1 deraadt 120: .It Fl l
1.13 ericj 121: Used to specify that
1.6 aaron 122: .Nm
1.13 ericj 123: should listen for an incoming connection rather than initiate a
1.7 aaron 124: connection to a remote host.
1.28 jmc 125: It is an error to use this option in conjunction with the
126: .Fl p ,
127: .Fl s ,
128: or
129: .Fl z
130: options.
1.36 jmc 131: Additionally, any timeouts specified with the
1.35 jmc 132: .Fl w
1.36 jmc 133: option are ignored.
1.1 deraadt 134: .It Fl n
1.21 ericj 135: Do not do any DNS or service lookups on any specified addresses,
136: hostnames or ports.
1.47 jmc 137: .It Fl O Ar length
138: Specifies the size of the TCP send buffer.
1.42 djm 139: .It Fl P Ar proxy_username
140: Specifies a username to present to a proxy server that requires authentication.
141: If no username is specified then authentication will not be attempted.
142: Proxy authentication is only supported for HTTP CONNECT proxies at present.
1.28 jmc 143: .It Fl p Ar source_port
1.1 deraadt 144: Specifies the source port
1.6 aaron 145: .Nm
1.1 deraadt 146: should use, subject to privilege restrictions and availability.
1.28 jmc 147: It is an error to use this option in conjunction with the
148: .Fl l
149: option.
1.1 deraadt 150: .It Fl r
1.13 ericj 151: Specifies that source and/or destination ports should be chosen randomly
152: instead of sequentially within a range or in the order that the system
1.21 ericj 153: assigns them.
1.28 jmc 154: .It Fl S
155: Enables the RFC 2385 TCP MD5 signature option.
156: .It Fl s Ar source_ip_address
1.3 aaron 157: Specifies the IP of the interface which is used to send the packets.
1.56 ! jeremy 158: For
! 159: .Ux Ns -domain
! 160: datagram sockets, specifies the local temporary socket file
! 161: to create and use so that datagrams can be received.
1.28 jmc 162: It is an error to use this option in conjunction with the
163: .Fl l
164: option.
1.41 dtucker 165: .It Fl T Ar ToS
166: Specifies IP Type of Service (ToS) for the connection.
167: Valid values are the tokens
168: .Dq lowdelay ,
169: .Dq throughput ,
170: .Dq reliability ,
171: or an 8-bit hexadecimal value preceded by
172: .Dq 0x .
1.1 deraadt 173: .It Fl t
174: Causes
1.6 aaron 175: .Nm
1.25 jmc 176: to send RFC 854 DON'T and WON'T responses to RFC 854 DO and WILL requests.
1.7 aaron 177: This makes it possible to use
1.6 aaron 178: .Nm
1.7 aaron 179: to script telnet sessions.
1.28 jmc 180: .It Fl U
1.51 sobrado 181: Specifies to use
1.52 sobrado 182: .Ux Ns -domain
183: sockets.
1.1 deraadt 184: .It Fl u
1.13 ericj 185: Use UDP instead of the default option of TCP.
1.56 ! jeremy 186: For
! 187: .Ux Ns -domain
! 188: sockets, use a datagram socket instead of a stream socket.
! 189: If a
! 190: .Ux Ns -domain
! 191: socket is used, a temporary receiving socket is created in
! 192: .Pa /tmp
! 193: unless the
! 194: .Fl s
! 195: flag is given.
1.54 guenther 196: .It Fl V Ar rtable
197: Set the routing table to be used.
1.50 jmc 198: The default is 0.
1.1 deraadt 199: .It Fl v
1.13 ericj 200: Have
1.6 aaron 201: .Nm
1.13 ericj 202: give more verbose output.
1.26 jmc 203: .It Fl w Ar timeout
204: If a connection and stdin are idle for more than
205: .Ar timeout
206: seconds, then the connection is silently closed.
207: The
208: .Fl w
209: flag has no effect on the
210: .Fl l
211: option, i.e.\&
212: .Nm
213: will listen forever for a connection, with or without the
214: .Fl w
215: flag.
216: The default is no timeout.
1.43 jmc 217: .It Fl X Ar proxy_protocol
1.28 jmc 218: Requests that
219: .Nm
1.33 djm 220: should use the specified protocol when talking to the proxy server.
221: Supported protocols are
222: .Dq 4
223: (SOCKS v.4),
224: .Dq 5
225: (SOCKS v.5)
226: and
227: .Dq connect
228: (HTTPS proxy).
229: If the protocol is not specified, SOCKS version 5 is used.
1.28 jmc 230: .It Xo
231: .Fl x Ar proxy_address Ns Oo : Ns
232: .Ar port Oc
233: .Xc
1.19 jakob 234: Requests that
235: .Nm
236: should connect to
237: .Ar hostname
1.33 djm 238: using a proxy at
1.28 jmc 239: .Ar proxy_address
240: and
241: .Ar port .
242: If
243: .Ar port
1.33 djm 244: is not specified, the well-known port for the proxy protocol is used (1080
245: for SOCKS, 3128 for HTTPS).
1.1 deraadt 246: .It Fl z
247: Specifies that
1.6 aaron 248: .Nm
1.13 ericj 249: should just scan for listening daemons, without sending any data to them.
1.28 jmc 250: It is an error to use this option in conjunction with the
251: .Fl l
252: option.
253: .El
1.35 jmc 254: .Pp
255: .Ar hostname
256: can be a numerical IP address or a symbolic hostname
257: (unless the
258: .Fl n
259: option is given).
260: In general, a hostname must be specified,
261: unless the
262: .Fl l
263: option is given
264: (in which case the local host is used).
265: .Pp
1.48 sobrado 266: .Ar port
267: can be a single integer or a range of ports.
1.35 jmc 268: Ranges are in the form nn-mm.
269: In general,
270: a destination port must be specified,
271: unless the
272: .Fl U
273: option is given
274: (in which case a socket must be specified).
1.28 jmc 275: .Sh CLIENT/SERVER MODEL
276: It is quite simple to build a very basic client/server model using
277: .Nm .
278: On one console, start
279: .Nm
280: listening on a specific port for a connection.
281: For example:
282: .Pp
283: .Dl $ nc -l 1234
284: .Pp
285: .Nm
286: is now listening on port 1234 for a connection.
287: On a second console
288: .Pq or a second machine ,
289: connect to the machine and port being listened on:
290: .Pp
291: .Dl $ nc 127.0.0.1 1234
292: .Pp
293: There should now be a connection between the ports.
294: Anything typed at the second console will be concatenated to the first,
295: and vice-versa.
296: After the connection has been set up,
297: .Nm
298: does not really care which side is being used as a
299: .Sq server
300: and which side is being used as a
301: .Sq client .
302: The connection may be terminated using an
303: .Dv EOF
304: .Pq Sq ^D .
305: .Sh DATA TRANSFER
306: The example in the previous section can be expanded to build a
307: basic data transfer model.
308: Any information input into one end of the connection will be output
309: to the other end, and input and output can be easily captured in order to
310: emulate file transfer.
311: .Pp
312: Start by using
313: .Nm
314: to listen on a specific port, with output captured into a file:
315: .Pp
316: .Dl $ nc -l 1234 \*(Gt filename.out
317: .Pp
318: Using a second machine, connect to the listening
319: .Nm
320: process, feeding it the file which is to be transferred:
321: .Pp
322: .Dl $ nc host.example.com 1234 \*(Lt filename.in
323: .Pp
324: After the file has been transferred, the connection will close automatically.
325: .Sh TALKING TO SERVERS
326: It is sometimes useful to talk to servers
327: .Dq by hand
328: rather than through a user interface.
329: It can aid in troubleshooting,
330: when it might be necessary to verify what data a server is sending
331: in response to commands issued by the client.
332: For example, to retrieve the home page of a web site:
1.40 jmc 333: .Bd -literal -offset indent
1.55 guenther 334: $ printf "GET / HTTP/1.0\er\en\er\en" | nc host.example.com 80
1.40 jmc 335: .Ed
1.28 jmc 336: .Pp
337: Note that this also displays the headers sent by the web server.
338: They can be filtered, using a tool such as
339: .Xr sed 1 ,
340: if necessary.
341: .Pp
342: More complicated examples can be built up when the user knows the format
343: of requests required by the server.
344: As another example, an email may be submitted to an SMTP server using:
345: .Bd -literal -offset indent
346: $ nc localhost 25 \*(Lt\*(Lt EOF
347: HELO host.example.com
1.44 jmc 348: MAIL FROM:\*(Ltuser@host.example.com\*(Gt
349: RCPT TO:\*(Ltuser2@host.example.com\*(Gt
1.28 jmc 350: DATA
351: Body of email.
352: \&.
353: QUIT
354: EOF
355: .Ed
356: .Sh PORT SCANNING
357: It may be useful to know which ports are open and running services on
358: a target machine.
359: The
360: .Fl z
361: flag can be used to tell
1.22 markus 362: .Nm
1.39 jmc 363: to report open ports,
364: rather than initiate a connection.
1.28 jmc 365: For example:
366: .Bd -literal -offset indent
1.39 jmc 367: $ nc -z host.example.com 20-30
1.28 jmc 368: Connection to host.example.com 22 port [tcp/ssh] succeeded!
369: Connection to host.example.com 25 port [tcp/smtp] succeeded!
370: .Ed
371: .Pp
372: The port range was specified to limit the search to ports 20 \- 30.
373: .Pp
374: Alternatively, it might be useful to know which server software
375: is running, and which versions.
376: This information is often contained within the greeting banners.
377: In order to retrieve these, it is necessary to first make a connection,
378: and then break the connection when the banner has been retrieved.
379: This can be accomplished by specifying a small timeout with the
380: .Fl w
381: flag, or perhaps by issuing a
382: .Qq Dv QUIT
383: command to the server:
384: .Bd -literal -offset indent
385: $ echo "QUIT" | nc host.example.com 20-30
386: SSH-1.99-OpenSSH_3.6.1p2
387: Protocol mismatch.
388: 220 host.example.com IMS SMTP Receiver Version 0.84 Ready
389: .Ed
1.1 deraadt 390: .Sh EXAMPLES
1.37 jmc 391: Open a TCP connection to port 42 of host.example.com, using port 31337 as
1.28 jmc 392: the source port, with a timeout of 5 seconds:
393: .Pp
1.37 jmc 394: .Dl $ nc -p 31337 -w 5 host.example.com 42
1.28 jmc 395: .Pp
1.37 jmc 396: Open a UDP connection to port 53 of host.example.com:
1.28 jmc 397: .Pp
1.37 jmc 398: .Dl $ nc -u host.example.com 53
1.28 jmc 399: .Pp
1.37 jmc 400: Open a TCP connection to port 42 of host.example.com using 10.1.2.3 as the
1.28 jmc 401: IP for the local end of the connection:
402: .Pp
1.37 jmc 403: .Dl $ nc -s 10.1.2.3 host.example.com 42
1.28 jmc 404: .Pp
1.51 sobrado 405: Create and listen on a
1.52 sobrado 406: .Ux Ns -domain
407: socket:
1.28 jmc 408: .Pp
409: .Dl $ nc -lU /var/tmp/dsocket
1.33 djm 410: .Pp
1.37 jmc 411: Connect to port 42 of host.example.com via an HTTP proxy at 10.2.3.4,
1.38 jmc 412: port 8080.
413: This example could also be used by
414: .Xr ssh 1 ;
415: see the
416: .Cm ProxyCommand
417: directive in
418: .Xr ssh_config 5
419: for more information.
1.33 djm 420: .Pp
1.37 jmc 421: .Dl $ nc -x10.2.3.4:8080 -Xconnect host.example.com 42
1.42 djm 422: .Pp
423: The same example again, this time enabling proxy authentication with username
424: .Dq ruser
425: if the proxy requires it:
426: .Pp
427: .Dl $ nc -x10.2.3.4:8080 -Xconnect -Pruser host.example.com 42
1.1 deraadt 428: .Sh SEE ALSO
1.38 jmc 429: .Xr cat 1 ,
430: .Xr ssh 1
1.15 smart 431: .Sh AUTHORS
432: Original implementation by *Hobbit*
433: .Aq hobbit@avian.org .
1.28 jmc 434: .br
435: Rewritten with IPv6 support by
436: .An Eric Jackson Aq ericj@monkey.org .
1.39 jmc 437: .Sh CAVEATS
438: UDP port scans will always succeed
439: (i.e. report the port as open),
440: rendering the
441: .Fl uz
442: combination of flags relatively useless.