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