readme

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

about genuinely open connections.  Example: "nc -v -w 2 -z target 20-30" will
try connecting to every port between 20 and 30 [inclusive] at the target, and
will likely inform you about an FTP server, telnet server, and mailer along the
way.  The -z switch prevents sending any data to a TCP connection and very
limited probe data to a UDP connection, and is thus useful as a fast scanning
mode just to see what ports the target is listening on.  To limit scanning
speed if desired, -i will insert a delay between each port probe.  There are
some pitfalls with regard to UDP scanning, described later, but in general it
works well.

For each range of ports specified, scanning is normally done downward within
that range.  If the -r switch is used, scanning hops randomly around within
that range and reports open ports as it finds them.  [If you want them listed
in order regardless, pipe standard error through "sort"...]  In addition, if
random mode is in effect, the local source ports are also randomized.  This
prevents netcat from exhibiting any kind of regular pattern in its scanning.
You can exert fairly fine control over your scan by judicious use of -r and
selected port ranges to cover.  If you use -r for a single connection, the
source port will have a random value above 8192, rather than the next one the
kernel would have assigned you.  Note that selecting a specific local port
with -p overrides any local-port randomization.

Many people are interested in testing network connectivity using IP source
routing, even if it's only to make sure their own firewalls are blocking
source-routed packets.  On systems that support it, the -g switch can be used
multiple times [up to 8] to construct a loose-source-routed path for your
connection, and the -G argument positions the "hop pointer" within the list.
If your network allows source-routed traffic in and out, you can test
connectivity to your own services via remote points in the internet.  Note that
although newer BSD-flavor telnets also have source-routing capability, it isn't
clearly documented and the command syntax is somewhat clumsy.  Netcat's
handling of "-g" is modeled after "traceroute".

Netcat tries its best to behave just like "cat".  It currently does nothing to
terminal input modes, and does no end-of-line conversion.  Standard input from
a terminal is read line by line with normal editing characters in effect.  You
can freely suspend out of an interactive connection and resume.  ^C or whatever
your interrupt character is will make netcat close the network connection and
exit.  A switch to place the terminal in raw mode has been considered, but so
far has not been necessary.  You can send raw binary data by reading it out of
a file or piping from another program, so more meaningful effort would be spent
writing an appropriate front-end driver.

Netcat is not an "arbitrary packet generator", but the ability to talk to raw
sockets and/or nit/bpf/dlpi may appear at some point.  Such things are clearly
useful; I refer you to Darren Reed's excellent ip_filter package, which now
includes a tool to construct and send raw packets with any contents you want.

Example uses -- the light side
==============================

Again, this is a very partial list of possibilities, but it may get you to
think up more applications for netcat.  Driving netcat with simple shell or
expect scripts is an easy and flexible way to do fairly complex tasks,
especially if you're not into coding network tools in C.  My coding isn't
particularly strong either [although undoubtedly better after writing this
thing!], so I tend to construct bare-metal tools like this that I can trivially
plug into other applications.  Netcat doubles as a teaching tool -- one can
learn a great deal about more complex network protocols by trying to simulate
them through raw connections!

An example of netcat as a backend for something else is the shell-script
Web browser, which simply asks for the relevant parts of a URL and pipes
"GET /what/ever" into a netcat connection to the server.  I used to do this
with telnet, and had to use calculated sleep times and other stupidity to
kludge around telnet's limitations.  Netcat guarantees that I get the whole
page, and since it transfers all the data unmodified, I can even pull down
binary image files and display them elsewhere later.  Some folks may find the
idea of a shell-script web browser silly and strange, but it starts up and
gets me my info a hell of a lot faster than a GUI browser and doesn't hide
any contents of links and forms and such.  This is included, as scripts/web,
along with several other web-related examples.

Netcat is an obvious replacement for telnet as a tool for talking to daemons.
For example, it is easier to type "nc host 25", talk to someone's mailer, and
just ^C out than having to type ^]c or QUIT as telnet would require you to do.
You can quickly catalog the services on your network by telling netcat to
connect to well-known services and collect greetings, or at least scan for open
ports.  You'll probably want to collect netcat's diagnostic messages in your
output files, so be sure to include standard error in the output using
`>& file' in *csh or `> file 2>&1' in bourne shell.

A scanning example: "echo QUIT | nc -v -w 5 target 20-250 500-600 5990-7000"
will inform you about a target's various well-known TCP servers, including
r-services, X, IRC, and maybe a few you didn't expect.  Sending in QUIT and
using the timeout will almost guarantee that you see some kind of greeting or
error from each service, which usually indicates what it is and what version.
[Beware of the "chargen" port, though...]  SATAN uses exactly this technique to
collect host information, and indeed some of the ideas herein were taken from
the SATAN backend tools.  If you script this up to try every host in your
subnet space and just let it run, you will not only see all the services,
you'll find out about hosts that aren't correctly listed in your DNS.  Then you
can compare new snapshots against old snapshots to see changes.  For going
after particular services, a more intrusive example is in scripts/probe.

Netcat can be used as a simple data transfer agent, and it doesn't really
matter which end is the listener and which end is the client -- input at one
side arrives at the other side as output.  It is helpful to start the listener
at the receiving side with no timeout specified, and then give the sending side
a small timeout.  That way the listener stays listening until you contact it,
and after data stops flowing the client will time out, shut down, and take the
listener with it.  Unless the intervening network is fraught with problems,
this should be completely reliable, and you can always increase the timeout.  A
typical example of something "rsh" is often used for: on one side,

	nc -l -p 1234 | uncompress -c | tar xvfp -

and then on the other side

	tar cfp - /some/dir | compress -c | nc -w 3 othermachine 1234

will transfer the contents of a directory from one machine to another, without
having to worry about .rhosts files, user accounts, or inetd configurations
at either end.  Again, it matters not which is the listener or receiver; the
"tarring" machine could just as easily be running the listener instead.  One
could conceivably use a scheme like this for backups, by having cron-jobs fire
up listeners and backup handlers [which can be restricted to specific addresses
and ports between each other] and pipe "dump" or "tar" on one machine to "dd
of=/dev/tapedrive" on another as usual.  Since netcat returns a nonzero exit
status for a denied listener connection, scripts to handle such tasks could
easily log and reject connect attempts from third parties, and then retry.

Another simple data-transfer example: shipping things to a PC that doesn't have
any network applications yet except a TCP stack and a web browser.  Point the
browser at an arbitrary port on a Unix server by telling it to download
something like http://unixbox:4444/foo, and have a listener on the Unix side
ready to ship out a file when the connect comes in.  The browser may pervert
binary data when told to save the URL, but you can dig the raw data out of
the on-disk cache.

If you build netcat with GAPING_SECURITY_HOLE defined, you can use it as an
"inetd" substitute to test experimental network servers that would otherwise
run under "inetd".  A script or program will have its input and output hooked
to the network the same way, perhaps sans some fancier signal handling.  Given
that most network services do not bind to a particular local address, whether
they are under "inetd" or not, it is possible for netcat avoid the "address
already in use" error by binding to a specific address.  This lets you [as
root, for low ports] place netcat "in the way" of a standard service, since
inbound connections are generally sent to such specifically-bound listeners
first and fall back to the ones bound to "any".  This allows for a one-off
experimental simulation of some service, without having to screw around with
inetd.conf.  Running with -v turned on and collecting a connection log from
standard error is recommended.

Netcat as well can make an outbound connection and then run a program or script
on the originating end, with input and output connected to the same network
port.  This "inverse inetd" capability could enhance the backup-server concept
described above or help facilitate things such as a "network dialback" concept.
The possibilities are many and varied here; if such things are intended as
security mechanisms, it may be best to modify netcat specifically for the
purpose instead of wrapping such functions in scripts.

Speaking of inetd, netcat will function perfectly well *under* inetd as a TCP
connection redirector for inbound services, like a "plug-gw" without the
authentication step.  This is very useful for doing stuff like redirecting
traffic through your firewall out to other places like web servers and mail
hubs, while posing no risk to the firewall machine itself.  Put netcat behind
inetd and tcp_wrappers, perhaps thusly:

	www stream tcp nowait nobody /etc/tcpd /bin/nc -w 3 realwww 80

