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