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