Home | History | Annotate | only in /external/netcat
Up to higher level directory
NameDateSize
Android.mk31-Jul-2010324
Changelog31-Jul-20103.8K
CleanSpec.mk31-Jul-20102.2K
data/31-Jul-2010
generic.h31-Jul-201011.4K
Makefile.dist31-Jul-20103.7K
MODULE_LICENSE_PUBLIC_DOMAIN31-Jul-20100
nc31-Jul-201027.6K
netcat.blurb31-Jul-20102.6K
netcat.c31-Jul-201057.2K
NOTICE31-Jul-2010579
README31-Jul-201059.4K
scripts/31-Jul-2010
stupidh31-Jul-20108.3K

README

      1 Netcat 1.10
      2 ===========							   /\_/\
      3 								  / 0 0 \
      4 Netcat is a simple Unix utility which reads and writes data	 ====v====
      5 across network connections, using TCP or UDP protocol.		  \  W  /
      6 It is designed to be a reliable "back-end" tool that can	  |     |     _
      7 be used directly or easily driven by other programs and		  / ___ \    /
      8 scripts.  At the same time, it is a feature-rich network	 / /   \ \  |
      9 debugging and exploration tool, since it can create almost	(((-----)))-'
     10 any kind of connection you would need and has several		 /
     11 interesting built-in capabilities.  Netcat, or "nc" as the	(      ___
     12 actual program is named, should have been supplied long ago	 \__.=|___E
     13 as another one of those cryptic but standard Unix tools.	        /
     14 
     15 In the simplest usage, "nc host port" creates a TCP connection to the given
     16 port on the given target host.  Your standard input is then sent to the host,
     17 and anything that comes back across the connection is sent to your standard
     18 output.  This continues indefinitely, until the network side of the connection
     19 shuts down.  Note that this behavior is different from most other applications
     20 which shut everything down and exit after an end-of-file on the standard input.
     21 
     22 Netcat can also function as a server, by listening for inbound connections
     23 on arbitrary ports and then doing the same reading and writing.  With minor
     24 limitations, netcat doesn't really care if it runs in "client" or "server"
     25 mode -- it still shovels data back and forth until there isn't any more left.
     26 In either mode, shutdown can be forced after a configurable time of inactivity
     27 on the network side.
     28 
     29 And it can do this via UDP too, so netcat is possibly the "udp telnet-like"
     30 application you always wanted for testing your UDP-mode servers.  UDP, as the
     31 "U" implies, gives less reliable data transmission than TCP connections and
     32 some systems may have trouble sending large amounts of data that way, but it's
     33 still a useful capability to have.
     34 
     35 You may be asking "why not just use telnet to connect to arbitrary ports?"
     36 Valid question, and here are some reasons.  Telnet has the "standard input
     37 EOF" problem, so one must introduce calculated delays in driving scripts to
     38 allow network output to finish.  This is the main reason netcat stays running
     39 until the *network* side closes.  Telnet also will not transfer arbitrary
     40 binary data, because certain characters are interpreted as telnet options and
     41 are thus removed from the data stream.  Telnet also emits some of its
     42 diagnostic messages to standard output, where netcat keeps such things
     43 religiously separated from its *output* and will never modify any of the real
     44 data in transit unless you *really* want it to.  And of course telnet is
     45 incapable of listening for inbound connections, or using UDP instead.  Netcat
     46 doesn't have any of these limitations, is much smaller and faster than telnet,
     47 and has many other advantages.
     48 
     49 Some of netcat's major features are:
     50 
     51 	Outbound or inbound connections, TCP or UDP, to or from any ports
     52 	Full DNS forward/reverse checking, with appropriate warnings
     53 	Ability to use any local source port
     54 	Ability to use any locally-configured network source address
     55 	Built-in port-scanning capabilities, with randomizer
     56 	Built-in loose source-routing capability
     57 	Can read command line arguments from standard input
     58 	Slow-send mode, one line every N seconds
     59 	Hex dump of transmitted and received data
     60 	Optional ability to let another program service established connections
     61 	Optional telnet-options responder
     62 
     63 Efforts have been made to have netcat "do the right thing" in all its various
     64 modes.  If you believe that it is doing the wrong thing under whatever
     65 circumstances, please notify me and tell me how you think it should behave.
     66 If netcat is not able to do some task you think up, minor tweaks to the code
     67 will probably fix that.  It provides a basic and easily-modified template for
     68 writing other network applications, and I certainly encourage people to make
     69 custom mods and send in any improvements they make to it.  This is the second
     70 release; the overall differences from 1.00 are relatively minor and have mostly
     71 to do with portability and bugfixes.  Many people provided greatly appreciated
     72 fixes and comments on the 1.00 release.  Continued feedback from the Internet
     73 community is always welcome!
     74 
     75 Netcat is entirely my own creation, although plenty of other code was used as
     76 examples.  It is freely given away to the Internet community in the hope that
     77 it will be useful, with no restrictions except giving credit where it is due.
     78 No GPLs, Berkeley copyrights or any of that nonsense.  The author assumes NO
     79 responsibility for how anyone uses it.  If netcat makes you rich somehow and
     80 you're feeling generous, mail me a check.  If you are affiliated in any way
     81 with Microsoft Network, get a life.  Always ski in control.  Comments,
     82 questions, and patches to hobbit (a] avian.org.
     83 
     84 Building
     85 ========
     86 
     87 Compiling is fairly straightforward.  Examine the Makefile for a SYSTYPE that
     88 matches yours, and do "make <systype>".  The executable "nc" should appear.
     89 If there is no relevant SYSTYPE section, try "generic".  If you create new
     90 sections for generic.h and Makefile to support another platform, please follow
     91 the given format and mail back the diffs.
     92 
     93 There are a couple of other settable #defines in netcat.c, which you can
     94 include as DFLAGS="-DTHIS -DTHAT" to your "make" invocation without having to
     95 edit the Makefile.  See the following discussions for what they are and do.
     96 
     97 If you want to link against the resolver library on SunOS [recommended] and
     98 you have BIND 4.9.x, you may need to change XLIBS=-lresolv in the Makefile to
     99 XLIBS="-lresolv -l44bsd".
    100 
    101 Linux sys/time.h does not really support presetting of FD_SETSIZE; a harmless
    102 warning is issued.
    103 
    104 Some systems may warn about pointer types for signal().  No problem, though.
    105 
    106 Exploration of features
    107 =======================
    108 
    109 Where to begin?  Netcat is at the same time so simple and versatile, it's like
    110 trying to describe everything you can do with your Swiss Army knife.  This will
    111 go over the basics; you should also read the usage examples and notes later on
    112 which may give you even more ideas about what this sort of tool is good for.
    113 
    114 If no command arguments are given at all, netcat asks for them, reads a line
    115 from standard input, and breaks it up into arguments internally.  This can be
    116 useful when driving netcat from certain types of scripts, with the side effect
    117 of hiding your command line arguments from "ps" displays.
    118 
    119 The host argument can be a name or IP address.  If -n is specified, netcat
    120 will only accept numeric IP addresses and do no DNS lookups for anything.  If
    121 -n is not given and -v is turned on, netcat will do a full forward and reverse
    122 name and address lookup for the host, and warn you about the all-too-common
    123 problem of mismatched names in the DNS.  This often takes a little longer for
    124 connection setup, but is useful to know about.  There are circumstances under
    125 which this can *save* time, such as when you want to know the name for some IP
    126 address and also connect there.  Netcat will just tell you all about it, saving
    127 the manual steps of looking up the hostname yourself.  Normally mismatch-
    128 checking is case-insensitive per the DNS spec, but you can define ANAL at
    129 compile time to make it case-sensitive -- sometimes useful for uncovering minor
    130 errors in your own DNS files while poking around your networks.
    131 
    132 A port argument is required for outbound connections, and can be numeric or a
    133 name as listed in /etc/services.  If -n is specified, only numeric arguments
    134 are valid.  Special syntax and/or more than one port argument cause different
    135 behavior -- see details below about port-scanning.
    136 
    137 The -v switch controls the verbosity level of messages sent to standard error.
    138 You will probably want to run netcat most of the time with -v turned on, so you
    139 can see info about the connections it is trying to make.  You will probably
    140 also want to give a smallish -w argument, which limits the time spent trying to
    141 make a connection.  I usually alias "nc" to "nc -v -w 3", which makes it
    142 function just about the same for things I would otherwise use telnet to do.
    143 The timeout is easily changed by a subsequent -w argument which overrides the
    144 earlier one.  Specifying -v more than once makes diagnostic output MORE
    145 verbose.  If -v is not specified at all, netcat silently does its work unless
    146 some error happens, whereupon it describes the error and exits with a nonzero
    147 status.  Refused network connections are generally NOT considered to be errors,
    148 unless you only asked for a single TCP port and it was refused.
    149 
    150 Note that -w also sets the network inactivity timeout.  This does not have any
    151 effect until standard input closes, but then if nothing further arrives from
    152 the network in the next <timeout> seconds, netcat tries to read the net once
    153 more for good measure, and then closes and exits.  There are a lot of network
    154 services now that accept a small amount of input and return a large amount of
    155 output, such as Gopher and Web servers, which is the main reason netcat was
    156 written to "block" on the network staying open rather than standard input.
    157 Handling the timeout this way gives uniform behavior with network servers that
    158 *don't* close by themselves until told to.
    159 
    160 UDP connections are opened instead of TCP when -u is specified.  These aren't
    161 really "connections" per se since UDP is a connectionless protocol, although
    162 netcat does internally use the "connected UDP socket" mechanism that most
    163 kernels support.  Although netcat claims that an outgoing UDP connection is
    164 "open" immediately, no data is sent until something is read from standard
    165 input.  Only thereafter is it possible to determine whether there really is a
    166 UDP server on the other end, and often you just can't tell.  Most UDP protocols
    167 use timeouts and retries to do their thing and in many cases won't bother
    168 answering at all, so you should specify a timeout and hope for the best.  You
    169 will get more out of UDP connections if standard input is fed from a source
    170 of data that looks like various kinds of server requests.
    171 
    172 To obtain a hex dump file of the data sent either way, use "-o logfile".  The
    173 dump lines begin with "<" or ">" to respectively indicate "from the net" or
    174 "to the net", and contain the total count per direction, and hex and ascii
    175 representations of the traffic.  Capturing a hex dump naturally slows netcat
    176 down a bit, so don't use it where speed is critical.
    177 
    178 Netcat can bind to any local port, subject to privilege restrictions and ports
    179 that are already in use.  It is also possible to use a specific local network
    180 source address if it is that of a network interface on your machine.  [Note:
    181 this does not work correctly on all platforms.]  Use "-p portarg" to grab a
    182 specific local port, and "-s ip-addr" or "-s name" to have that be your source
    183 IP address.  This is often referred to as "anchoring the socket".  Root users
    184 can grab any unused source port including the "reserved" ones less than 1024.
    185 Absence of -p will bind to whatever unused port the system gives you, just like
    186 any other normal client connection, unless you use -r [see below].
    187 
    188 Listen mode will cause netcat to wait for an inbound connection, and then the
    189 same data transfer happens.  Thus, you can do "nc -l -p 1234 < filename" and
    190 when someone else connects to your port 1234, the file is sent to them whether
    191 they wanted it or not.  Listen mode is generally used along with a local port
    192 argument -- this is required for UDP mode, while TCP mode can have the system
    193 assign one and tell you what it is if -v is turned on.  If you specify a target
    194 host and optional port in listen mode, netcat will accept an inbound connection
    195 only from that host and if you specify one, only from that foreign source port.
    196 In verbose mode you'll be informed about the inbound connection, including what
    197 address and port it came from, and since listening on "any" applies to several
    198 possibilities, which address it came *to* on your end.  If the system supports
    199 IP socket options, netcat will attempt to retrieve any such options from an
    200 inbound connection and print them out in hex.
    201 
    202 If netcat is compiled with -DGAPING_SECURITY_HOLE, the -e argument specifies
    203 a program to exec after making or receiving a successful connection.  In the
    204 listening mode, this works similarly to "inetd" but only for a single instance.
    205 Use with GREAT CARE.  This piece of the code is normally not enabled; if you
    206 know what you're doing, have fun.  This hack also works in UDP mode.  Note that
    207 you can only supply -e with the name of the program, but no arguments.  If you
    208 want to launch something with an argument list, write a two-line wrapper script
    209 or just use inetd like always.
    210 
    211 If netcat is compiled with -DTELNET, the -t argument enables it to respond
    212 to telnet option negotiation [always in the negative, i.e. DONT or WONT].
    213 This allows it to connect to a telnetd and get past the initial negotiation
    214 far enough to get a login prompt from the server.  Since this feature has
    215 the potential to modify the data stream, it is not enabled by default.  You
    216 have to understand why you might need this and turn on the #define yourself.
    217 
    218 Data from the network connection is always delivered to standard output as
    219 efficiently as possible, using large 8K reads and writes.  Standard input is
    220 normally sent to the net the same way, but the -i switch specifies an "interval
    221 time" which slows this down considerably.  Standard input is still read in
    222 large batches, but netcat then tries to find where line breaks exist and sends
    223 one line every interval time.  Note that if standard input is a terminal, data
    224 is already read line by line, so unless you make the -i interval rather long,
    225 what you type will go out at a fairly normal rate.  -i is really designed
    226 for use when you want to "measure out" what is read from files or pipes.
    227 
    228 Port-scanning is a popular method for exploring what's out there.  Netcat
    229 accepts its commands with options first, then the target host, and everything
    230 thereafter is interpreted as port names or numbers, or ranges of ports in M-N
    231 syntax.  CAVEAT: some port names in /etc/services contain hyphens -- netcat
    232 currently will not correctly parse those, so specify ranges using numbers if
    233 you can.  If more than one port is thus specified, netcat connects to *all* of
    234 them, sending the same batch of data from standard input [up to 8K worth] to
    235 each one that is successfully connected to.  Specifying multiple ports also
    236 suppresses diagnostic messages about refused connections, unless -v is
    237 specified twice for "more verbosity".  This way you normally get notified only
    238 about genuinely open connections.  Example: "nc -v -w 2 -z target 20-30" will
    239 try connecting to every port between 20 and 30 [inclusive] at the target, and
    240 will likely inform you about an FTP server, telnet server, and mailer along the
    241 way.  The -z switch prevents sending any data to a TCP connection and very
    242 limited probe data to a UDP connection, and is thus useful as a fast scanning
    243 mode just to see what ports the target is listening on.  To limit scanning
    244 speed if desired, -i will insert a delay between each port probe.  There are
    245 some pitfalls with regard to UDP scanning, described later, but in general it
    246 works well.
    247 
    248 For each range of ports specified, scanning is normally done downward within
    249 that range.  If the -r switch is used, scanning hops randomly around within
    250 that range and reports open ports as it finds them.  [If you want them listed
    251 in order regardless, pipe standard error through "sort"...]  In addition, if
    252 random mode is in effect, the local source ports are also randomized.  This
    253 prevents netcat from exhibiting any kind of regular pattern in its scanning.
    254 You can exert fairly fine control over your scan by judicious use of -r and
    255 selected port ranges to cover.  If you use -r for a single connection, the
    256 source port will have a random value above 8192, rather than the next one the
    257 kernel would have assigned you.  Note that selecting a specific local port
    258 with -p overrides any local-port randomization.
    259 
    260 Many people are interested in testing network connectivity using IP source
    261 routing, even if it's only to make sure their own firewalls are blocking
    262 source-routed packets.  On systems that support it, the -g switch can be used
    263 multiple times [up to 8] to construct a loose-source-routed path for your
    264 connection, and the -G argument positions the "hop pointer" within the list.
    265 If your network allows source-routed traffic in and out, you can test
    266 connectivity to your own services via remote points in the internet.  Note that
    267 although newer BSD-flavor telnets also have source-routing capability, it isn't
    268 clearly documented and the command syntax is somewhat clumsy.  Netcat's
    269 handling of "-g" is modeled after "traceroute".
    270 
    271 Netcat tries its best to behave just like "cat".  It currently does nothing to
    272 terminal input modes, and does no end-of-line conversion.  Standard input from
    273 a terminal is read line by line with normal editing characters in effect.  You
    274 can freely suspend out of an interactive connection and resume.  ^C or whatever
    275 your interrupt character is will make netcat close the network connection and
    276 exit.  A switch to place the terminal in raw mode has been considered, but so
    277 far has not been necessary.  You can send raw binary data by reading it out of
    278 a file or piping from another program, so more meaningful effort would be spent
    279 writing an appropriate front-end driver.
    280 
    281 Netcat is not an "arbitrary packet generator", but the ability to talk to raw
    282 sockets and/or nit/bpf/dlpi may appear at some point.  Such things are clearly
    283 useful; I refer you to Darren Reed's excellent ip_filter package, which now
    284 includes a tool to construct and send raw packets with any contents you want.
    285 
    286 Example uses -- the light side
    287 ==============================
    288 
    289 Again, this is a very partial list of possibilities, but it may get you to
    290 think up more applications for netcat.  Driving netcat with simple shell or
    291 expect scripts is an easy and flexible way to do fairly complex tasks,
    292 especially if you're not into coding network tools in C.  My coding isn't
    293 particularly strong either [although undoubtedly better after writing this
    294 thing!], so I tend to construct bare-metal tools like this that I can trivially
    295 plug into other applications.  Netcat doubles as a teaching tool -- one can
    296 learn a great deal about more complex network protocols by trying to simulate
    297 them through raw connections!
    298 
    299 An example of netcat as a backend for something else is the shell-script
    300 Web browser, which simply asks for the relevant parts of a URL and pipes
    301 "GET /what/ever" into a netcat connection to the server.  I used to do this
    302 with telnet, and had to use calculated sleep times and other stupidity to
    303 kludge around telnet's limitations.  Netcat guarantees that I get the whole
    304 page, and since it transfers all the data unmodified, I can even pull down
    305 binary image files and display them elsewhere later.  Some folks may find the
    306 idea of a shell-script web browser silly and strange, but it starts up and
    307 gets me my info a hell of a lot faster than a GUI browser and doesn't hide
    308 any contents of links and forms and such.  This is included, as scripts/web,
    309 along with several other web-related examples.
    310 
    311 Netcat is an obvious replacement for telnet as a tool for talking to daemons.
    312 For example, it is easier to type "nc host 25", talk to someone's mailer, and
    313 just ^C out than having to type ^]c or QUIT as telnet would require you to do.
    314 You can quickly catalog the services on your network by telling netcat to
    315 connect to well-known services and collect greetings, or at least scan for open
    316 ports.  You'll probably want to collect netcat's diagnostic messages in your
    317 output files, so be sure to include standard error in the output using
    318 `>& file' in *csh or `> file 2>&1' in bourne shell.
    319 
    320 A scanning example: "echo QUIT | nc -v -w 5 target 20-250 500-600 5990-7000"
    321 will inform you about a target's various well-known TCP servers, including
    322 r-services, X, IRC, and maybe a few you didn't expect.  Sending in QUIT and
    323 using the timeout will almost guarantee that you see some kind of greeting or
    324 error from each service, which usually indicates what it is and what version.
    325 [Beware of the "chargen" port, though...]  SATAN uses exactly this technique to
    326 collect host information, and indeed some of the ideas herein were taken from
    327 the SATAN backend tools.  If you script this up to try every host in your
    328 subnet space and just let it run, you will not only see all the services,
    329 you'll find out about hosts that aren't correctly listed in your DNS.  Then you
    330 can compare new snapshots against old snapshots to see changes.  For going
    331 after particular services, a more intrusive example is in scripts/probe.
    332 
    333 Netcat can be used as a simple data transfer agent, and it doesn't really
    334 matter which end is the listener and which end is the client -- input at one
    335 side arrives at the other side as output.  It is helpful to start the listener
    336 at the receiving side with no timeout specified, and then give the sending side
    337 a small timeout.  That way the listener stays listening until you contact it,
    338 and after data stops flowing the client will time out, shut down, and take the
    339 listener with it.  Unless the intervening network is fraught with problems,
    340 this should be completely reliable, and you can always increase the timeout.  A
    341 typical example of something "rsh" is often used for: on one side,
    342 
    343 	nc -l -p 1234 | uncompress -c | tar xvfp -
    344 
    345 and then on the other side
    346 
    347 	tar cfp - /some/dir | compress -c | nc -w 3 othermachine 1234
    348 
    349 will transfer the contents of a directory from one machine to another, without
    350 having to worry about .rhosts files, user accounts, or inetd configurations
    351 at either end.  Again, it matters not which is the listener or receiver; the
    352 "tarring" machine could just as easily be running the listener instead.  One
    353 could conceivably use a scheme like this for backups, by having cron-jobs fire
    354 up listeners and backup handlers [which can be restricted to specific addresses
    355 and ports between each other] and pipe "dump" or "tar" on one machine to "dd
    356 of=/dev/tapedrive" on another as usual.  Since netcat returns a nonzero exit
    357 status for a denied listener connection, scripts to handle such tasks could
    358 easily log and reject connect attempts from third parties, and then retry.
    359 
    360 Another simple data-transfer example: shipping things to a PC that doesn't have
    361 any network applications yet except a TCP stack and a web browser.  Point the
    362 browser at an arbitrary port on a Unix server by telling it to download
    363 something like http://unixbox:4444/foo, and have a listener on the Unix side
    364 ready to ship out a file when the connect comes in.  The browser may pervert
    365 binary data when told to save the URL, but you can dig the raw data out of
    366 the on-disk cache.
    367 
    368 If you build netcat with GAPING_SECURITY_HOLE defined, you can use it as an
    369 "inetd" substitute to test experimental network servers that would otherwise
    370 run under "inetd".  A script or program will have its input and output hooked
    371 to the network the same way, perhaps sans some fancier signal handling.  Given
    372 that most network services do not bind to a particular local address, whether
    373 they are under "inetd" or not, it is possible for netcat avoid the "address
    374 already in use" error by binding to a specific address.  This lets you [as
    375 root, for low ports] place netcat "in the way" of a standard service, since
    376 inbound connections are generally sent to such specifically-bound listeners
    377 first and fall back to the ones bound to "any".  This allows for a one-off
    378 experimental simulation of some service, without having to screw around with
    379 inetd.conf.  Running with -v turned on and collecting a connection log from
    380 standard error is recommended.
    381 
    382 Netcat as well can make an outbound connection and then run a program or script
    383 on the originating end, with input and output connected to the same network
    384 port.  This "inverse inetd" capability could enhance the backup-server concept
    385 described above or help facilitate things such as a "network dialback" concept.
    386 The possibilities are many and varied here; if such things are intended as
    387 security mechanisms, it may be best to modify netcat specifically for the
    388 purpose instead of wrapping such functions in scripts.
    389 
    390 Speaking of inetd, netcat will function perfectly well *under* inetd as a TCP
    391 connection redirector for inbound services, like a "plug-gw" without the
    392 authentication step.  This is very useful for doing stuff like redirecting
    393 traffic through your firewall out to other places like web servers and mail
    394 hubs, while posing no risk to the firewall machine itself.  Put netcat behind
    395 inetd and tcp_wrappers, perhaps thusly:
    396 
    397 	www stream tcp nowait nobody /etc/tcpd /bin/nc -w 3 realwww 80
    398 
    399 and you have a simple and effective "application relay" with access control
    400 and logging.  Note use of the wait time as a "safety" in case realwww isn't
    401 reachable or the calling user aborts the connection -- otherwise the relay may
    402 hang there forever.
    403 
    404 You can use netcat to generate huge amounts of useless network data for
    405 various performance testing.  For example, doing
    406 
    407 	yes AAAAAAAAAAAAAAAAAAAAAA | nc -v -v -l -p 2222 > /dev/null
    408 
    409 on one side and then hitting it with
    410 
    411 	yes BBBBBBBBBBBBBBBBBBBBBB | nc othermachine 2222 > /dev/null
    412 
    413 from another host will saturate your wires with A's and B's.  The "very
    414 verbose" switch usage will tell you how many of each were sent and received
    415 after you interrupt either side.  Using UDP mode produces tremendously MORE
    416 trash per unit time in the form of fragmented 8 Kbyte mobygrams -- enough to
    417 stress-test kernels and network interfaces.  Firing random binary data into
    418 various network servers may help expose bugs in their input handling, which
    419 nowadays is a popular thing to explore.  A simple example data-generator is
    420 given in data/data.c included in this package, along with a small collection
    421 of canned input files to generate various packet contents.  This program is
    422 documented in its beginning comments, but of interest here is using "%r" to
    423 generate random bytes at well-chosen points in a data stream.  If you can
    424 crash your daemon, you likely have a security problem.
    425 
    426 The hex dump feature may be useful for debugging odd network protocols,
    427 especially if you don't have any network monitoring equipment handy or aren't
    428 root where you'd need to run "tcpdump" or something.  Bind a listening netcat
    429 to a local port, and have it run a script which in turn runs another netcat
    430 to the real service and captures the hex dump to a log file.  This sets up a
    431 transparent relay between your local port and wherever the real service is.
    432 Be sure that the script-run netcat does *not* use -v, or the extra info it
    433 sends to standard error may confuse the protocol.  Note also that you cannot
    434 have the "listen/exec" netcat do the data capture, since once the connection
    435 arrives it is no longer netcat that is running.
    436 
    437 Binding to an arbitrary local port allows you to simulate things like r-service
    438 clients, if you are root locally.  For example, feeding "^@root^@joe^@pwd^@"
    439 [where ^@ is a null, and root/joe could be any other local/remote username
    440 pair] into a "rsh" or "rlogin" server, FROM your port 1023 for example,
    441 duplicates what the server expects to receive.  Thus, you can test for insecure
    442 .rhosts files around your network without having to create new user accounts on
    443 your client machine.  The program data/rservice.c can aid this process by
    444 constructing the "rcmd" protocol bytes.  Doing this also prevents "rshd" from
    445 trying to create that separate standard-error socket and still gives you an
    446 input path, as opposed to the usual action of "rsh -n".  Using netcat for
    447 things like this can be really useful sometimes, because rsh and rlogin
    448 generally want a host *name* as an argument and won't accept IP addresses.  If
    449 your client-end DNS is hosed, as may be true when you're trying to extract
    450 backup sets on to a dumb client, "netcat -n" wins where normal rsh/rlogin is
    451 useless.
    452 
    453 If you are unsure that a remote syslogger is working, test it with netcat.
    454 Make a UDP connection to port 514 and type in "<0>message", which should
    455 correspond to "kern.emerg" and cause syslogd to scream into every file it has
    456 open [and possibly all over users' terminals].  You can tame this down by
    457 using a different number and use netcat inside routine scripts to send syslog
    458 messages to places that aren't configured in syslog.conf.  For example,
    459 "echo '<38>message' | nc -w 1 -u loggerhost 514" should send to auth.notice
    460 on loggerhost.  The exact number may vary; check against your syslog.h first.
    461 
    462 Netcat provides several ways for you to test your own packet filters.  If you
    463 bind to a port normally protected against outside access and make a connection
    464 to somewhere outside your own network, the return traffic will be coming to
    465 your chosen port from the "outside" and should be blocked.  TCP may get through
    466 if your filter passes all "ack syn", but it shouldn't be even doing that to low
    467 ports on your network.  Remember to test with UDP traffic as well!  If your
    468 filter passes at least outbound source-routed IP packets, bouncing a connection
    469 back to yourself via some gateway outside your network will create "incoming"
    470 traffic with your source address, which should get dropped by a correctly
    471 configured anti-spoofing filter.  This is a "non-test" if you're also dropping
    472 source-routing, but it's good to be able to test for that too.  Any packet
    473 filter worth its salt will be blocking source-routed packets in both
    474 directions, but you never know what interesting quirks you might turn up by
    475 playing around with source ports and addresses and watching the wires with a
    476 network monitor.
    477 
    478 You can use netcat to protect your own workstation's X server against outside
    479 access.  X is stupid enough to listen for connections on "any" and never tell
    480 you when new connections arrive, which is one reason it is so vulnerable.  Once
    481 you have all your various X windows up and running you can use netcat to bind
    482 just to your ethernet address and listen to port 6000.  Any new connections
    483 from outside the machine will hit netcat instead your X server, and you get a
    484 log of who's trying.  You can either tell netcat to drop the connection, or
    485 perhaps run another copy of itself to relay to your actual X server on
    486 "localhost".  This may not work for dedicated X terminals, but it may be
    487 possible to authorize your X terminal only for its boot server, and run a relay
    488 netcat over on the server that will in turn talk to your X terminal.  Since
    489 netcat only handles one listening connection per run, make sure that whatever
    490 way you rig it causes another one to run and listen on 6000 soon afterward, or
    491 your real X server will be reachable once again.  A very minimal script just
    492 to protect yourself could be
    493 
    494 	while true ; do
    495 	  nc -v -l -s <your-addr> -p 6000 localhost 2
    496 	done
    497 
    498 which causes netcat to accept and then close any inbound connection to your
    499 workstation's normal ethernet address, and another copy is immediately run by
    500 the script.  Send standard error to a file for a log of connection attempts.
    501 If your system can't do the "specific bind" thing all is not lost; run your
    502 X server on display ":1" or port 6001, and netcat can still function as a probe
    503 alarm by listening on 6000.
    504 
    505 Does your shell-account provider allow personal Web pages, but not CGI scripts?
    506 You can have netcat listen on a particular port to execute a program or script
    507 of your choosing, and then just point to the port with a URL in your homepage.
    508 The listener could even exist on a completely different machine, avoiding the
    509 potential ire of the homepage-host administrators.  Since the script will get
    510 the raw browser query as input it won't look like a typical CGI script, and
    511 since it's running under your UID you need to write it carefully.  You may want
    512 to write a netcat-based script as a wrapper that reads a query and sets up
    513 environment variables for a regular CGI script.  The possibilities for using
    514 netcat and scripts to handle Web stuff are almost endless.  Again, see the
    515 examples under scripts/.
    516 
    517 Example uses -- the dark side
    518 =============================
    519 
    520 Equal time is deserved here, since a versatile tool like this can be useful
    521 to any Shade of Hat.  I could use my Victorinox to either fix your car or
    522 disassemble it, right?  You can clearly use something like netcat to attack
    523 or defend -- I don't try to govern anyone's social outlook, I just build tools.
    524 Regardless of your intentions, you should still be aware of these threats to
    525 your own systems.
    526 
    527 The first obvious thing is scanning someone *else's* network for vulnerable
    528 services.  Files containing preconstructed data, be it exploratory or
    529 exploitive, can be fed in as standard input, including command-line arguments
    530 to netcat itself to keep "ps" ignorant of your doings.  The more random the
    531 scanning, the less likelihood of detection by humans, scan-detectors, or
    532 dynamic filtering, and with -i you'll wait longer but avoid loading down the
    533 target's network.  Some examples for crafting various standard UDP probes are
    534 given in data/*.d.
    535 
    536 Some configurations of packet filters attempt to solve the FTP-data problem by
    537 just allowing such connections from the outside.  These come FROM port 20, TO
    538 high TCP ports inside -- if you locally bind to port 20, you may find yourself
    539 able to bypass filtering in some cases.  Maybe not to low ports "inside", but
    540 perhaps to TCP NFS servers, X servers, Prospero, ciscos that listen on 200x
    541 and 400x...  Similar bypassing may be possible for UDP [and maybe TCP too] if a
    542 connection comes from port 53; a filter may assume it's a nameserver response.
    543 
    544 Using -e in conjunction with binding to a specific address can enable "server
    545 takeover" by getting in ahead of the real ones, whereupon you can snarf data
    546 sent in and feed your own back out.  At the very least you can log a hex dump
    547 of someone else's session.  If you are root, you can certainly use -s and -e to
    548 run various hacked daemons without having to touch inetd.conf or the real
    549 daemons themselves.  You may not always have the root access to deal with low
    550 ports, but what if you are on a machine that also happens to be an NFS server?
    551 You might be able to collect some interesting things from port 2049, including
    552 local file handles.  There are several other servers that run on high ports
    553 that are likely candidates for takeover, including many of the RPC services on
    554 some platforms [yppasswdd, anyone?].  Kerberos tickets, X cookies, and IRC
    555 traffic also come to mind.  RADIUS-based terminal servers connect incoming
    556 users to shell-account machines on a high port, usually 1642 or thereabouts.
    557 SOCKS servers run on 1080.  Do "netstat -a" and get creative.
    558 
    559 There are some daemons that are well-written enough to bind separately to all
    560 the local interfaces, possibly with an eye toward heading off this sort of
    561 problem.  Named from recent BIND releases, and NTP, are two that come to mind.
    562 Netstat will show these listening on address.53 instead of *.53.  You won't
    563 be able to get in front of these on any of the real interface addresses, which
    564 of course is especially interesting in the case of named, but these servers
    565 sometimes forget about things like "alias" interface addresses or interfaces
    566 that appear later on such as dynamic PPP links.  There are some hacked web
    567 servers and versions of "inetd" floating around that specifically bind as well,
    568 based on a configuration file -- these generally *are* bound to alias addresses
    569 to offer several different address-based services from one machine.
    570 
    571 Using -e to start a remote backdoor shell is another obvious sort of thing,
    572 easier than constructing a file for inetd to listen on "ingreslock" or
    573 something, and you can access-control it against other people by specifying a
    574 client host and port.  Experience with this truly demonstrates how fragile the
    575 barrier between being "logged in" or not really is, and is further expressed by
    576 scripts/bsh.  If you're already behind a firewall, it may be easier to make an
    577 *outbound* connection and then run a shell; a small wrapper script can
    578 periodically try connecting to a known place and port, you can later listen
    579 there until the inbound connection arrives, and there's your shell.  Running
    580 a shell via UDP has several interesting features, although be aware that once
    581 "connected", the UDP stub sockets tend to show up in "netstat" just like TCP
    582 connections and may not be quite as subtle as you wanted.  Packets may also be
    583 lost, so use TCP if you need reliable connections.  But since UDP is
    584 connectionless, a hookup of this sort will stick around almost forever, even if
    585 you ^C out of netcat or do a reboot on your side, and you only need to remember
    586 the ports you used on both ends to reestablish.  And outbound UDP-plus-exec
    587 connection creates the connected socket and starts the program immediately.  On
    588 a listening UDP connection, the socket is created once a first packet is
    589 received.  In either case, though, such a "connection" has the interesting side
    590 effect that only your client-side IP address and [chosen?] source port will
    591 thereafter be able to talk to it.  Instant access control!  A non-local third
    592 party would have to do ALL of the following to take over such a session:
    593 
    594 	forge UDP with your source address [trivial to do; see below]
    595 	guess the port numbers of BOTH ends, or sniff the wire for them
    596 	arrange to block ICMP or UDP return traffic between it and your real
    597 	  source, so the session doesn't die with a network write error.
    598 
    599 The companion program data/rservice.c is helpful in scripting up any sort of
    600 r-service username or password guessing attack.  The arguments to "rservice"
    601 are simply the strings that get null-terminated and passed over an "rcmd"-style
    602 connection, with the assumption that the client does not need a separate
    603 standard-error port.  Brute-force password banging is best done via "rexec" if
    604 it is available since it is less likely to log failed attempts.  Thus, doing
    605 "rservice joe joespass pwd | nc target exec" should return joe's home dir if
    606 the password is right, or "Permission denied."  Plug in a dictionary and go to
    607 town.  If you're attacking rsh/rlogin, remember to be root and bind to a port
    608 between 512 and 1023 on your end, and pipe in "rservice joe joe pwd" and such.
    609 
    610 Netcat can prevent inadvertently sending extra information over a telnet
    611 connection.  Use "nc -t" in place of telnet, and daemons that try to ask for
    612 things like USER and TERM environment variables will get no useful answers, as
    613 they otherwise would from a more recent telnet program.  Some telnetds actually
    614 try to collect this stuff and then plug the USER variable into "login" so that
    615 the caller is then just asked for a password!  This mechanism could cause a
    616 login attempt as YOUR real username to be logged over there if you use a
    617 Borman-based telnet instead of "nc -t".
    618 
    619 Got an unused network interface configured in your kernel [e.g. SLIP], or
    620 support for alias addresses?  Ifconfig one to be any address you like, and bind
    621 to it with -s to enable all sorts of shenanigans with bogus source addresses.
    622 The interface probably has to be UP before this works; some SLIP versions
    623 need a far-end address before this is true.  Hammering on UDP services is then
    624 a no-brainer.  What you can do to an unfiltered syslog daemon should be fairly
    625 obvious; trimming the conf file can help protect against it.  Many routers out
    626 there still blindly believe what they receive via RIP and other routing
    627 protocols.  Although most UDP echo and chargen servers check if an incoming
    628 packet was sent from *another* "internal" UDP server, there are many that still
    629 do not, any two of which [or many, for that matter] could keep each other
    630 entertained for hours at the expense of bandwidth.  And you can always make
    631 someone wonder why she's being probed by nsa.gov.
    632 
    633 Your TCP spoofing possibilities are mostly limited to destinations you can
    634 source-route to while locally bound to your phony address.  Many sites block
    635 source-routed packets these days for precisely this reason.  If your kernel
    636 does oddball things when sending source-routed packets, try moving the pointer
    637 around with -G.  You may also have to fiddle with the routing on your own
    638 machine before you start receiving packets back.  Warning: some machines still
    639 send out traffic using the source address of the outbound interface, regardless
    640 of your binding, especially in the case of localhost.  Check first.  If you can
    641 open a connection but then get no data back from it, the target host is
    642 probably killing the IP options on its end [this is an option inside TCP
    643 wrappers and several other packages], which happens after the 3-way handshake
    644 is completed.  If you send some data and observe the "send-q" side of "netstat"
    645 for that connection increasing but never getting sent, that's another symptom.
    646 Beware: if Sendmail 8.7.x detects a source-routed SMTP connection, it extracts
    647 the hop list and sticks it in the Received: header!
    648 
    649 SYN bombing [sometimes called "hosing"] can disable many TCP servers, and if
    650 you hit one often enough, you can keep it unreachable for days.  As is true of
    651 many other denial-of-service attacks, there is currently no defense against it
    652 except maybe at the human level.  Making kernel SOMAXCONN considerably larger
    653 than the default and the half-open timeout smaller can help, and indeed some
    654 people running large high-performance web servers have *had* to do that just to
    655 handle normal traffic.  Taking out mailers and web servers is sociopathic, but
    656 on the other hand it is sometimes useful to be able to, say, disable a site's
    657 identd daemon for a few minutes.  If someone realizes what is going on,
    658 backtracing will still be difficult since the packets have a phony source
    659 address, but calls to enough ISP NOCs might eventually pinpoint the source.
    660 It is also trivial for a clueful ISP to watch for or even block outgoing
    661 packets with obviously fake source addresses, but as we know many of them are
    662 not clueful or willing to get involved in such hassles.  Besides, outbound
    663 packets with an [otherwise unreachable] source address in one of their net
    664 blocks would look fairly legitimate.
    665 
    666 Notes
    667 =====
    668 
    669 A discussion of various caveats, subtleties, and the design of the innards.
    670 
    671 As of version 1.07 you can construct a single file containing command arguments
    672 and then some data to transfer.  Netcat is now smart enough to pick out the
    673 first line and build the argument list, and send any remaining data across the
    674 net to one or multiple ports.  The first release of netcat had trouble with
    675 this -- it called fgets() for the command line argument, which behind the
    676 scenes does a large read() from standard input, perhaps 4096 bytes or so, and
    677 feeds that out to the fgets() library routine.  By the time netcat 1.00 started
    678 directly read()ing stdin for more data, 4096 bytes of it were gone.  It now
    679 uses raw read() everywhere and does the right thing whether reading from files,
    680 pipes, or ttys.  If you use this for multiple-port connections, the single
    681 block of data will now be a maximum of 8K minus the first line.  Improvements
    682 have been made to the logic in sending the saved chunk to each new port.  Note
    683 that any command-line arguments hidden using this mechanism could still be
    684 extracted from a core dump.
    685 
    686 When netcat receives an inbound UDP connection, it creates a "connected socket"
    687 back to the source of the connection so that it can also send out data using
    688 normal write().  Using this mechanism instead of recvfrom/sendto has several
    689 advantages -- the read/write select loop is simplified, and ICMP errors can in
    690 effect be received by non-root users.  However, it has the subtle side effect
    691 that if further UDP packets arrive from the caller but from different source
    692 ports, the listener will not receive them.  UDP listen mode on a multihomed
    693 machine may have similar quirks unless you specifically bind to one of its
    694 addresses.  It is not clear that kernel support for UDP connected sockets
    695 and/or my understanding of it is entirely complete here, so experiment...
    696 
    697 You should be aware of some subtleties concerning UDP scanning.  If -z is on,
    698 netcat attempts to send a single null byte to the target port, twice, with a
    699 small time in between.  You can either use the -w timeout, or netcat will try
    700 to make a "sideline" TCP connection to the target to introduce a small time
    701 delay equal to the round-trip time between you and the target.  Note that if
    702 you have a -w timeout and -i timeout set, BOTH take effect and you wait twice
    703 as long.  The TCP connection is to a normally refused port to minimize traffic,
    704 but if you notice a UDP fast-scan taking somewhat longer than it should, it
    705 could be that the target is actually listening on the TCP port.  Either way,
    706 any ICMP port-unreachable messages from the target should have arrived in the
    707 meantime.  The second single-byte UDP probe is then sent.  Under BSD kernels,
    708 the ICMP error is delivered to the "connected socket" and the second write
    709 returns an error, which tells netcat that there is NOT a UDP service there.
    710 While Linux seems to be a fortunate exception, under many SYSV derived kernels
    711 the ICMP is not delivered, and netcat starts reporting that *all* the ports are
    712 "open" -- clearly wrong.  [Some systems may not even *have* the "udp connected
    713 socket" concept, and netcat in its current form will not work for UDP at all.]
    714 If -z is specified and only one UDP port is probed, netcat's exit status
    715 reflects whether the connection was "open" or "refused" as with TCP.
    716 
    717 It may also be that UDP packets are being blocked by filters with no ICMP error
    718 returns, in which case everything will time out and return "open".  This all
    719 sounds backwards, but that's how UDP works.  If you're not sure, try "echo
    720 w00gumz | nc -u -w 2 target 7" to see if you can reach its UDP echo port at
    721 all.  You should have no trouble using a BSD-flavor system to scan for UDP
    722 around your own network, although flooding a target with the high activity that
    723 -z generates will cause it to occasionally drop packets and indicate false
    724 "opens".  A more "correct" way to do this is collect and analyze the ICMP
    725 errors, as does SATAN's "udp_scan" backend, but then again there's no guarantee
    726 that the ICMP gets back to you either.  Udp_scan also does the zero-byte
    727 probes but is excruciatingly careful to calculate its own round-trip timing
    728 average and dynamically set its own response timeouts along with decoding any
    729 ICMP received.  Netcat uses a much sleazier method which is nonetheless quite
    730 effective.  Cisco routers are known to have a "dead time" in between ICMP
    731 responses about unreachable UDP ports, so a fast scan of a cisco will show
    732 almost everything "open".  If you are looking for a specific UDP service, you
    733 can construct a file containing the right bytes to trigger a response from the
    734 other end and send that as standard input.  Netcat will read up to 8K of the
    735 file and send the same data to every UDP port given.  Note that you must use a
    736 timeout in this case [as would any other UDP client application] since the
    737 two-write probe only happens if -z is specified.
    738 
    739 Many telnet servers insist on a specific set of option negotiations before
    740 presenting a login banner.  On a raw connection you will see this as small
    741 amount of binary gook.  My attempts to create fixed input bytes to make a
    742 telnetd happy worked some places but failed against newer BSD-flavor ones,
    743 possibly due to timing problems, but there are a couple of much better
    744 workarounds.  First, compile with -DTELNET and use -t if you just want to get
    745 past the option negotiation and talk to something on a telnet port.  You will
    746 still see the binary gook -- in fact you'll see a lot more of it as the options
    747 are responded to behind the scenes.  The telnet responder does NOT update the
    748 total byte count, or show up in the hex dump -- it just responds negatively to
    749 any options read from the incoming data stream.  If you want to use a normal
    750 full-blown telnet to get to something but also want some of netcat's features
    751 involved like settable ports or timeouts, construct a tiny "foo" script:
    752 
    753 	#! /bin/sh
    754 	exec nc -otheroptions targethost 23
    755 
    756 and then do
    757 
    758 	nc -l -p someport -e foo localhost &
    759 	telnet localhost someport
    760 
    761 and your telnet should connect transparently through the exec'ed netcat to
    762 the target, using whatever options you supplied in the "foo" script.  Don't
    763 use -t inside the script, or you'll wind up sending *two* option responses.
    764 
    765 I've observed inconsistent behavior under some Linuxes [perhaps just older
    766 ones?] when binding in listen mode.  Sometimes netcat binds only to "localhost"
    767 if invoked with no address or port arguments, and sometimes it is unable to
    768 bind to a specific address for listening if something else is already listening
    769 on "any".  The former problem can be worked around by specifying "-s 0.0.0.0",
    770 which will do the right thing despite netcat claiming that it's listening on
    771 [127.0.0.1].  This is a known problem -- for example, there's a mention of it
    772 in the makefile for SOCKS.  On the flip side, binding to localhost and sending
    773 packets to some other machine doesn't work as you'd expect -- they go out with
    774 the source address of the sending interface instead.  The Linux kernel contains
    775 a specific check to ensure that packets from 127.0.0.1 are never sent to the
    776 wire; other kernels may contain similar code.  Linux, of course, *still*
    777 doesn't support source-routing, but they claim that it and many other network
    778 improvements are at least breathing hard.
    779 
    780 There are several possible errors associated with making TCP connections, but
    781 to specifically see anything other than "refused", one must wait the full
    782 kernel-defined timeout for a connection to fail.  Netcat's mechanism of
    783 wrapping an alarm timer around the connect prevents the *real* network error
    784 from being returned -- "errno" at that point indicates "interrupted system
    785 call" since the connect attempt was interrupted.  Some old 4.3 BSD kernels
    786 would actually return things like "host unreachable" immediately if that was
    787 the case, but most newer kernels seem to wait the full timeout and *then* pass
    788 back the real error.  Go figure.  In this case, I'd argue that the old way was
    789 better, despite those same kernels generally being the ones that tear down
    790 *established* TCP connections when ICMP-bombed.
    791 
    792 Incoming socket options are passed to applications by the kernel in the
    793 kernel's own internal format.  The socket-options structure for source-routing
    794 contains the "first-hop" IP address first, followed by the rest of the real
    795 options list.  The kernel uses this as is when sending reply packets -- the
    796 structure is therefore designed to be more useful to the kernel than to humans,
    797 but the hex dump of it that netcat produces is still useful to have.
    798 
    799 Kernels treat source-routing options somewhat oddly, but it sort of makes sense
    800 once one understands what's going on internally.  The options list of addresses
    801 must contain hop1, hop2, ..., destination.  When a source-routed packet is sent
    802 by the kernel [at least BSD], the actual destination address becomes irrelevant
    803 because it is replaced with "hop1", "hop1" is removed from the options list,
    804 and all the other addresses in the list are shifted up to fill the hole.  Thus
    805 the outbound packet is sent from your chosen source address to the first
    806 *gateway*, and the options list now contains hop2, ..., destination.  During
    807 all this address shuffling, the kernel does NOT change the pointer value, which
    808 is why it is useful to be able to set the pointer yourself -- you can construct
    809 some really bizarre return paths, and send your traffic fairly directly to the
    810 target but around some larger loop on the way back.  Some Sun kernels seem to
    811 never flip the source-route around if it contains less than three hops, never
    812 reset the pointer anyway, and tries to send the packet [with options containing
    813 a "completed" source route!!] directly back to the source.  This is way broken,
    814 of course.  [Maybe ipforwarding has to be on?  I haven't had an opportunity to
    815 beat on it thoroughly yet.]
    816 
    817 "Credits" section: The original idea for netcat fell out of a long-standing
    818 desire and fruitless search for a tool resembling it and having the same
    819 features.  After reading some other network code and realizing just how many
    820 cool things about sockets could be controlled by the calling user, I started
    821 on the basics and the rest fell together pretty quickly.  Some port-scanning
    822 ideas were taken from Venema/Farmer's SATAN tool kit, and Pluvius' "pscan"
    823 utility.  Healthy amounts of BSD kernel source were perused in an attempt to
    824 dope out socket options and source-route handling; additional help was obtained
    825 from Dave Borman's telnet sources.  The select loop is loosely based on fairly
    826 well-known code from "rsh" and Richard Stevens' "sock" program [which itself is
    827 sort of a "netcat" with more obscure features], with some more paranoid
    828 sanity-checking thrown in to guard against the distinct likelihood that there
    829 are subtleties about such things I still don't understand.  I found the
    830 argument-hiding method cleanly implemented in Barrett's "deslogin"; reading the
    831 line as input allows greater versatility and is much less prone to cause
    832 bizarre problems than the more common trick of overwriting the argv array.
    833 After the first release, several people contributed portability fixes; they are
    834 credited in generic.h and the Makefile.  Lauren Burka inspired the ascii art
    835 for this revised document.  Dean Gaudet at Wired supplied a precursor to
    836 the hex-dump code, and mudge (a] l0pht.com originally experimented with and
    837 supplied code for the telnet-options responder.  Outbound "-e <prog>" resulted
    838 from a need to quietly bypass a firewall installation.  Other suggestions and
    839 patches have rolled in for which I am always grateful, but there are only 26
    840 hours per day and a discussion of feature creep near the end of this document.
    841 
    842 Netcat was written with the Russian railroad in mind -- conservatively built
    843 and solid, but it *will* get you there.  While the coding style is fairly
    844 "tight", I have attempted to present it cleanly [keeping *my* lines under 80
    845 characters, dammit] and put in plenty of comments as to why certain things
    846 are done.  Items I know to be questionable are clearly marked with "XXX".
    847 Source code was made to be modified, but determining where to start is
    848 difficult with some of the tangles of spaghetti code that are out there.
    849 Here are some of the major points I feel are worth mentioning about netcat's
    850 internal design, whether or not you agree with my approach.
    851 
    852 Except for generic.h, which changes to adapt more platforms, netcat is a single
    853 source file.  This has the distinct advantage of only having to include headers
    854 once and not having to re-declare all my functions in a billion different
    855 places.  I have attempted to contain all the gross who's-got-what-.h-file
    856 things in one small dumping ground.  Functions are placed "dependencies-first",
    857 such that when the compiler runs into the calls later, it already knows the
    858 type and arguments and won't complain.  No function prototyping -- not even the
    859 __P(()) crock -- is used, since it is more portable and a file of this size is
    860 easy enough to check manually.  Each function has a standard-format comment
    861 ahead of it, which is easily found using the regexp " :$".  I freely use gotos.
    862 Loops and if-clauses are made as small and non-nested as possible, and the ends
    863 of same *marked* for clarity [I wish everyone would do this!!].
    864 
    865 Large structures and buffers are all malloc()ed up on the fly, slightly larger
    866 than the size asked for and zeroed out.  This reduces the chances of damage
    867 from those "end of the buffer" fencepost errors or runaway pointers escaping
    868 off the end.  These things are permanent per run, so nothing needs to be freed
    869 until the program exits.
    870 
    871 File descriptor zero is always expected to be standard input, even if it is
    872 closed.  If a new network descriptor winds up being zero, a different one is
    873 asked for which will be nonzero, and fd zero is simply left kicking around
    874 for the rest of the run.  Why?  Because everything else assumes that stdin is
    875 always zero and "netfd" is always positive.  This may seem silly, but it was a
    876 lot easier to code.  The new fd is obtained directly as a new socket, because
    877 trying to simply dup() a new fd broke subsequent socket-style use of the new fd
    878 under Solaris' stupid streams handling in the socket library.
    879 
    880 The catch-all message and error handlers are implemented with an ample list of
    881 phoney arguments to get around various problems with varargs.  Varargs seems
    882 like deliberate obfuscation in the first place, and using it would also
    883 require use of vfprintf() which not all platforms support.  The trailing
    884 sleep in bail() is to allow output to flush, which is sometimes needed if
    885 netcat is already on the other end of a network connection.
    886 
    887 The reader may notice that the section that does DNS lookups seems much
    888 gnarlier and more confusing than other parts.  This is NOT MY FAULT.  The
    889 sockaddr and hostent abstractions are an abortion that forces the coder to
    890 deal with it.  Then again, a lot of BSD kernel code looks like similar
    891 struct-pointer hell.  I try to straighten it out somewhat by defining my own
    892 HINF structure, containing names, ascii-format IP addresses, and binary IP
    893 addresses.  I fill this structure exactly once per host argument, and squirrel
    894 everything safely away and handy for whatever wants to reference it later.
    895 
    896 Where many other network apps use the FIONBIO ioctl to set non-blocking I/O
    897 on network sockets, netcat uses straightforward blocking I/O everywhere.
    898 This makes everything very lock-step, relying on the network and filesystem
    899 layers to feed in data when needed.  Data read in is completely written out
    900 before any more is fetched.  This may not be quite the right thing to do under
    901 some OSes that don't do timed select() right, but this remains to be seen.
    902 
    903 The hexdump routine is written to be as fast as possible, which is why it does
    904 so much work itself instead of just sprintf()ing everything together.  Each
    905 dump line is built into a single buffer and atomically written out using the
    906 lowest level I/O calls.  Further improvements could undoubtedly be made by
    907 using writev() and eliminating all sprintf()s, but it seems to fly right along
    908 as is.  If both exec-a-prog mode and a hexdump file is asked for, the hexdump
    909 flag is deliberately turned off to avoid creating random zero-length files.
    910 Files are opened in "truncate" mode; if you want "append" mode instead, change
    911 the open flags in main().
    912 
    913 main() may look a bit hairy, but that's only because it has to go down the
    914 argv list and handle multiple ports, random mode, and exit status.  Efforts
    915 have been made to place a minimum of code inside the getopt() loop.  Any real
    916 work is sent off to functions in what is hopefully a straightforward way.
    917 
    918 Obligatory vendor-bash: If "nc" had become a standard utility years ago,
    919 the commercial vendors would have likely packaged it setuid root and with
    920 -DGAPING_SECURITY_HOLE turned on but not documented.  It is hoped that netcat
    921 will aid people in finding and fixing the no-brainer holes of this sort that
    922 keep appearing, by allowing easier experimentation with the "bare metal" of
    923 the network layer.
    924 
    925 It could be argued that netcat already has too many features.  I have tried
    926 to avoid "feature creep" by limiting netcat's base functionality only to those
    927 things which are truly relevant to making network connections and the everyday
    928 associated DNS lossage we're used to.  Option switches already have slightly
    929 overloaded functionality.  Random port mode is sort of pushing it.  The
    930 hex-dump feature went in later because it *is* genuinely useful.  The
    931 telnet-responder code *almost* verges on the gratuitous, especially since it
    932 mucks with the data stream, and is left as an optional piece.  Many people have
    933 asked for example "how 'bout adding encryption?" and my response is that such
    934 things should be separate entities that could pipe their data *through* netcat
    935 instead of having their own networking code.  I am therefore not completely
    936 enthusiastic about adding any more features to this thing, although you are
    937 still free to send along any mods you think are useful.
    938 
    939 Nonetheless, at this point I think of netcat as my tcp/ip swiss army knife,
    940 and the numerous companion programs and scripts to go with it as duct tape.
    941 Duct tape of course has a light side and a dark side and binds the universe
    942 together, and if I wrap enough of it around what I'm trying to accomplish,
    943 it *will* work.  Alternatively, if netcat is a large hammer, there are many
    944 network protocols that are increasingly looking like nails by now...
    945 
    946 _H* 960320 v1.10 RELEASE -- happy spring!
    947