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