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