and you have a simple and effective "application relay" with access control
and logging.  Note use of the wait time as a "safety" in case realwww isn't
reachable or the calling user aborts the connection -- otherwise the relay may
hang there forever.

You can use netcat to generate huge amounts of useless network data for
various performance testing.  For example, doing

	yes AAAAAAAAAAAAAAAAAAAAAA | nc -v -v -l -p 2222 > /dev/null

on one side and then hitting it with

	yes BBBBBBBBBBBBBBBBBBBBBB | nc othermachine 2222 > /dev/null

from another host will saturate your wires with A's and B's.  The "very
verbose" switch usage will tell you how many of each were sent and received
after you interrupt either side.  Using UDP mode produces tremendously MORE
trash per unit time in the form of fragmented 8 Kbyte mobygrams -- enough to
stress-test kernels and network interfaces.  Firing random binary data into
various network servers may help expose bugs in their input handling, which
nowadays is a popular thing to explore.  A simple example data-generator is
given in data/data.c included in this package, along with a small collection
of canned input files to generate various packet contents.  This program is
documented in its beginning comments, but of interest here is using "%r" to
generate random bytes at well-chosen points in a data stream.  If you can
crash your daemon, you likely have a security problem.

The hex dump feature may be useful for debugging odd network protocols,
especially if you don't have any network monitoring equipment handy or aren't
root where you'd need to run "tcpdump" or something.  Bind a listening netcat
to a local port, and have it run a script which in turn runs another netcat
to the real service and captures the hex dump to a log file.  This sets up a
transparent relay between your local port and wherever the real service is.
Be sure that the script-run netcat does *not* use -v, or the extra info it
sends to standard error may confuse the protocol.  Note also that you cannot
have the "listen/exec" netcat do the data capture, since once the connection
arrives it is no longer netcat that is running.

Binding to an arbitrary local port allows you to simulate things like r-service
clients, if you are root locally.  For example, feeding "^@root^@joe^@pwd^@"
[where ^@ is a null, and root/joe could be any other local/remote username
pair] into a "rsh" or "rlogin" server, FROM your port 1023 for example,
duplicates what the server expects to receive.  Thus, you can test for insecure
.rhosts files around your network without having to create new user accounts on
your client machine.  The program data/rservice.c can aid this process by
constructing the "rcmd" protocol bytes.  Doing this also prevents "rshd" from
trying to create that separate standard-error socket and still gives you an
input path, as opposed to the usual action of "rsh -n".  Using netcat for
things like this can be really useful sometimes, because rsh and rlogin
generally want a host *name* as an argument and won't accept IP addresses.  If
your client-end DNS is hosed, as may be true when you're trying to extract
backup sets on to a dumb client, "netcat -n" wins where normal rsh/rlogin is
useless.

If you are unsure that a remote syslogger is working, test it with netcat.
Make a UDP connection to port 514 and type in "<0>message", which should
correspond to "kern.emerg" and cause syslogd to scream into every file it has
open [and possibly all over users' terminals].  You can tame this down by
using a different number and use netcat inside routine scripts to send syslog
messages to places that aren't configured in syslog.conf.  For example,
"echo '<38>message' | nc -w 1 -u loggerhost 514" should send to auth.notice
on loggerhost.  The exact number may vary; check against your syslog.h first.

Netcat provides several ways for you to test your own packet filters.  If you
bind to a port normally protected against outside access and make a connection
to somewhere outside your own network, the return traffic will be coming to
your chosen port from the "outside" and should be blocked.  TCP may get through
if your filter passes all "ack syn", but it shouldn't be even doing that to low
ports on your network.  Remember to test with UDP traffic as well!  If your
filter passes at least outbound source-routed IP packets, bouncing a connection
back to yourself via some gateway outside your network will create "incoming"
traffic with your source address, which should get dropped by a correctly
configured anti-spoofing filter.  This is a "non-test" if you're also dropping
source-routing, but it's good to be able to test for that too.  Any packet
filter worth its salt will be blocking source-routed packets in both
directions, but you never know what interesting quirks you might turn up by