+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
| |
| SID (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| MBZ (12 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
In this message, zero in the Accept field means that the server is
willing to conduct the session. A non-zero value indicates rejection
of the request. The full list of available Accept values is
described in Section 3.3, "Values of the Accept Field".
If the server rejects a Request-Session message, it SHOULD not close
the TCP connection. The client MAY close it if it receives a
negative response to the Request-Session message.
The meaning of Port in the response depends on the values of Conf-
Sender and Conf-Receiver in the query that solicited the response.
If both were set, the Port field is unused. If only Conf-Sender was
set, Port is the port from which to expect OWAMP-Test packets. If
only Conf-Receiver was set, Port is the port to which OWAMP-Test
packets are sent.
If only Conf-Sender was set, the SID field in the response is unused.
Otherwise, SID is a unique server-generated session identifier. It
can be used later as handle to fetch the results of a session.
SIDs SHOULD be constructed by concatenation of the 4-octet IPv4 IP
number belonging to the generating machine, an 8-octet timestamp, and
a 4-octet random value. To reduce the probability of collisions, if
the generating machine has any IPv4 addresses (with the exception of
loopback), one of them SHOULD be used for SID generation, even if all
communication is IPv6-based. If it has no IPv4 addresses at all, the
last four octets of an IPv6 address MAY be used instead. Note that
SID is always chosen by the receiver. If truly random values are not
available, it is important that the SID be made unpredictable, as
knowledge of the SID might be used for access control.
3.6. Send Schedules
The sender and the receiver both need to know the same send schedule.
This way, when packets are lost, the receiver knows when they were
supposed to be sent. It is desirable to compress common schedules
and still to be able to use an arbitrary one for the test sessions.
In many cases, the schedule will consist of repeated sequences of
packets: this way, the sequence performs some test, and the test is
repeated a number of times to gather statistics.
To implement this, we have a schedule with a given number of slots.
Each slot has a type and a parameter. Two types are supported:
exponentially distributed pseudo-random quantity (denoted by a code
of 0) and a fixed quantity (denoted by a code of 1). The parameter
is expressed as a timestamp and specifies a time interval. For a
type 0 slot (exponentially distributed pseudo-random quantity), this
interval is the mean value (or 1/lambda if the distribution density
function is expressed as lambda*exp(-lambda*x) for positive values of
x). For a type 1 (fixed quantity) slot, the parameter is the delay
itself. The sender starts with the beginning of the schedule and
executes the instructions in the slots: for a slot of type 0, wait an
exponentially distributed time with a mean of the specified parameter
and then send a test packet (and proceed to the next slot); for a
slot of type 1, wait the specified time and send a test packet (and
proceed to the next slot). The schedule is circular: when there are
no more slots, the sender returns to the first slot.
The sender and the receiver need to be able to reproducibly execute
the entire schedule (so, if a packet is lost, the receiver can still
attach a send timestamp to it). Slots of type 1 are trivial to
reproducibly execute. To reproducibly execute slots of type 0, we
need to be able to generate pseudo-random exponentially distributed
quantities in a reproducible manner. The way this is accomplished is
discussed later in Section 5, "Computing Exponentially Distributed
Pseudo-Random Numbers".
Using this mechanism, one can easily specify common testing
scenarios. The following are some examples:
+ Poisson stream: a single slot of type 0.
+ Periodic stream: a single slot of type 1.
+ Poisson stream of back-to-back packet pairs: two slots, type 0
with a non-zero parameter and type 1 with a zero parameter.
Further, a completely arbitrary schedule can be specified (albeit
inefficiently) by making the number of test packets equal to the
number of schedule slots. In this case, the complete schedule is
transmitted in advance of an OWAMP-Test session.
3.7. Starting Test Sessions
Having requested one or more test sessions and received affirmative
Accept-Session responses, an OWAMP client MAY start the execution of
the requested test sessions by sending a Start-Sessions message to
the server.
The format of this message is as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 2 | |
+-+-+-+-+-+-+-+-+ |
| MBZ (15 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
The server MUST respond with an Start-Ack message (which SHOULD be
sent as quickly as possible). Start-Ack messages have the following
format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Accept | |
+-+-+-+-+-+-+-+-+ |
| MBZ (15 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
If Accept is non-zero, the Start-Sessions request was rejected; zero
means that the command was accepted. The full list of available
Accept values is described in Section 3.3, "Values of the Accept
Field". The server MAY, and the client SHOULD, close the connection
in the case of a rejection.
The server SHOULD start all OWAMP-Test streams immediately after it
sends the response or immediately after their specified start times,
whichever is later. If the client represents a Sender, the client
SHOULD start its OWAMP-Test streams immediately after it sees the
Start-Ack response from the Server (if the Start-Sessions command was
accepted) or immediately after their specified start times, whichever
is later. See more on OWAMP-Test sender behavior in a separate
section below.
3.8. Stop-Sessions
The Stop-Sessions message may be issued by either the Control-Client
or the Server. The format of this command is as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 3 | Accept | MBZ |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Sessions |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| MBZ (8 octets) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This is immediately followed by zero or more session description
records (the number of session description records is specified in
the "Number of Sessions" field above). The session description
record is used to indicate which packets were actually sent by the
sender process (rather than skipped). The header of the session
description record is as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
| |
| SID (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Next Seqno |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Number of Skip Ranges |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
This is immediately followed by zero or more Skip Range descriptions
as specified by the "Number of Skip Ranges" field above. Skip Ranges
are simply two sequence numbers that, together, indicate a range of
packets that were not sent:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-|
| First Seqno Skipped |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Last Seqno Skipped |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Skip Ranges MUST be in order. The last (possibly full, possibly
incomplete) block (16 octets) of data MUST be padded with zeros, if
necessary. This ensures that the next session description record
starts on a block boundary.
Finally, a single block (16 octets) of HMAC is concatenated on the
end to complete the Stop-Sessions message.
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| HMAC (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
All these records comprise one logical message: the Stop-Sessions
command.
Above, the first octet (3) indicates that this is the Stop-Sessions
command.
Non-zero Accept values indicate a failure of some sort. Zero values
indicate normal (but possibly premature) completion. The full list
of available Accept values is described in Section 3.3, "Values of
the Accept Field".
If Accept had a non-zero value (from either party), results of all
OWAMP-Test sessions spawned by this OWAMP-Control session SHOULD be
considered invalid, even if a Fetch-Session with SID from this
session works for a different OWAMP-Control session. If Accept was
not transmitted at all (for whatever reason, including the TCP
connection used for OWAMP-Control breaking), the results of all
OWAMP-Test sessions spawned by this OWAMP-control session MAY be
considered invalid.
Number of Sessions indicates the number of session description
records that immediately follow the Stop-Sessions header.
Number of Sessions MUST contain the number of send sessions started
by the local side of the control connection that have not been
previously terminated by a Stop-Sessions command (i.e., the Control-
Client MUST account for each accepted Request-Session where Conf-
Receiver was set; the Control-Server MUST account for each accepted
Request-Session where Conf-Sender was set). If the Stop-Sessions
message does not account for exactly the send sessions controlled by
that side, then it is to be considered invalid and the connection
SHOULD be closed and any results obtained considered invalid.
Each session description record represents one OWAMP-Test session.
SID is the session identifier (SID) used to indicate which send
session is being described.
Next Seqno indicates the next sequence number that would have been
sent from this send session. For completed sessions, this will equal
NumPackets from the Request-Session.
Number of Skip Ranges indicates the number of holes that actually
occurred in the sending process. This is a range of packets that
were never actually sent by the sending process. For example, if a
send session is started too late for the first 10 packets to be sent
and this is the only hole in the schedule, then "Number of Skip
Ranges" would be 1. The single Skip Range description will have
First Seqno Skipped equal to 0 and Last Seqno Skipped equal to 9.
This is described further in the "Sender Behavior" section.
If the OWAMP-Control connection breaks when the Stop-Sessions command
is sent, the receiver MAY not completely invalidate the session
results. It MUST discard all record of packets that follow (in other
words, that have greater sequence number than) the last packet that
was actually received before any lost packet records. This will help
differentiate between packet losses that occurred in the network and
packets the sending process may have never sent.
If a receiver of an OWAMP-Test session learns, through an OWAMP-
Control Stop-Sessions message, that the OWAMP-Test sender’s last
sequence number is lower than any sequence number actually received,
the results of the complete OWAMP-Test session MUST be invalidated.
A receiver of an OWAMP-Test session, upon receipt of an OWAMP-Control
Stop-Sessions command, MUST discard any packet records -- including
lost packet records -- with a (computed) send time that falls between
the current time minus Timeout and the current time. This ensures
statistical consistency for the measurement of loss and duplicates in
the event that the Timeout is greater than the time it takes for the
Stop-Sessions command to take place.
To effect complete sessions, each side of the control connection
SHOULD wait until all sessions are complete before sending the Stop-
Sessions message. The completed time of each session is determined
as Timeout after the scheduled time for the last sequence number.
Endpoints MAY add a small increment to the computed completed time
for send endpoints to ensure that the Stop-Sessions message reaches
the receiver endpoint after Timeout.
To effect a premature stop of sessions, the party that initiates this
command MUST stop its OWAMP-Test send streams to send the Session
Packets Sent values before sending this command. That party SHOULD
wait until receiving the response Stop-Sessions message before
stopping the receiver streams so that it can use the values from the
received Stop-Sessions message to validate the data.
3.9. Fetch-Session
The format of this client command is as follows:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 4 | |
+-+-+-+-+-+-+-+-+ |
| MBZ (7 octets) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Begin Seq |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| End Seq |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| SID (16 octets) |
| |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |