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.

ServerHello hello¶

message ServerHello {
  string server_id = 1;
  string redirect = 2;
  repeated string servers = 3;
  bool subcommands = 4;
}

The ServerHello message consists of server information sent when the client first connects. It contains the following members:

server_id

A free-form server description. Usually this includes the name and version of the implementation running on the log server. This member is always present.

redirect

A host and port separated by a colon (‘’): that the client should connect to instead. The host may be a host name, an IPv4 address, or an IPv6 address in square brackets. This may be used for server load balancing. The server will disconnect after sending the ServerHello when it includes a redirect.

servers

A list of other known log servers. This can be used to implement log server redundancy and allows the client to discover all other log servers simply by connecting to one known server. This member may be omitted when there is only a single log server.

subcommands

If set, the server supports logging additional commands during a session. The client may send an AcceptMessage or RejectMessage when sudo is running in intercept mode. In this mode, commands spawned from the initial command authorized by sudo are subject to policy restrictions and/or are logged. If subcommands is false, the client must not attempt to log additional commands.

TimeSpec commit_point¶

A periodic time stamp sent by the server to indicate when I/O log buffers have been committed to storage. This message is not sent after every IoBuffer but rather at a server-configurable interval. When the server receives an ExitMessage, it will respond with a commit_point corresponding to the last received IoBuffer before closing the connection.

string log_id¶

The server-side ID of the I/O log being stored, sent in response to an AcceptMessage where expect_iobufs is true.

string error¶

A fatal server-side error. The server will close the connection after sending the error message.

string abort¶

An abort message from the server indicates that the client should kill the command and terminate the session. It may be used to implement simple server-side policy. The server will close the connection after sending the abort message.