A ClientMessage is a container used to encapsulate all the possible
message types a client may send to the server.
message ClientMessage {
oneof type {
AcceptMessage accept_msg = 1;
RejectMessage reject_msg = 2;
ExitMessage exit_msg = 3;
RestartMessage restart_msg = 4;
AlertMessage alert_msg = 5;
IoBuffer ttyin_buf = 6;
IoBuffer ttyout_buf = 7;
IoBuffer stdin_buf = 8;
IoBuffer stdout_buf = 9;
IoBuffer stderr_buf = 10;
ChangeWindowSize winsize_event = 11;
CommandSuspend suspend_event = 12;
ClientHello hello_msg = 13;
}
}
The different ClientMessage sub-messages the client may sent to the
server are described below.
TimeSpec
message TimeSpec {
int64 tv_sec = 1;
int32 tv_nsec = 2;
}
A TimeSpec is the equivalent of a POSIX struct timespec, containing
seconds and nanoseconds members. The tv_sec member is a 64-bit
integer to support dates after the year 2038.
InfoMessage
message InfoMessage {
message StringList {
repeated string strings = 1;
}
message NumberList {
repeated int64 numbers = 1;
}
string key = 1;
oneof value {
int64 numval = 2;
string strval = 3;
StringList strlistval = 4;
NumberList numlistval = 5;
}
}
An InfoMessage is used to represent information about the invoking
user as well as the execution environment the command runs in the
form of key-value pairs. The key is always a string but the value
may be a 64-bit integer, a string, an array of strings or an array
of 64-bit integers. The event log data is composed of InfoMessage
entries. See the EVENT LOG VARIABLES section for more information.
ClientHello hello_msg
message ClientHello {
string client_id = 1;
}
A ClientHello message consists of client information that may be
sent to the server when the client first connects.
client_id
A free-form client description. This usually includes the
name and version of the client implementation.
AcceptMessage accept_msg
message AcceptMessage {
TimeSpec submit_time = 1;
repeated InfoMessage info_msgs = 2;
bool expect_iobufs = 3;
}
An AcceptMessage is sent by the client when a command is allowed by
the security policy. It contains the following members:
submit_time
The wall clock time when the command was submitted to the
security policy.
info_msgs
An array of InfoMessage describing the user who submitted
the command as well as the execution environment of the
command. This information is used to generate an event log
entry and may also be used by server to determine where and
how the I/O log is stored.
expect_iobufs
Set to true if the server should expect IoBuffer messages
to follow (for I/O logging) or false if the server should
only store the event log.
If an AcceptMessage is sent, the client must not send a
RejectMessage or RestartMessage.
RejectMessage reject_msg
message RejectMessage {
TimeSpec submit_time = 1;
string reason = 2;
repeated InfoMessage info_msgs = 3;
}
A RejectMessage is sent by the client when a command is denied by
the security policy. It contains the following members:
submit_time
The wall clock time when the command was submitted to the
security policy.
reason The reason the security policy gave for denying the
command.
info_msgs
An array of InfoMessage describing the user who submitted
the command as well as the execution environment of the
command. This information is used to generate an event log
entry.
If a RejectMessage is sent, the client must not send an
AcceptMessage or RestartMessage.
ExitMessage exit_msg
message ExitMessage {
TimeSpec run_time = 1;
int32 exit_value = 2;
bool dumped_core = 3;
string signal = 4;
string error = 5;
}
An ExitMessage is sent by the client after the command has exited
or has been terminated by a signal. It contains the following
members:
run_time
The total amount of elapsed time since the command started,
calculated using a monotonic clock where possible. This is
not the wall clock time.
exit_value
The command's exit value in the range 0-255.
dumped_core
True if the command was terminated by a signal and dumped
core.
signal If the command was terminated by a signal, this is set to
the name of the signal without the leading 'SIG'. For
example, INT, TERM, KILL, SEGV.
error A message from the client indicating that the command was
terminated unexpectedly due to an error.
When performing I/O logging, the client should wait for a
commit_point corresponding to the final IoBuffer before closing the
connection unless the final commit_point has already been received.
RestartMessage restart_msg
message RestartMessage {
string log_id = 1;
TimeSpec resume_point = 2;
}
A RestartMessage is sent by the client to resume sending an
existing I/O log that was previously interrupted. It contains the
following members:
log_id The the server-side name for an I/O log that was previously
sent to the client by the server. This may be a path name
on the server or some other kind of server-side identifier.
resume_point
The point in time after which to resume the I/O log. This
is in the form of a TimeSpec representing the amount of
time since the command started, not the wall clock time.
The resume_point should correspond to a commit_point
previously sent to the client by the server. If the server
receives a RestartMessage containing a resume_point it has
not previously seen, an error will be returned to the
client and the connection will be dropped.
If a RestartMessage is sent, the client must not send an
AcceptMessage or RejectMessage.
AlertMessage alert_msg
message AlertMessage {
TimeSpec alert_time = 1;
string reason = 2;
repeated InfoMessage info_msgs = 3;
}
An AlertMessage is sent by the client to indicate a problem
detected by the security policy while the command is running that
should be stored in the event log. It contains the following
members:
alert_time
The wall clock time when the alert occurred.
reason The reason for the alert.
info_msgs
An optional array of InfoMessage describing the user who
submitted the command as well as the execution environment
of the command. This information is used to generate an
event log entry.
IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf
message IoBuffer {
TimeSpec delay = 1;
bytes data = 2;
}
An IoBuffer is used to represent data from terminal input, terminal
output, standard input, standard output or standard error. It
contains the following members:
delay The elapsed time since the last record in the form of a
TimeSpec. The delay should be calculated using a monotonic
clock where possible.
data The binary I/O log data from terminal input, terminal
output, standard input, standard output or standard error.
ChangeWindowSize winsize_event
message ChangeWindowSize {
TimeSpec delay = 1;
int32 rows = 2;
int32 cols = 3;
}
A ChangeWindowSize message is sent by the client when the terminal
running the command changes size. It contains the following
members:
delay The elapsed time since the last record in the form of a
TimeSpec. The delay should be calculated using a monotonic
clock where possible.
rows The new number of terminal rows.
cols The new number of terminal columns.
CommandSuspend suspend_event
message CommandSuspend {
TimeSpec delay = 1;
string signal = 2;
}
A CommandSuspend message is sent by the client when the command is
either suspended or resumed. It contains the following members:
delay The elapsed time since the last record in the form of a
TimeSpec. The delay should be calculated using a monotonic
clock where possible.
signal The signal name without the leading 'SIG'. For example,
STOP, TSTP, CONT.
