Netcat - A simple port of 'netcat' (nc) for DOS 2010-07-18 Version Michael Brutman (mbbrutman@yahoo.com) Hardware requirements: 8088 processor or better Somewhere between 96KB and 128KB available RAM CGA, Monochrome (MDA), EGA or VGA display Supported Ethernet card, SLIP or PPP connection Software requirements: DOS 2.0 or newer (DOS 3.3 or newer recommended) Packet driver for your Ethernet card, SLIP or PPP connection Introduction Netcat (nc) is a utility that can send and receive data using a TCP/IP socket. It has the ability to open a connection to another machine or to listen for incoming connections. Input can be entered interactively through the keyboard or redirected in from a file. Output can appear on the screen or redirected to a file. Nc can be used to send large files or short messages, and it can be called from within batch files too. Any status messages that netcat creates that are not part of the data received from the socket are sent to stderr. This ensures that if you redirect the socket output to a file that only the data that came across the socket will be in that file. Requirements Netcat is built using the mTCP library. The setup instructions for mTCP can be found in SETUP.TXT. Using Netcat Netcat uses the following syntax: nc -target [options] nc -listen [options] The first form of the command is used to create a socket connection to another machine, as a client program normally would. The second form of the command is used to make nc wait for an incoming connection from another machine, as a server program normally would. Interested in getting started quickly? Skip down to the section entitled 'Examples'. The discussion of options is fairly long. Netcat Options Options are: -help Show basic help text -verbose Print extra status messages -bin Treat stdin and stdout as binary streams -telnet_nl Send and receive newline (NL) as Telnet newline (CR/LF) -echo Turn on local echoing -w Wait seconds for traffic after stdin closes -nocorc Do not Close on remote close -srcport Use as the source port when connecting Some explanation is needed here ... First, some background definitions: Newline character (NL): This varies depending on the computer and operating system being used. - For MS-DOS: A newline is composed of a CR/LF pair - For Unix: A newline character is an LF - For internet programs using the Telnet NVT standard: A newline is composed of a CR/LF pair. Socket 'closes' In this context a socket is a connection to another machine using TCP/IP. The socket is a full duplex connection - each side can send at the same time, and each side is treated as a peer. When a socket connection is "closed" it means that one one side of the connection has signaled that it is done sending data. The socket still exists, and the side that did the close is still free to receive data from the socket - it just can't send any more data. The other side of the connection is free to send more data to the half that did the close, but it should not expect to be able to read any more data from the closed half. It is only when both sides have closed their half of the socket that the socket connection is terminated and cleaned up. Most programs communicating via a socket use a protocol over the socket that warns both sides when the connection is going to be closed. That allows them to close their half of the socket and end the application while being assured that the other side is going to close and exit too. Netcat's default behavior is to close and exit when the other side closes, but this can be overridden. Netcat default operation: With no extra options netcat will behave as follows after a connection is made: - Input will come from the keyboard and be sent over the socket - Data received on the socket will be written to the screen - Pressing Ctrl-Z at the keyboard will specify the end of input and close your half of the socket connection. It will also terminate the socket connection and end netcat even if the other side of the connection had not closed their half of the socket. (It is expected that the other side will close when they see you close.) - Pressing the Enter key will generate a Unix newline char (LF) - Unix newline characters received on the socket will be converted to MS-DOS newline characters (CR/LF) - If the remote side does a close on their half of the socket netcat will close your half of the socket and exit. (This can be overridden.) - Each keystroke is sent in a separate packet. There is no line editing capability because that would block the receipt of incoming data from the socket. There are no surprises here, unless you come from an entirely DOS universe where newline characters are always a CR/LF pair instead of the Unix style newline which is an ASCII LF. Redirecting stdin and stdout from/to files You can specify that stdin should be read from a file or that stdout should be written to a file. Just use the normal DOS redirection charaters to do this. Netcat behavior when stdin/stdout are redirected is similar to its default behavior, except for these changes: - If netcat detects that stdin is redirected from a file it will try to read large chunks of the file in a single read operation and then send those chunks in large packets. This is more efficient than the normal behavior when netcat is reading from the keyboard. - If netcat detects that stdin is redirected from a file it will close its half of the socket when EOF is hit on stdin. This will cause netcat to terminate the socket connection and exit whether the other side had closed their half of the socket or not. (There is an option to change this behavior - see "-w".) Netcat options: -verbose Verbose mode gives you extra status message that tell you when the local side or the remote side closed their connection. These messages are written to stderr so they will not affect data that you redirect to a file on stdout. -bin MS-DOS can treat files as either BINARY or TEXT. In BINARY mode: - All characters are read and written exactly with no changes. - The End of File (EOF) is determined by the file size, not a Ctrl-Z char. If you are reading from the keyboard (and not a redirected file) then you need to use Alt-X to close the connection, as Ctrl-Z will not be interpreted as EOF. In TEXT mode: - When writing on stdout Unix newline characters (LF) will be converted to MS-DOS newline characters (CR/LF). - When reading from stdin MS-DOS newline characters (CR/LF) will be converted to the Unix newline character (LF). - A Ctrl-Z will be interpreted as End of File If you are transferring binary data, use -bin to ensure that netcat and MS-DOS do not alter your data in any way. If you are working with normal ASCII text then use the default, although binary mode might work too. Binary mode is going to perform much better than the normal text mode because in binary mode no attempt is made to process the incoming and outgoing characters, saving on processing time. Note: You can use -bin even if you are not redirecting stdin and stdout to a file. The behavior change is the same whether you are redirecting or not. -telnet_nl The standard for sending newline characters across the internet using the Telnet "network virtual terminal" (NVT) is to send a CR/LF pair. This is because some machines use CR, some use LF, and some use other oddball characters. If you are connecting to a service that uses the Telnet NVT standard then turn this option on. This will convert your outgoing newline characters to the Telnet standard of CR/LF. Services like HTTP, FTP, SMTP, etc. all use the Telnet NVT standard so they will probably work better with this option. Incoming CR/LF pairs will be translated to normal newlines. This option can not be mixed with -bin. If you need binary mode, then turning on -telnet_nl makes not sense. (Slightly fun trick .. MS-DOS uses the same newline characters as the Telnet NVT standard. So you can probably use -bin in place of -telnet_nl. But -bin changes other things, so it is probably best not to mess with it.) This option does not turn netcat into a Telnet client - it only changes the way that newline characters are sent and received. It will not do Telnet option negotiation, which is an important part of the Telnet protocol that a real Telnet server will need. But this option will help you connect to FTP, SMTP and other servers that use the Telnet NVT standard but not do Telnet option negotiation. -echo By default no echoing of characters is provided. If you turn this on any characters from stdin will be echoed to stdout. If the other side is echoing your characters and you turn this on you will see things twice. Keep in mind that because we are echoing to stdout with this option, your local input will show up in stdout even when you redirect stdout to a file. -w The default is to close the socket connection and exit from netcat when EOF is detected on stdin. This can be a problem if there was data in flight from the other side at the time the socket was closed. (You will miss the data that was in flight. This is more likely to happen when stdin is redirected from a file, as netcat will send it very quickly and hit EOF possibly before the other side has had a chance to do everything.) To get around this the -w option tells netcat how long to wait for data to come from the other side after your side of the socket hits EOF on stdin. This can give netcat a chance to receive the last of the data from the other side before closing the connection. is the number of seconds to wait. -nocorc Corc stands for "Close On Remote Close", so -nocorc means don't do that. By default if netcat detects that the other side closed its half of the socket connection it will close the socket and exit. This will happen even if EOF was not yet detected on stdin. With this option netcat will ignore the close from the other side until EOF is detected on stdin. This option probably is not very useful for most people, but if you are experimenting with 'half closed' sockets it can be very useful. -srcport By default if you are connecting to another machine netcat will use a random port number as the source port on your machine. If for some reason you need to specify a source port for your machine you can use this option. Keyboard Handling By default netcat reads interactively from the keyboard. This is normally straightforward, but there are some things you should know. In binary mode: - Ctrl-Z is sent as ASCII 26 and does not mark EOF. (You must signal 'EOF' using Alt-X.) - Enter is sent as ASCII 13 (CR). - Ctrl-Enter is sent as ASCII 10 (LF). - All other keys are sent exactly as they are read. In text mode: - Ctrl-Z means EOF for stdin, and will close your half of the socket. - Enter is sent as a Unix newline (LF) - Ctrl-Enter is also sent as ASCII 10 (LF). (No change from above) - To send a raw CR use Ctrl-M. In text mode with -telnet_nl turned on the Enter key changes slightly: - Enter is sent as a telnet NVT newline (CR/LF) - To send a raw CR use Ctrl-M. To send a raw LF use Ctrl-J. or Ctrl-Enter. Special keys: Whether you are reading from the keyboard or not the following keys will always be honored: Alt-E: Toggle local echoing on and off Alt-H: Help Alt-X: Close your half of the socket connection Alt-S: Show Status Ctrl-Break: Unconditional exit Alt-S is really handy, as it will show you if the other side has closed their half of the connection or not. If you are doing a large file transfer it can also show you how many bytes have been sent and received. Environment variables Two environment variables are provided to help tailor netcat to your memory and performance requirements. READBUF Default 8192, Range 512 to 32768 Use: Sets the size of the buffer used to read from stdin when stdin is redirected from a file on your local disk. Bigger numbers generally result in higher performance. Use a smaller number if you are tight on memory and need to cut back on what netcat whats to use. If you are low on memory 4KB is a reasonable setting that will not hurt performance too much. This environment variable has no effect when you are reading from the keyboard. WRITEBUF Default 8192, Range 512 to 32768 Use: Sets the size of the buffer used to write to stdout when stdout is redirected to a file on your local disk. Bigger numbers generally result in higher performance. Use a smaller number if you are tight on memory and need to cut back on what netcat whats to use. If you are low on memory 4KB is a reasonable setting that will not hurt performance too much. For both variables DOS likes it best if you use a power of 2, or at least a multiple of 512 bytes. Other numbers will cause extra work for DOS and limit performance. Examples (and Quickstart!) nc -target 192.168.2.10 7 Opens a socket connection to 192.168.2.10 on port 7. Your keystrokes will be sent and data coming back will be displayed on the screen. (On a Unix machine port 7 is the echo service, so you should see everything that you send.) nc -target 192.168.2.5 1234 < input.txt Opens a TCP/IP socket to 192.168.2.5 port 1234 and sends the file 'input.txt' to the other machine instead of sending your keyboard input. The program automatically ends after input.txt has been transferred. nc -target 192.168.2.5 1234 -w 5 < input.txt Same as above, but wait 5 more seconds after EOF is detected on stdin so that any response from the other side can be read. nc -listen 2000 > newfile.txt Listens on port 2000 for a connection from a remote machine. When the connection is established any incoming data is sent to newfile.txt. When the remote machine closes the connection netcat exits automatically. nc -listen 3000 -nocorc > newfile.txt Similar to above, but netcat does not automatically exit until it is told to. (This is not terribly useful when redirecting files, but is useful when using netcat interactively.) nc -target www.cnn.com 80 -telnet_nl -verbose -echo Connect to the HTTP server at www.cnn.com on port 80. Automatically convert newlines to telnet NVT newlines, enable verbose status messages, and start with local echoing turned on. (If you send "GET /" without the quotes and press Enter, you will get a web page back!) Limitations * Does not support UDP. (Most Unix versions do.) Changes: 2010-06-21: Ported to Open Watcom 2010-04-22: Maintenance release for the underlying TCP library. TCP checksums should be computed correctly all of the time now, and are much faster. 2010-02-08: Complete rewrite More information: http://www.brutman.com/mTCP Created July 31st, 2008, Last updated July 18th, 2010 (C)opyright Michael B. Brutman, mbbrutman@yahoo.com