Annotation of src/usr.bin/nc/README, Revision 1.1
1.1 ! deraadt 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@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@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!
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / nc