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