   .       .         
   \`-"'"-'/
    } 6 6 {    
   ==. Y ,==   
     /^^^\  .
    /     \  )           
   (  )-(  )/     _
   -""---""---   /
  /   Ncat    \_/
 (     ____
  \_.=|____E


README for Ncat V0.10rc1
------------------------

Ncat is a reimplementation of the currently splintered 
and reasonably unmaintained Netcat family. Ncat will
do pretty much everything that all the other Netcat's
do; however it does this all in one handy place. Plus
has the added benefit of spanky new features.

Ncat was designed with the original Ncat interface
in mind. Rather than replacing the old Netcat interface
with a brand new and subsequently more convoluted interface
the Ncat interface is clean and simple to use.

Ncat is a subset of features from the original Netcat but with
a complete overhaul. New features and a combination of the Netcat
families features (IPv6 support, SSL support, etc) 

The port scanning support has been entirely removed from Ncat. 
I know of a better port scanner out there already :)

Under the hood of Ncat, there is IPv4, IPv6 support as well
as support for TCP and UDP in both listen and connect modes.
There is also SSL support for both listen and connect operations
too. As well as a new "Connection Brokering" feature. This enables
two (or more.) hosts to connect that perhaps previously were unable
to directly connect to each other.

For example: Host A can connect to Host B but not Host C
             Host C can connect to Host B but not Host A

(ASCII diagram warning)

[HostA] <------> [HostB-with-Ncat-Broker] <------> [HostC]

Then connection brokering will allow you to sneak a connection
through between Host A and Host C via Host B without the trouble
of having to have SOCKS support, etc.

The Ncat process owner can also see the current connection live 
as it happens. This is similar to a third party style wire tap. 
This can be disabled with a command line option passed to the 
Ncat process that is doing the brokering (--sendonly)

Ncat has support for HTTP CONNECT via an HTTP proxy server. It
will also connect via a SOCKS4 server and is very flexible
in terms of how it shuffles your data around.

Ncat can also spawn it's own it's own SOCKS4 server for 
your own relaying requirements.

Ncat can also execute a program and will handle the I/O for this
applications data over the socket. Ncat will fully handle the I/O 
for the executed program. This has the added benefit of "adding" 
networking support to applications that currently do not have 
networking support included already.

For example, you could:

./ncat --exec "/bin/bash" -l 5000

WARNING: This is exceptionally dangerous as it leaves an open
shell sitting accessible to the whole Internet. See the --allow,
--deny and allowfile/denyfile options later on for securing your
Ncat process.

You could also use Ncat as a TCP to UDP "gender changer". If 
you have an application that only makes TCP connections, but
you need UDP support. Spawn an Ncat process to listen on a
TCP port and in true 'redir' style, it will redirect the 
TCP connection out to the final destination over UDP.

Ncat can be used as an all purpose TCP and UDP 'redir'
for redirecting data.

$ ncat --exec "./ncat www.example.com 80" -l 8888

This command binds Ncat to the local machine on port 8888,
connections to port 8888 are then shuffled off to
port 80 of www.example.com -- this may also be useful as 
a "host hiding" system. Similar to SOCKS4 but without any
of the hassle of having SOCKS support in the application.

SOCKS4 support in Ncat is supported both ways. SOCKS4
client support and SOCKS4 server support.

$ ncat --socks4-server -l 5001

Ncat will start a SOCKS4 server on port 5001.

WARNING: This will be a publically accessible
SOCKS4 server and potentially cause you problems
with regard to your sites security.

To prevent unauthorised access to ANY Ncat process
that is listening on a port, the --allow, --deny 
and --allowfile and --denyfile options are included.

Therefore, a minor change to our parameters issued 
to Ncat to include security concerns:

./ncat --allow 127.0.0.1/32 --socks4-server -l 5001

The allow and deny family of functions accept IP
addresses in a number of different formats for
your maximum flexibility:

ip.ip.ip.ip
ip.ip.ip.ip/cidr
ip.ip.ip.ip:nm.nm.nm.nm
ip.ip.ip.*
ip.ip.*.*
ip.*.*.*

These IP addresses may also be used in a file delimited
by newlines. An example ACL is included in docs/examples/
called iplist. Comments start with a #.

<INSERT MORE DOCUMENTATION HERE>


Acknowledgements
----------------

First and foremost: Thanks go out to Fyodor for making this great
experience just that bit more pleasurable; for all concerned.

Thanks to Google and the Summer of Code team. The point of
contact with Google being Chris DiBona, Natalie and Jude. Thanks to
you all for making this possible. Without whom I wouldn't even 
be writing this.

Also, thank you to all the folks from #C on Undernet who kicked 
me in the right direction when things were at their most broken.

Thanks to Jan for all her support and, well, general tolerance. :)

Thanks to all the people who've submitted bug reports, given me 
ideas, helped me test Ncat or just given me general encouragement.
It is most appreciated.

Finally, thanks to Hobbit for writing the original Netcat. It rocks.

--Chris Gibson, <chris@linuxops.net>
