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