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
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.