GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


rfc:ien:ien172
                      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
/data/webs/external/dokuwiki/data/pages/rfc/ien/ien172.txt · Last modified: 2001/06/25 20:35 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki