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