Netcat - A simple port of 'netcat' (nc) for DOS
2011-10-04 Version
Michael Brutman (mbbrutman@gmail.com)


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.


Hardware requirements

  8088 processor or better
  160KB available RAM (using standard buffer sizes)
  CGA, Monochrome (MDA), EGA or VGA display
  Supported Ethernet card, SLIP or PPP connection


Software requirements

  DOS 2.1 or newer (DOS 3.3 or newer recommended)
  Packet driver for your Ethernet card, SLIP or PPP connection


Setup instructions

  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 <ipaddr> <port> [options]
    nc -listen <port> [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 <n>            Wait <n> seconds for traffic after stdin closes
    -nocorc           Do not Close on remote close
    -srcport <port>   Use <port> 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 (details):

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

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

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


Support

  Have a comment or need help?  Please email me at mbbrutman@gmail.com.


Recent changes

  2010-11-27:

    Misc TCP library changes to improve handling when buffers are full.
    Watcom runtime workaround: improve compatibility with older machines

  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 Oct 1st, 2011
(C)opyright Michael B. Brutman, mbbrutman@gmail.com

