A SIMPLE MESSAGE GENERATOR
     
     
     
     
     
     
                                  IEN 172
     
     
     
     
     
     
     
     
     
     
     
                             David Flood Page
     
     
     
     
     
     
                               9 March 1981
     
     
     
     
     
     
     
     
     
     
     
                       Bolt, Beranek and Newman Inc.
     
     
                             50 Moulton Street
     
     
                      Cambridge, Massachusetts 02238

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
                             TABLE OF CONTENTS
     
     
     
     
                                                                  Page
         1  Introduction                                             1
         2  Overview of TRAF and the subset described here           1
         3  The User-Server Interaction                              3
         4  Message formats                                          6
              4.1  User to Server Messages                           7
              4.2  Server to user Messages                           7
              4.3  Argument Structures                               8
              4.4  Error Messages                                   12
         5  Echo/Sink Servers                                       14
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                                     i

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     1  Introduction
     
     
          We  want  to  have  a controllable message generator for the
     
     Catenet that will be simple to implement.  There currently exists
     
     the TRAF system which was built to do  performance  measures  for
     
     another  project;  this  document  describes a subset of the TRAF
     
     facilities aimed at producing a simple message generator that can
     
     be controlled by the  existing  TRAF  control  system.    A  full
     
     specification and description of TRAF will be issued later.
     
     
          Because  we  want it to be controllable by the existing TRAF
     
     control system, the server will have to  include  a  TCP.    This
     
     conflicts  slightly  with  the idea of a minimal server, but will
     
     allow us to get things working faster.   At  some  point  in  the
     
     future  we  will define a simpler, XNET-like protocol for control
     
     of the server; the message contents will be  the  same  as  those
     
     described here in any case.  The messages will be transmitted via
     
     UDP.
     
     
     
     2  Overview of TRAF and the subset described here
     
     
          TRAF  consists  of  two  programs:    a controlling program,
     
     called the user program, which runs  on  a  Unix  system,  and  a
     
     server  program,  which  runs  on a PDP-11 (or LSI-11) under MOS.
     
     One user program can control many instances of the server.    The
     
     user  program  communicates with the servers via TCP connections,
     
     so the servers do not have to be on the same net as the user.
     
     
                                     1

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
          The user program provides three basic services:
     
     
       1.  It accepts and executes the user's commands, entered at
           a  terminal.    Often  these  commands  cause  the user
           program to forward commands to a server.
     
       2.  It  displays  the  results  of  its  actions,  messages
           received  from  the  servers,  and  the  status  of the
           message generation activity it controls.
     
       3.  It performs various file handling  functions,  such  as
           storing job definitions and command files.
     
     
          The Server program provides three basic services:
     
     
       1.  Packet  echo  delay  or TCP connection open/close delay
           jobs.  These jobs generate messages.
     
       2.  Echo jobs.    These  just  echo  packets  after  a  TCP
           connection has been established.
     
       3.  Special  TCP  and  UDP ports which act as raw echoes or
           sinks (depending on the port number), without the  need
           to open any connections.
     
     
          A  full  TRAF  server  will perform these functions and also
     
     gather data about the delays it sees.  This  data  is  then  sent
     
     back  to the user program.  This specification deals with message
     
     generation but not with data gathering.  It describes a subset of
     
     the message generation commands which will allow control  by  the
     
     existing user program.
     
     
     
     
     
     
     
     
     
                                     2

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     3  The User-Server Interaction
     
     
          When  the  server  starts  up  it  listens  on  TCP  port 51
     
     (decimal).  The user establishes a connection on  this  port  and
     
     this  causes  the  server to set up a process called the session,
     
     which then accepts commands from  the  user  program,  and  sends
     
     responses back to it, over the TCP connection.
     
     
          Servers  without  a TCP will listen on UDP port 51 (decimal)
     
     for the messages from the user program.  The first  message  from
     
     the  user  program  will  be  a  "Set time and date" message (see
     
     below).
     
     
          In addition, the user and server send echo requests, and the
     
     appropriate responses, to each other every 30 seconds,  to  check
     
     that the connection is still working.  If either end times out an
     
     echo request, then it closes the connection.  The timeout time is
     
     2 minutes.
     
     
          A   session  can  be  in  a  number  of  states,  and  state
     
     transitions are caused by user commands.  The states used in this
     
     specification are:
     
     
           o  Defined
     
           o  Started
     
           o  Aborted
     
           o  Ended
     
           o  Active
     
     
                                     3

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
          A  session  is  active  if  it  has active jobs running (see
     
     below).  The following is the state transition table:
     
     
                                   SESSION  STATE
                       +---------+---------+---------+----------+
                       |         |         |         |          |
                       | Defined | Started | Aborted |  Active  |
                       |         |         |         |          |
            C +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            O | Start  | started | error s3| started | error s3 |
              |        |         |         |         |          |
            M +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            M | Abort  | aborted | aborted |error s9 | aborted  |
              |        |         |         |         |          |
            A +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            N |  End   |  ended  |  ended  |  ended  |  ended   |
              |        |         |         |         |          |
            D +--------+---------+---------+---------+----------+
     
     
     
     Where an error is indicated, no state transition takes place.   A
     
     session  enters  the  Defined  state  when  the TCP connection is
     
     established.  A session that is ended goes  away  completely,  so
     
     there are no transitions from the Ended state.
     
     
          Details  of  command  formats are given in section 4.  If an
     
     active session is aborted,  all  jobs  within  that  session  are
     
     ended.  (See below.)
     
     
          A  session  creates  processes called jobs to do the message
     
     generation.  The full TRAF server  allows  multiple  jobs  to  be
     
     running   simultaneously  within  a  session,  but  this  is  not
     
     
     
     
     
                                     4

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     essential to the operation of the system; one only will do.
     
     
          A  job  can be in one of several states.  The states we will
     
     use are:
     
     
         Job       defined
     
                   started
     
                   aborted
     
                   done
     
                   ended.  (undefined)
     
     
          As with sessions, job state transitions are caused  by  user
     
     commands.  The commands we will use are:
     
     
           o  job start
     
           o  job abort
     
           o  job end
     
     
          The state transition table is given below.  A job enters the
     
     Done state when it has run to completion, and when a job is ended
     
     it  goes  away  altogether,  i.e. its resources are freed; so, as
     
     with sessions, there are no transitions from the Ended state.
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                                     5

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
                                   JOB  STATE
                       +---------+---------+---------+----------+
                       |         |         |         |          |
                       | Defined | Started | Aborted |   Done   |
                       |         |         |         |          |
            C +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            O | Start  | started | error j9| started | started  |
              |        |         |         |         |          |
            M +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            M | Abort  | aborted | aborted |error j16| aborted  |
              |        |         |         |         |          |
            A +--------+---------+---------+---------+----------+
              |        |         |         |         |          |
            N |  End   |  ended  |  ended  |  ended  |  ended   |
              |        |         |         |         |          |
            D +--------+---------+---------+---------+----------+
     
     
     
          A  job  is  initially  defined by an "assign and define job"
     
     command.  The argument list  for  this  command  includes  a  job
     
     number,  called  the  user job number, assigned to it by the user
     
     program.  The server assigns its own job number to  the  job  and
     
     returns   that   job   number   to   the   user  program  in  its
     
     acknowledgement;  all  further  references   to   that   job   in
     
     user-server  or  server-user messages use the job number assigned
     
     by the server.
     
     
     
     4  Message formats
     
     
          Bits within fields are  numbered  according  to  the  PDP-11
     
     convention, i.e. bit 0 is the least significant bit.
     
     
          All  communication  between  user  and server programs takes
     
     
     
     
                                     6

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     place  over  a  TCP  connection.    The server listens on port 51
     
     (decimal) and the user host initiates the connection.
     
     
          The first octet of every message is the opcode.  This opcode
     
     defines the operation required and determines  the  structure  of
     
     the rest of the message.  The next two sections list the opcodes,
     
     their  meanings,  and  the  argument  structure  (if  any) of the
     
     messages.  All numbers are in decimal.
     
     
     4.1  User to Server Messages
     
     
     Opcode  Meaning                       Argument Structure
     
        0    echo request                  octet to be echoed
        1    echo response                 echoed octet
        2    set time and date             version number, 16 bits
                                           Unix format time and date,
                                           32 bits
        5    return job state information  job number, 1 octet
        6    return session state
        7    start session
        11   abort session
        12   end session
        13   assign and define job         job definition block,
                                           see below.
     
        14   start job                     job number, 1 octet
        18   abort job                     job number, 1 octet
        19   end job                       job number, 1 octet
        20   error reset                   job number, 1 octet
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                                     7

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     4.2  Server to user Messages
     
     Opcode  Meaning                 Argument Structure
     
        0    echo request            octet to be echoed
        1    echo response           echoed octet
        2    set time and date
        5    job state information   job number, 1 octet
                                     job state vector, see below.
        6    session state           session state vector, see below.
        7    session started
        11   session aborted
        12   session ended
        13   job assigned            server job number, 1 octet
                                     user job number, 16 bits
        14   job started             job number, 1 octet
        18   job aborted             job number, 1 octet
        19   job ended               job number, 1 octet
        21   job complete            job number, 1 octet
        22   error                   job number, 1 octet
                                     number of characters in error
                                     string, 16 bits
                                     error string.
     
     
     
          Note that server-user opcode 19 (job ended) is a response to
     
     user-server   opcode   19  (end  job),  while  opcode  21  is  an
     
     asynchronous message indicating that the job has run to its end.
     
     
          The response to any opcode not included  here  is  an  error
     
     message  for  that  opcode with the string "Limited server only".
     
     See error messages, below.
     
     
     4.3  Argument Structures
     
     
          These are the formats for the arguments whose format is  not
     
     fully specified in the preceding sections.
     
     
     
     
     
     
     
                                     8

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     4.3.1  Job Definition Block
     
     
     Field Name                     Size (Octets)       See Note
     
     job option word                      2                1
     job duration, low order              2                2
     job duration, high order             2                2
     destination net                      1
     destination host                     1
     destination tcp id                   1
     destination logical host             1
     number of outstanding packets        2
     unused in this specification         2
     lower limit of packet size           2
     upper limit of packet size           2
     unused in this specification        10
     user job number                      2                3
     job comment                         80                4
     
     
          Notes:
     
     
       1.  The  job  option  word  is  a  16  bit  field.  The bit
           settings  relevant  here  are:  (bit  0  is  the  least
           significant)
     
     
           0               must  be  set.  Indicates an echo delay
                           job.
     
           1               If  set,  the  server  will  send   UDP
                           datagrams; if not, TCP datagrams.
     
           2               If  set, indicates that messages are to
                           be  sent  to  the  sink  port  on   the
                           destination host; if unset, to the echo
                           port.
     
           3               Not used in this specification.
     
           4               Not used in this specification.
     
     
       2.  Job duration is in units of 0.1 second.
     
       3.  The  user  job  number  is  sent  back  with  the  "job
     
     
     
     
                                     9

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
           assigned"  message,  along  with the server job number;
           thereafter, only the server job number is used.
     
       4.  The job comment is not used by this limited server.
     
     
     4.3.2  Job State Vector
     
     
     Field Name                          Size(Octets)      See Note
     
     Job state word                            2              1
     TCP state word                            2              2
     (Internal information)                   26
     low order of time left to run             2              3
     high order of time left to run            2              3
     unused in this specification              2
     echo delay data queue                     4              4
     unused in this specification              8
     
     
     
          Notes:
     
     
       1.  The job state word has the following bit settings:
     
     
           0               job defined
     
           1               job started
     
           3               job aborted
     
           5               job done
     
           10              job is an echo delay job
     
           11              job is currently active
     
           13              error sent (waiting for reset)
     
           14              restart process  after  tcp  connection
                           closes
     
     
           Bits  not  specified are not part of this specification
           subset.
     
     
     
     
                                    10

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
       2.  The TCP state word has the following bit settings.
     
     
           0               open wait
     
           1               send wait
     
           2               read wait
     
           3               close wait
     
           4               connection open
     
           5               abort connection
     
           6               close connection after write
     
           7               data  successfully read at some time on
                           connection
     
           8               data successfully sent at some time  on
                           connection
     
     
       3.  The  time  left to run is a 32 bit quantity in units of
           0.1 second.
     
       4.  Data queues consist of a pointer and  an  entry  count.
           The  pointer  is  for internal use only and need not be
           set; the entry count is just the number of items on the
           queue.
     
     
     4.3.3  Session State Vector
     
          A session state vector consists of 2  16-bit  fields.    The
     
     first is the session state, with bit settings as follows:
     
     
        Bit
         0     session is defined (tcp connection is open)
         1     session is started and idle (no active jobs)
         2     session is started and active
         3
         4     session is aborted.
     
     
     
     
     
     
                                    11

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
          The  second  field  is the TCP status word, with settings as
     
     shown in 2. above.  (Job status vector)
     
     
     4.4  Error Messages
     
     
          The high order 2 bits in the server to user upcode are  used
     
     to  signal  an  error condition (bit 7) or message condition (bit
     
     6).  When either bit is  set,  a  string  is  returned  with  the
     
     opcode.  This string has the format:
     
     
         number of characters in string, 1 octet
         string, ASCII octets
         null octet
     
     
          If the opcode is normally followed by a job number then that
     
     precedes  the  string.   The error bit is set in the asynchronous
     
     error message (opcode 22).
     
     
          If this limited server receives an opcode that it  does  not
     
     understand,  then  it  will  send  back  a message containing the
     
     opcode with the error bit set on,  and  an  error  string  saying
     
     "Limited server only".
     
     
     4.4.1  Session Related Errors and Messages
     
          s1   Server identifying message.  For this limited server it
     
     will be "TRAF Limited Server.  Version n (<date>)".
     
     
          This  is  sent  when  the server receives a time set command
     
     from the user.
     
     
     
     
                                    12

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     s3        Session already started
     s4        Session active, must be aborted
     s9        Session already aborted
     
     
          Errors  s3,  s4,  s9  are  sent in response to illegal state
     
     transition requests.
     
     
     s12       No new jobs currently available.
     
     
          This is sent when the server has no new jobs with  which  to
     
     satisfy an assign request.
     
     
     s13       Illegal job number
     
     
          This  is sent if the server receives a request containing an
     
     undefined job number.
     
     
     s14       Server using a newer version of the TRAF protocol.
     s15       Server using an older version of the TRAF protocol
     
     
          The time set command contains  a  version  number;  if  this
     
     doesn't match the server's version number, s14 or s15 is returned
     
     and the TCP connection is closed.
     
     
     s16       Echo request timeout, connection closed.
     
     
     
          If  the server doesn't get a response to one or its periodic
     
     echo requests within a 2  minutes,  it  sends  this  message  and
     
     closes the connection.
     
     
     
     
     
     
                                    13

