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