Annotation of src/usr.bin/nc/nc.1, Revision 1.10
1.10 ! ian 1: .\" $OpenBSD: nc.1,v 1.9 2000/07/08 15:42:04 aaron 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: .\"
28: .Dd August 1, 1996
1.3 aaron 29: .Dt NC 1
1.4 deraadt 30: .Os
1.1 deraadt 31: .Sh NAME
32: .Nm nc
1.5 millert 33: .Nd "arbitrary TCP and UDP connections and listens"
1.2 deraadt 34: .Sh SYNOPSIS
1.1 deraadt 35: .Nm nc
1.9 aaron 36: .Op Fl lnrtuvz
1.1 deraadt 37: .Op Fl e Ar command
38: .Op Fl g Ar intermediates
39: .Op Fl G Ar hopcount
40: .Op Fl i Ar interval
41: .Op Fl o Ar filename
1.6 aaron 42: .Op Fl p Ar source port
1.1 deraadt 43: .Op Fl s Ar ip address
1.6 aaron 44: .Op Fl w Ar timeout
1.1 deraadt 45: .Op Ar hostname
46: .Op Ar port[s...]
47: .Sh DESCRIPTION
48: The
1.6 aaron 49: .Nm
1.1 deraadt 50: (or
51: .Nm netcat )
52: utility is used for just about anything under the sun
1.7 aaron 53: involving TCP or UDP.
54: It can open TCP connections, send UDP packets,
1.3 aaron 55: listen on arbitrary TCP and UDP ports, do port scanning, and source
1.7 aaron 56: routing.
57: Unlike
1.1 deraadt 58: .Xr telnet 1 ,
1.6 aaron 59: .Nm
1.1 deraadt 60: scripts nicely, and separates error messages onto standard error instead
1.6 aaron 61: of sending them to standard output, as
62: .Xr telnet 1
63: does with some.
1.1 deraadt 64: .Pp
65: Destination ports can be single integers, names as listed in
1.5 millert 66: .Xr services 5 ,
1.7 aaron 67: or ranges.
68: Ranges are in the form nn-mm, and several separate ports and/or
1.1 deraadt 69: ranges may be specified on the command line.
70: .Pp
71: Common uses include:
1.7 aaron 72: .Pp
73: .Bl -bullet -offset indent -compact
1.1 deraadt 74: .It
1.3 aaron 75: simple TCP proxies
1.1 deraadt 76: .It
1.3 aaron 77: shell\-script based HTTP clients and servers
1.1 deraadt 78: .It
79: network daemon testing
80: .It
81: source routing based connectivity testing
82: .It
83: and much, much more
84: .El
85: .Pp
86: The options are as follows:
87: .Bl -tag -width Ds
88: .It Fl e Ar command
89: Execute the specified command, using data from the network for stdin,
1.7 aaron 90: and sending stdout and stderr to the network.
91: This option is only present if
1.6 aaron 92: .Nm
1.1 deraadt 93: was compiled with the GAPING_SECURITY_HOLE compile time option, since it
94: allows users to make arbitrary programs available to anyone on the network.
95: .It Fl g Ar intermediate-host
1.7 aaron 96: Specifies a hop along a loose source routed path.
97: Can be used more than once to build a chain of hop points.
1.1 deraadt 98: .It Fl G Ar pointer
1.7 aaron 99: Positions the
100: .Dq hop counter
101: within the list of machines in the path of a source routed packet.
102: Must be a multiple of 4.
1.1 deraadt 103: .It Fl i Ar seconds
104: Specifies a delay time interval between lines of text sent and received.
105: Also causes a delay time between connections to multiple ports.
106: .It Fl l
107: Is used to specify that
1.6 aaron 108: .Nm
1.1 deraadt 109: should listen for an incoming connection, rather than initiate a
1.7 aaron 110: connection to a remote host.
111: Any hostname/IP address and port arguments
1.1 deraadt 112: restrict the source of inbound connections to only that address and
113: source port.
114: .It Fl n
115: Do not do DNS lookups on any of the specified addresses or hostnames, or
116: names of port numbers from /etc/services.
117: .It Fl o Ar filename
118: Create a hexadecimal log of data transferred in the specified file.
1.7 aaron 119: Each line begins with
120: .Ql <
121: or
122: .Ql > .
123: .Ql <
124: means
125: .Dq from the net
126: and
127: .Ql >
128: means
129: .Dq to the net .
1.1 deraadt 130: .It Fl p Ar port
131: Specifies the source port
1.6 aaron 132: .Nm
1.1 deraadt 133: should use, subject to privilege restrictions and availability.
134: .It Fl r
1.3 aaron 135: Specifies that source and/or destination ports should be chosen semi-randomly
1.1 deraadt 136: instead of sequentially within a range or in the order that the
137: system assigns.
138: .It Fl s Ar hostname/ip-address
1.3 aaron 139: Specifies the IP of the interface which is used to send the packets.
140: On some platforms, this can be used for UDP spoofing by using
141: .Xr ifconfig 8
142: to bring up a dummy interface with the desired source IP address.
1.1 deraadt 143: .It Fl t
144: Causes
1.6 aaron 145: .Nm
1.1 deraadt 146: to send RFC854 DON'T and WON'T responses to RFC854 DO
1.7 aaron 147: and WILL requests.
148: This makes it possible to use
1.6 aaron 149: .Nm
1.7 aaron 150: to script telnet sessions.
151: The presence of this option can be
1.1 deraadt 152: enabled or disabled as a compile-time option.
153: .It Fl u
1.6 aaron 154: Use UDP instead of TCP.
1.1 deraadt 155: On most platforms,
1.6 aaron 156: .Nm
1.1 deraadt 157: will behave as if a connection is established until it receives an
158: ICMP packet indicating that there is no program listening to what it
159: sends.
160: .It Fl v
1.7 aaron 161: Verbose.
162: Cause
1.6 aaron 163: .Nm
1.7 aaron 164: to display connection information.
165: Using
1.3 aaron 166: .Fl v
1.1 deraadt 167: more than once will cause
1.6 aaron 168: .Nm
1.1 deraadt 169: to become even more verbose.
170: .It Fl w Ar timeout
171: Specifies the number of seconds
1.6 aaron 172: .Nm
1.1 deraadt 173: should wait before deciding that
174: an attempt to establish a connection is hopeless.
175: Also used to specify how long to wait for more network data after standard
176: input closes.
177: .It Fl z
178: Specifies that
1.6 aaron 179: .Nm
1.1 deraadt 180: should just scan for listening
1.7 aaron 181: daemons, without sending any data to them.
1.10 ! ian 182: Diagnostic messages about refused connections will not be displayed unless
1.3 aaron 183: .Fl v
184: is specified twice.
1.8 aaron 185: .El
1.1 deraadt 186: .Sh EXAMPLES
187: .Bl -tag -width x
188: .It Li "nc"
189: Wait for the user to type what would normally be command-line
1.10 ! ian 190: arguments on stdin.
1.1 deraadt 191: .It Li "nc example.host 42"
1.7 aaron 192: Open a TCP connection to port 42 of example.host.
193: If the connection
1.1 deraadt 194: fails, do not display any error messages, but simply exit.
195: .It Li "nc -p 31337 example.host 42"
196: Open a TCP connection to port 42 of example.host, and use port 31337
197: as the source port.
198: .It Li "nc -w 5 example.host 42"
1.3 aaron 199: Open a TCP connection to port 42 of example.host, and time out after
1.1 deraadt 200: five seconds while attempting to connect.
201: .It Li "nc -u example.host 53"
202: Send any data from stdin
203: to UDP port 53 of example.host, and display any data returned.
204: .It Li "nc -s 10.1.2.3 example.host 42"
1.3 aaron 205: Open a TCP connection to port 42 of example.host using 10.1.2.3 as the
206: IP for the local end of the connection.
1.1 deraadt 207: .It Li "nc -v example.host 42"
1.3 aaron 208: Open a TCP connection to port 42 of example.host, displaying some
1.1 deraadt 209: diagnostic messages on stderr.
210: .It Li "nc -v -v example.host 42"
1.3 aaron 211: Open a TCP connection to port 42 of example.host, displaying all
1.1 deraadt 212: diagnostic messages on stderr.
213: .It Li "nc -v -z example.host 20-30"
1.3 aaron 214: Attempt to open TCP connections to ports 20 through 30 of
1.1 deraadt 215: example.host, and report which ones
1.6 aaron 216: .Nm
1.1 deraadt 217: was able to connect to.
218: .It Li "nc -v -u -z -w 3 example.host 20-30"
1.3 aaron 219: Send UDP packets to ports 20-30 of example.host, and report which ones
1.1 deraadt 220: did not respond with an ICMP packet after three seconds.
221: .It Li "nc -l -p 3000"
222: Listen on TCP port 3000, and once there is a connection, send stdin to
223: the remote host, and send data from the remote host to stdout.
224: .It Li "echo foobar | nc example.host 1000"
225: Connect to port 1000 of example.host, send the string "foobar"
226: followed by a newline, and move data from port 1000 of example.host to
227: stdout until example.host closes the connection.
228: .El
229: .Sh SEE ALSO
230: .Xr cat 1 ,
1.3 aaron 231: .Xr telnet 1
232: .Pp
233: The
1.1 deraadt 234: .Nm netcat
1.3 aaron 235: .Pa README .
1.1 deraadt 236: .Sh AUTHOR
237: *Hobbit* [hobbit@avian.org]