
                            The NetPipe Protocol

                                   Rev. 0

                    by Jan Oberlnder <mindriot@gmx.net>

                                 06-13-1999

THIS DOCUMENTATION IS NOT COMPLETE  AND MAY NOT BE UP TO DATE. IT IS SAFER TO
                           CHECK THE SOURCE CODE!

DESCRIPTION

  NetPipe is a simple  UDP-based unicast  or broadcast  transfer protocol. It
  provides a simple basis for transferring binary data streams to one or mul-
  tiple stations in an IP subnet for use with pipe ends.
  
STRUCTURE

  NetPipe is a UDP protocol running by default on UDP port 9000 and employs a
  set of headered packets with minimum protocol overhead to  execute the data
  transactions. The transaction process consists of four phases:
  
    1. Seek Phase
    
      The sender seeks  the network for  clients to receive  the data  stream
      by sending search packets which the  clients reply to. The server keeps
      all replying clients in a list to keep  track of all stations receiving
      the data.
      
    2. Initialization Phase
    
      This rather short phase begins with the server sending out an initiali-
      sation packet which tells the clients to be ready for data. The clients
      answer with a simple acknowledging packet.
      
    3. Transaction Phase
    
      The server sends out sequenced data packets with a 32-bit CRC code. All
      clients must acknowledge each packet or send the appropriate error mes-
      sages. If a  client does not answer  within a certain time,  the server
      eventually discards that client. Clients ignore packets that have older
      sequence numbers and will send a sequence error if they are missing one
      packet in the sequence. In this case the clients will fail and are dis-
      carded by the server. If  the current packet  contained errors, clients
      send a CRC error message and the server will resend the current packet.
      Because NetPipe takes  the data to be sent from  input stream pipes, it
      can not seek back to resume  the transaction from any  point other than
      the current packet.
    
    4. End-Of-Transaction Phase
    
      Once the transaction ends, the server  sends out an EOT packet which is
      again answered by an acknowledge packet by all clients.
      
  NetPipe can be set up as a server which takes stdin data to transmit, or as
  client which receives data to write to stdout. Thus it works as a pipe bet-
  ween two, or in broadcast mode, multiple  stations in an IP network. It em-
  ploys a small set of one-byte  commands followed by  command-specific data.
  The packet size is kept as small as possible to avoid protocol overhead and
  to prevent  network congestions  resulting from many  clients responding to
  server commands at the same time.
  
    1. CM_PING - server ping command (0x01)
    
      The server ping  command is broadcast  to find clients  waiting  on the
      network. It includes a timestamp to be able to determine the connection
      quality.
      
      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x01 The command byte
      0x01 dword   tv_sec       timestamp seconds
      0x05 dword   tv_usec      timestamp microseconds
      
    2. CM_PONG - client ping reply (0x02)
    
      Clients reply to server pings with this command, sending back the time-
      stamp transmitted by the server.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x02 The command byte
      0x01 dword   tv_sec       timestamp seconds
      0x05 dword   tv_usec      timestamp microseconds

    3. CM_SEQ_INIT - initiate transaction sequence (0x03)
    
      The server sends this command to  prepare the clients for the beginning
      of the transaction.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x03 The command byte
      0x01 dword   flags        Transaction flags:
                                 0x00000001: only one client must answer
                                 
    4. CM_READY - client seq_init reply - ready to start transaction (0x04)
    
      Via CM_READY the clients denote that they are ready to begin the trans-
      action.
      
      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x04 The command byte

    5. CM_TX - server sends data packet (0x05)
    
      The server send out a data packet of variable size (up to 4 GB), inclu-
      ding a 32-bit CRC code and a 32-bit sequence number.
      
      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x05 The command byte
      0x01 dword   seqnum       Sequence number
      0x05 dword   len          Length of data block to follow
      0x09 bytes   data         Data block
      0xnn dword   crc          CRC-32
    
    6. CM_RXOK - client receive acknowledge code (0x06)
    
      This way each clients acknowledges the last data packet, using only the
      command byte to avoid collisions.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x06 The command byte
      
    7. CM_RXERR - client receive error (0x07)
    
      On error the client sends this packet including a status field.
      
      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x07 The command byte
      0x01 dword   error        Error code:
                                 0x00000001: CRC error, retry
                                 0x00000002: Sequence error, fatal

    8. CM_ERROR - client general error (0x08)

      This code is used for errors other than receive errors.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x08 The command byte
      0x01 dword   error        Error code:
                                 0x00000001: User abort, fatal
                                 0x00000002: Internal error, see errno; fatal
      0x05 dword   errno        Linux errno.h code number
      
    9. CM_EOT - End-Of-Transaction signal (0x09)
    
      The server hereby states the transaction completion.
      
      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x09 The command byte

   10. CM_DONE - client EOT acknowledgement (0x0A)
   
      The client's reply to CM_EOT.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x0A The command byte
 
   11. CM_ACK_PLZ - tell client to acknowledge each packet (0x0B)
   
      This is for  the [-1] mode  in which only  one client will acknowledge.
      The client who receives  this packet must acknowledge while others will
      turn off  acknowledging by  default once they get a  CM_SEQ_INIT packet
      with bit zero set.

      Ofs  Type    Name    Val  Description
      -----------------------------------------------------------------------
      0x00 byte    cmd     0x0A The command byte
 
COPYING
 
  The NetPipe program, its  source code and this document are distributed un-
  der the  GNU General  Public License.  Deleting  my name  from any of these
  files results in seven years of  bad luck or so... - well, just be nice and
  don't do it, you know the rules.

DISCLAIMER

  The software  is provided with no  warranty  whatsoever. The  author is not
  responsible for any kind of damage resulting  from the use of this software
  or the use of the source  code or  parts of it.  By using this program, the
  user acknowledges and accepts this disclaimer.

AUTHOR

  This software and the NetPipe protocol were created by:
    Jan Oberlnder <mindriot@gmx.net>
  Use the above email address for questions, comments, bug reports etc.
