readme

very comprehensive example, windows WDM driver development ex The use of drive technology can s

Netcat 1.10
===========							   /\_/\
								  / 0 0 \
Netcat is a simple Unix utility which reads and writes data	 ====v====
across network connections, using TCP or UDP protocol.		  \  W  /
It is designed to be a reliable "back-end" tool that can	  |     |     _
be used directly or easily driven by other programs and		  / ___ \    /
scripts.  At the same time, it is a feature-rich network	 / /   \ \  |
debugging and exploration tool, since it can create almost	(((-----)))-'
any kind of connection you would need and has several		 /
interesting built-in capabilities.  Netcat, or "nc" as the	(      ___
actual program is named, should have been supplied long ago	 \__.=|___E
as another one of those cryptic but standard Unix tools.	        /

In the simplest usage, "nc host port" creates a TCP connection to the given
port on the given target host.  Your standard input is then sent to the host,
and anything that comes back across the connection is sent to your standard
output.  This continues indefinitely, until the network side of the connection
shuts down.  Note that this behavior is different from most other applications
which shut everything down and exit after an end-of-file on the standard input.

Netcat can also function as a server, by listening for inbound connections
on arbitrary ports and then doing the same reading and writing.  With minor
limitations, netcat doesn't really care if it runs in "client" or "server"
mode -- it still shovels data back and forth until there isn't any more left.
In either mode, shutdown can be forced after a configurable time of inactivity
on the network side.

And it can do this via UDP too, so netcat is possibly the "udp telnet-like"
application you always wanted for testing your UDP-mode servers.  UDP, as the
"U" implies, gives less reliable data transmission than TCP connections and
some systems may have trouble sending large amounts of data that way, but it's
still a useful capability to have.

You may be asking "why not just use telnet to connect to arbitrary ports?"
Valid question, and here are some reasons.  Telnet has the "standard input
EOF" problem, so one must introduce calculated delays in driving scripts to
allow network output to finish.  This is the main reason netcat stays running
until the *network* side closes.  Telnet also will not transfer arbitrary
binary data, because certain characters are interpreted as telnet options and
are thus removed from the data stream.  Telnet also emits some of its
diagnostic messages to standard output, where netcat keeps such things
religiously separated from its *output* and will never modify any of the real
data in transit unless you *really* want it to.  And of course telnet is
incapable of listening for inbound connections, or using UDP instead.  Netcat
doesn't have any of these limitations, is much smaller and faster than telnet,
and has many other advantages.

Some of netcat's major features are:

	Outbound or inbound connections, TCP or UDP, to or from any ports
	Full DNS forward/reverse checking, with appropriate warnings
	Ability to use any local source port
	Ability to use any locally-configured network source address
	Built-in port-scanning capabilities, with randomizer
	Built-in loose source-routing capability
	Can read command line arguments from standard input
	Slow-send mode, one line every N seconds
	Hex dump of transmitted and received data
	Optional ability to let another program service established connections
	Optional telnet-options responder

Efforts have been made to have netcat "do the right thing" in all its various
modes.  If you believe that it is doing the wrong thing under whatever
circumstances, please notify me and tell me how you think it should behave.
If netcat is not able to do some task you think up, minor tweaks to the code
will probably fix that.  It provides a basic and easily-modified template for
writing other network applications, and I certainly encourage people to make
custom mods and send in any improvements they make to it.  This is the second
release; the overall differences from 1.00 are relatively minor and have mostly
to do with portability and bugfixes.  Many people provided greatly appreciated
fixes and comments on the 1.00 release.  Continued feedback from the Internet
community is always welcome!

Netcat is entirely my own creation, although plenty of other code was used as
examples.  It is freely given away to the Internet community in the hope that
it will be useful, with no restrictions except giving credit where it is due.
No GPLs, Berkeley copyrights or any of that nonsense.  The author assumes NO
responsibility for how anyone uses it.  If netcat makes you rich somehow and
you're feeling generous, mail me a check.  If you are affiliated in any way
with Microsoft Network, get a life.  Always ski in control.  Comments,
questions, and patches to [e-mail].

Building
========

Compiling is fairly straightforward.  Examine the Makefile for a SYSTYPE that
matches yours, and do "make <systype>".  The executable "nc" should appear.
If there is no relevant SYSTYPE section, try "generic".  If you create new
sections for generic.h and Makefile to support another platform, please follow
the given format and mail back the diffs.

There are a couple of other settable #defines in netcat.c, which you can
include as DFLAGS="-DTHIS -DTHAT" to your "make" invocation without having to
edit the Makefile.  See the following discussions for what they are and do.

If you want to link against the resolver library on SunOS [recommended] and
you have BIND 4.9.x, you may need to change XLIBS=-lresolv in the Makefile to
XLIBS="-lresolv -l44bsd".

Linux sys/time.h does not really support presetting of FD_SETSIZE; a harmless
warning is issued.

Some systems may warn about pointer types for signal().  No problem, though.

Exploration of features
=======================

Where to begin?  Netcat is at the same time so simple and versatile, it's like
trying to describe everything you can do with your Swiss Army knife.  This will
go over the basics; you should also read the usage examples and notes later on
which may give you even more ideas about what this sort of tool is good for.

If no command arguments are given at all, netcat asks for them, reads a line
from standard input, and breaks it up into arguments internally.  This can be
useful when driving netcat from certain types of scripts, with the side effect
of hiding your command line arguments from "ps" displays.

The host argument can be a name or IP address.  If -n is specified, netcat
will only accept numeric IP addresses and do no DNS lookups for anything.  If
-n is not given and -v is turned on, netcat will do a full forward and reverse
name and address lookup for the host, and warn you about the all-too-common
problem of mismatched names in the DNS.  This often takes a little longer for
connection setup, but is useful to know about.  There are circumstances under
which this can *save* time, such as when you want to know the name for some IP
address and also connect there.  Netcat will just tell you all about it, saving
the manual steps of looking up the hostname yourself.  Normally mismatch-
checking is case-insensitive per the DNS spec, but you can define ANAL at
compile time to make it case-sensitive -- sometimes useful for uncovering minor
errors in your own DNS files while poking around your networks.

A port argument is required for outbound connections, and can be numeric or a
name as listed in /etc/services.  If -n is specified, only numeric arguments
are valid.  Special syntax and/or more than one port argument cause different
behavior -- see details below about port-scanning.

The -v switch controls the verbosity level of messages sent to standard error.
You will probably want to run netcat most of the time with -v turned on, so you
can see info about the connections it is trying to make.  You will probably
also want to give a smallish -w argument, which limits the time spent trying to
make a connection.  I usually alias "nc" to "nc -v -w 3", which makes it
function just about the same for things I would otherwise use telnet to do.
The timeout is easily changed by a subsequent -w argument which overrides the
earlier one.  Specifying -v more than once makes diagnostic output MORE
verbose.  If -v is not specified at all, netcat silently does its work unless
some error happens, whereupon it describes the error and exits with a nonzero
status.  Refused network connections are generally NOT considered to be errors,
unless you only asked for a single TCP port and it was refused.

Note that -w also sets the network inactivity timeout.  This does not have any
effect until standard input closes, but then if nothing further arrives from
the network in the next <timeout> seconds, netcat tries to read the net once
more for good measure, and then closes and exits.  There are a lot of network
services now that accept a small amount of input and return a large amount of
output, such as Gopher and Web servers, which is the main reason netcat was
written to "block" on the network staying open rather than standard input.
Handling the timeout this way gives uniform behavior with network servers that
*don't* close by themselves until told to.

UDP connections are opened instead of TCP when -u is specified.  These aren't
really "connections" per se since UDP is a connectionless protocol, although
netcat does internally use the "connected UDP socket" mechanism that most
kernels support.  Although netcat claims that an outgoing UDP connection is
"open" immediately, no data is sent until something is read from standard
input.  Only thereafter is it possible to determine whether there really is a
UDP server on the other end, and often you just can't tell.  Most UDP protocols
use timeouts and retries to do their thing and in many cases won't bother
answering at all, so you should specify a timeout and hope for the best.  You
will get more out of UDP connections if standard input is fed from a source
of data that looks like various kinds of server requests.

To obtain a hex dump file of the data sent either way, use "-o logfile".  The
dump lines begin with "<" or ">" to respectively indicate "from the net" or
"to the net", and contain the total count per direction, and hex and ascii
representations of the traffic.  Capturing a hex dump naturally slows netcat
down a bit, so don't use it where speed is critical.

Netcat can bind to any local port, subject to privilege restrictions and ports
that are already in use.  It is also possible to use a specific local network
source address if it is that of a network interface on your machine.  [Note:
this does not work correctly on all platforms.]  Use "-p portarg" to grab a
specific local port, and "-s ip-addr" or "-s name" to have that be your source
IP address.  This is often referred to as "anchoring the socket".  Root users
can grab any unused source port including the "reserved" ones less than 1024.
Absence of -p will bind to whatever unused port the system gives you, just like
any other normal client connection, unless you use -r [see below].

Listen mode will cause netcat to wait for an inbound connection, and then the
same data transfer happens.  Thus, you can do "nc -l -p 1234 < filename" and
when someone else connects to your port 1234, the file is sent to them whether
they wanted it or not.  Listen mode is generally used along with a local port
argument -- this is required for UDP mode, while TCP mode can have the system
assign one and tell you what it is if -v is turned on.  If you specify a target
host and optional port in listen mode, netcat will accept an inbound connection
only from that host and if you specify one, only from that foreign source port.
In verbose mode you'll be informed about the inbound connection, including what
address and port it came from, and since listening on "any" applies to several
possibilities, which address it came *to* on your end.  If the system supports
IP socket options, netcat will attempt to retrieve any such options from an
inbound connection and print them out in hex.

If netcat is compiled with -DGAPING_SECURITY_HOLE, the -e argument specifies
a program to exec after making or receiving a successful connection.  In the
listening mode, this works similarly to "inetd" but only for a single instance.
Use with GREAT CARE.  This piece of the code is normally not enabled; if you
know what you're doing, have fun.  This hack also works in UDP mode.  Note that
you can only supply -e with the name of the program, but no arguments.  If you
want to launch something with an argument list, write a two-line wrapper script
or just use inetd like always.

If netcat is compiled with -DTELNET, the -t argument enables it to respond
to telnet option negotiation [always in the negative, i.e. DONT or WONT].
This allows it to connect to a telnetd and get past the initial negotiation
far enough to get a login prompt from the server.  Since this feature has
the potential to modify the data stream, it is not enabled by default.  You
have to understand why you might need this and turn on the #define yourself.

Data from the network connection is always delivered to standard output as
efficiently as possible, using large 8K reads and writes.  Standard input is
normally sent to the net the same way, but the -i switch specifies an "interval
time" which slows this down considerably.  Standard input is still read in
large batches, but netcat then tries to find where line breaks exist and sends
one line every interval time.  Note that if standard input is a terminal, data
is already read line by line, so unless you make the -i interval rather long,
what you type will go out at a fairly normal rate.  -i is really designed
for use when you want to "measure out" what is read from files or pipes.

Port-scanning is a popular method for exploring what's out there.  Netcat
accepts its commands with options first, then the target host, and everything
thereafter is interpreted as port names or numbers, or ranges of ports in M-N
syntax.  CAVEAT: some port names in /etc/services contain hyphens -- netcat
currently will not correctly parse those, so specify ranges using numbers if
you can.  If more than one port is thus specified, netcat connects to *all* of
them, sending the same batch of data from standard input [up to 8K worth] to
each one that is successfully connected to.  Specifying multiple ports also
suppresses diagnostic messages about refused connections, unless -v is
specified twice for "more verbosity".  This way you normally get notified only