Bolt Beranek and Newman Inc.                              IEN 172
     
     
     
     
     4.4.2  Job Related Errors and Messages
     
     
     j1        Connection error
     j2        Dead foreign host
     j3        TCP connection refused
     j4        Unexpected connection close
     j5        TCP/UDP buffer unavailable
     j6        TCP send error
     
     
     
          These  are  messages  relating  to  errors  in the job's TCP
     
     connection, if any.
     
     
     j9        Job already started
     j15       Job was aborted
     j16       Job already aborted
     j19       Job done
     
     
     
          These are messages relating to job state transitions.
     
     
     
     5  Echo/Sink Servers
     
     
          The server will echo any TCP or UDP packets sent to  port  7
     
     by  swapping  the source and destination addresses and ports, and
     
     sending the packet out again.  This means that, for TCP echo,  no
     
     TCP  connection  is  established  to  the  server; in effect, the
     
     connection is made by the source of the packets to itself.
     
     
          Port 9 is the sink port.  UDP packets sent to port 9  should
     
     be  discarded  with  no  acknowledgement.    For  TCP the case is
     
     different, because even discarded packets must  be  acknowledged,
     
     
     
     
     
                                    14

IEN 172                              Bolt Beranek and Newman Inc.
     
     
     
     
     so it will be necessary to open a TCP connection to port 9 to use
     
     it as a sink.  Servers which do not have a TCP will therefore not
     
     offer this facility.
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
                                    15