mirror of https://github.com/sudo-project/sudo.git
924 lines
23 KiB
Groff
924 lines
23 KiB
Groff
.\" Automatically generated from the sudo_logsrv.proto.mdoc.in file. Do not edit.
|
|
.\"
|
|
.\" SPDX-License-Identifier: ISC
|
|
.\"
|
|
.\" Copyright (c) 2019-2022 Todd C. Miller <Todd.Miller@sudo.ws>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.TH "SUDO_LOGSRV.PROTO" "@mansectform@" "September 13, 2022" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
|
|
.nh
|
|
.if n .ad l
|
|
.SH "NAME"
|
|
\fBsudo_logsrv.proto\fR
|
|
\- Sudo log server protocol
|
|
.SH "DESCRIPTION"
|
|
Starting with version 1.9.0,
|
|
\fBsudo\fR
|
|
supports sending event and I/O logs to a log server.
|
|
The protocol used is written in Google's Protocol Buffers domain
|
|
specific language.
|
|
The
|
|
\fIEXAMPLES\fR
|
|
section includes a complete description of the protocol in Protocol
|
|
Buffers format.
|
|
.PP
|
|
Because there is no way to determine message boundaries when using
|
|
Protocol Buffers, the wire size of each message is sent immediately
|
|
preceding the message itself as a 32-bit unsigned integer in network
|
|
byte order.
|
|
This is referred to as
|
|
\(lqlength-prefix framing\(rq
|
|
and is how Google suggests handling the lack of message delimiters.
|
|
.PP
|
|
The protocol is made up of two basic messages,
|
|
\fIClientMessage\fR
|
|
and
|
|
\fIServerMessage\fR,
|
|
described below.
|
|
The server must accept messages up to two megabytes in size.
|
|
The server may return an error if the client tries to send a message
|
|
larger than two megabytes.
|
|
.SH "Client Messages"
|
|
A
|
|
\fIClientMessage\fR
|
|
is a container used to encapsulate all the possible message types
|
|
a client may send to the server.
|
|
.nf
|
|
.sp
|
|
.RS 0n
|
|
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;
|
|
}
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
The different
|
|
\fIClientMessage\fR
|
|
sub-messages the client may sent to the server are described below.
|
|
.SS "TimeSpec"
|
|
.nf
|
|
.RS 0n
|
|
message TimeSpec {
|
|
int64 tv_sec = 1;
|
|
int32 tv_nsec = 2;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fITimeSpec\fR
|
|
is the equivalent of a POSIX
|
|
\fIstruct timespec\fR,
|
|
containing seconds and nanoseconds members.
|
|
The
|
|
\fItv_sec\fR
|
|
member is a 64-bit integer to support dates after the year 2038.
|
|
.SS "InfoMessage"
|
|
.nf
|
|
.RS 0n
|
|
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;
|
|
}
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
An
|
|
\fIInfoMessage\fR
|
|
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
|
|
\fIInfoMessage\fR
|
|
entries.
|
|
See the
|
|
\fIEVENT LOG VARIABLES\fR
|
|
section for more information.
|
|
.SS "ClientHello hello_msg"
|
|
.nf
|
|
.RS 0n
|
|
message ClientHello {
|
|
string client_id = 1;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fIClientHello\fR
|
|
message consists of client information that may be sent to the
|
|
server when the client first connects.
|
|
.TP 8n
|
|
client_id
|
|
A free-form client description.
|
|
This usually includes the name and version of the client implementation.
|
|
.SS "AcceptMessage accept_msg"
|
|
.nf
|
|
.RS 0n
|
|
message AcceptMessage {
|
|
TimeSpec submit_time = 1;
|
|
repeated InfoMessage info_msgs = 2;
|
|
bool expect_iobufs = 3;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
An
|
|
\fIAcceptMessage\fR
|
|
is sent by the client when a command is allowed by the security policy.
|
|
It contains the following members:
|
|
.TP 8n
|
|
submit_time
|
|
The wall clock time when the command was submitted to the security policy.
|
|
.TP 8n
|
|
info_msgs
|
|
An array of
|
|
\fIInfoMessage\fR
|
|
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.
|
|
.TP 8n
|
|
expect_iobufs
|
|
Set to true if the server should expect
|
|
\fIIoBuffer\fR
|
|
messages to follow (for I/O logging) or false if the server should only
|
|
store the event log.
|
|
.PP
|
|
If an
|
|
\fIAcceptMessage\fR
|
|
is sent, the client must not send a
|
|
\fIRejectMessage\fR
|
|
or
|
|
\fIRestartMessage\fR.
|
|
.SS "RejectMessage reject_msg"
|
|
.nf
|
|
.RS 0n
|
|
message RejectMessage {
|
|
TimeSpec submit_time = 1;
|
|
string reason = 2;
|
|
repeated InfoMessage info_msgs = 3;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fIRejectMessage\fR
|
|
is sent by the client when a command is denied by the security policy.
|
|
It contains the following members:
|
|
.TP 8n
|
|
submit_time
|
|
The wall clock time when the command was submitted to the security policy.
|
|
.TP 8n
|
|
reason
|
|
The reason the security policy gave for denying the command.
|
|
.TP 8n
|
|
info_msgs
|
|
An array of
|
|
\fIInfoMessage\fR
|
|
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.
|
|
.PP
|
|
If a
|
|
\fIRejectMessage\fR
|
|
is sent, the client must not send an
|
|
\fIAcceptMessage\fR
|
|
or
|
|
\fIRestartMessage\fR.
|
|
.SS "ExitMessage exit_msg"
|
|
.nf
|
|
.RS 0n
|
|
message ExitMessage {
|
|
TimeSpec run_time = 1;
|
|
int32 exit_value = 2;
|
|
bool dumped_core = 3;
|
|
string signal = 4;
|
|
string error = 5;
|
|
}
|
|
.PP
|
|
.RE
|
|
.fi
|
|
An
|
|
\fIExitMessage\fR
|
|
is sent by the client after the command has exited or has been
|
|
terminated by a signal.
|
|
It contains the following members:
|
|
.TP 8n
|
|
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.
|
|
.TP 8n
|
|
exit_value
|
|
The command's exit value in the range 0-255.
|
|
.TP 8n
|
|
dumped_core
|
|
True if the command was terminated by a signal and dumped core.
|
|
.TP 8n
|
|
signal
|
|
If the command was terminated by a signal, this is set to the
|
|
name of the signal without the leading
|
|
\(lqSIG\(rq.
|
|
For example,
|
|
\fRINT\fR,
|
|
\fRTERM\fR,
|
|
\fRKILL\fR,
|
|
\fRSEGV\fR.
|
|
.TP 8n
|
|
error
|
|
A message from the client indicating that the command was terminated
|
|
unexpectedly due to an error.
|
|
.PP
|
|
When performing I/O logging, the client should wait for a
|
|
\fIcommit_point\fR
|
|
corresponding to the final
|
|
\fIIoBuffer\fR
|
|
before closing the connection unless the final
|
|
\fIcommit_point\fR
|
|
has already been received.
|
|
.SS "RestartMessage restart_msg"
|
|
.nf
|
|
.RS 0n
|
|
message RestartMessage {
|
|
string log_id = 1;
|
|
TimeSpec resume_point = 2;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fIRestartMessage\fR
|
|
is sent by the client to resume sending an existing I/O log that
|
|
was previously interrupted.
|
|
It contains the following members:
|
|
.TP 8n
|
|
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.
|
|
.TP 8n
|
|
resume_point
|
|
The point in time after which to resume the I/O log.
|
|
This is in the form of a
|
|
\fITimeSpec\fR
|
|
representing the amount of time since the command started, not
|
|
the wall clock time.
|
|
The
|
|
\fIresume_point\fR
|
|
should correspond to a
|
|
\fIcommit_point\fR
|
|
previously sent to the client by the server.
|
|
If the server receives a
|
|
\fIRestartMessage\fR
|
|
containing a
|
|
\fIresume_point\fR
|
|
it has not previously seen, an error will be returned to the client
|
|
and the connection will be dropped.
|
|
.PP
|
|
If a
|
|
\fIRestartMessage\fR
|
|
is sent, the client must not send an
|
|
\fIAcceptMessage\fR
|
|
or
|
|
\fIRejectMessage\fR.
|
|
.SS "AlertMessage alert_msg"
|
|
.nf
|
|
.RS 0n
|
|
message AlertMessage {
|
|
TimeSpec alert_time = 1;
|
|
string reason = 2;
|
|
repeated InfoMessage info_msgs = 3;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
An
|
|
\fIAlertMessage\fR
|
|
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:
|
|
.TP 8n
|
|
alert_time
|
|
The wall clock time when the alert occurred.
|
|
.TP 8n
|
|
reason
|
|
The reason for the alert.
|
|
.TP 8n
|
|
info_msgs
|
|
An optional array of
|
|
\fIInfoMessage\fR
|
|
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.
|
|
.SS "IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf"
|
|
.nf
|
|
.RS 0n
|
|
message IoBuffer {
|
|
TimeSpec delay = 1;
|
|
bytes data = 2;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
An
|
|
\fIIoBuffer\fR
|
|
is used to represent data from terminal input, terminal
|
|
output, standard input, standard output, or standard error.
|
|
It contains the following members:
|
|
.TP 8n
|
|
delay
|
|
The elapsed time since the last record in the form of a
|
|
\fITimeSpec\fR.
|
|
The
|
|
\fIdelay\fR
|
|
should be calculated using a monotonic clock where possible.
|
|
.TP 8n
|
|
data
|
|
The binary I/O log data from terminal input, terminal output,
|
|
standard input, standard output, or standard error.
|
|
.SS "ChangeWindowSize winsize_event"
|
|
.nf
|
|
.RS 0n
|
|
message ChangeWindowSize {
|
|
TimeSpec delay = 1;
|
|
int32 rows = 2;
|
|
int32 cols = 3;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fIChangeWindowSize\fR
|
|
message is sent by the client when the terminal running the command
|
|
changes size.
|
|
It contains the following members:
|
|
.TP 8n
|
|
delay
|
|
The elapsed time since the last record in the form of a
|
|
\fITimeSpec\fR.
|
|
The
|
|
\fIdelay\fR
|
|
should be calculated using a monotonic clock where possible.
|
|
.TP 8n
|
|
rows
|
|
The new number of terminal rows.
|
|
.TP 8n
|
|
cols
|
|
The new number of terminal columns.
|
|
.SS "CommandSuspend suspend_event"
|
|
.nf
|
|
.RS 0n
|
|
message CommandSuspend {
|
|
TimeSpec delay = 1;
|
|
string signal = 2;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
A
|
|
\fICommandSuspend\fR
|
|
message is sent by the client when the command is either suspended
|
|
or resumed.
|
|
It contains the following members:
|
|
.TP 8n
|
|
delay
|
|
The elapsed time since the last record in the form of a
|
|
\fITimeSpec\fR.
|
|
The
|
|
\fIdelay\fR
|
|
should be calculated using a monotonic clock where possible.
|
|
.TP 8n
|
|
signal
|
|
The signal name without the leading
|
|
\(lqSIG\(rq.
|
|
For example,
|
|
\fRSTOP\fR,
|
|
\fRTSTP\fR,
|
|
\fRCONT\fR.
|
|
.SH "Server Messages"
|
|
A
|
|
\fIServerMessage\fR
|
|
is a container used to encapsulate all the possible message types
|
|
the server may send to a client.
|
|
.nf
|
|
.sp
|
|
.RS 0n
|
|
message ServerMessage {
|
|
oneof type {
|
|
ServerHello hello = 1;
|
|
TimeSpec commit_point = 2;
|
|
string log_id = 3;
|
|
string error = 4;
|
|
string abort = 5;
|
|
}
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
The different
|
|
\fIServerMessage\fR
|
|
sub-messages the server may sent to the client are described below.
|
|
.SS "ServerHello hello"
|
|
.nf
|
|
.RS 0n
|
|
message ServerHello {
|
|
string server_id = 1;
|
|
string redirect = 2;
|
|
repeated string servers = 3;
|
|
bool subcommands = 4;
|
|
}
|
|
.RE
|
|
.fi
|
|
.PP
|
|
The
|
|
\fIServerHello\fR
|
|
message consists of server information sent when the client first connects.
|
|
It contains the following members:
|
|
.TP 8n
|
|
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.
|
|
.TP 8n
|
|
redirect
|
|
A host and port separated by a colon
|
|
(\(oq\(cq):
|
|
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
|
|
\fIServerHello\fR
|
|
when it includes a
|
|
\fBredirect\fR.
|
|
.TP 8n
|
|
servers
|
|
.br
|
|
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.
|
|
.TP 8n
|
|
subcommands
|
|
If set, the server supports logging additional commands during a session.
|
|
The client may send an
|
|
\fIAcceptMessage\fR
|
|
or
|
|
\fIRejectMessage\fR
|
|
when
|
|
\fBsudo\fR
|
|
is running in
|
|
\fIintercept\fR
|
|
mode.
|
|
In this mode, commands spawned from the initial command authorized by
|
|
\fBsudo\fR
|
|
are subject to policy restrictions and/or are logged.
|
|
If
|
|
\fIsubcommands\fR
|
|
is false, the client must not attempt to log additional commands.
|
|
.SS "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
|
|
\fIIoBuffer\fR
|
|
but rather at a server-configurable interval.
|
|
When the server receives an
|
|
\fIExitMessage\fR,
|
|
it will respond with a
|
|
\fIcommit_point\fR
|
|
corresponding to the last received
|
|
\fIIoBuffer\fR
|
|
before closing the connection.
|
|
.SS "string log_id"
|
|
The server-side ID of the I/O log being stored, sent in response
|
|
to an
|
|
\fIAcceptMessage\fR
|
|
where
|
|
\fIexpect_iobufs\fR
|
|
is true.
|
|
.SS "string error"
|
|
A fatal server-side error.
|
|
The server will close the connection after sending the
|
|
\fIerror\fR
|
|
message.
|
|
.SS "string abort"
|
|
An
|
|
\fIabort\fR
|
|
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
|
|
\fIabort\fR
|
|
message.
|
|
.SH "Protocol flow of control"
|
|
The expected protocol flow is as follows:
|
|
.TP 5n
|
|
1.\&
|
|
Client connects to the first available server.
|
|
If the client is configured to use TLS, a TLS handshake will be
|
|
attempted.
|
|
.TP 5n
|
|
2.\&
|
|
Client sends
|
|
\fIClientHello\fR.
|
|
This is currently optional but allows the server to detect a
|
|
non-TLS connection on the TLS port.
|
|
.TP 5n
|
|
3.\&
|
|
Server sends
|
|
\fIServerHello\fR.
|
|
.TP 5n
|
|
4.\&
|
|
Client responds with either
|
|
\fIAcceptMessage\fR,
|
|
\fIRejectMessage\fR,
|
|
or
|
|
\fIRestartMessage\fR.
|
|
.TP 5n
|
|
5.\&
|
|
If client sent a
|
|
\fIAcceptMessage\fR
|
|
with
|
|
\fIexpect_iobufs\fR
|
|
set, server creates a new I/O log and responds with a
|
|
\fIlog_id\fR.
|
|
.TP 5n
|
|
6.\&
|
|
Client sends zero or more
|
|
\fIIoBuffer\fR
|
|
messages.
|
|
.TP 5n
|
|
7.\&
|
|
Server periodically responds to
|
|
\fIIoBuffer\fR
|
|
messages with a
|
|
\fIcommit_point\fR.
|
|
.TP 5n
|
|
8.\&
|
|
Client sends an
|
|
\fIExitMessage\fR
|
|
when the command exits or is killed.
|
|
.TP 5n
|
|
9.\&
|
|
Server sends the final
|
|
\fIcommit_point\fR
|
|
if one is pending.
|
|
.TP 5n
|
|
10.\&
|
|
Server closes the connection.
|
|
After receiving the final
|
|
\fIcommit_point\fR,
|
|
the client shuts down its side of the TLS connection if TLS
|
|
is in use, and closes the connection.
|
|
.TP 5n
|
|
11.\&
|
|
Server shuts down its side of the TLS connection if TLS is in use,
|
|
and closes the connection.
|
|
.PP
|
|
At any point, the server may send an
|
|
\fIerror\fR
|
|
or
|
|
\fIabort\fR
|
|
message to the client at which point the server will close the
|
|
connection.
|
|
If an
|
|
\fIabort\fR
|
|
message is received, the client should terminate the running command.
|
|
.SH "EVENT LOG VARIABLES"
|
|
\fIAcceptMessage\fR,
|
|
\fIAlertMessage\fR
|
|
and
|
|
\fIRejectMessage\fR
|
|
classes contain an array of
|
|
\fIInfoMessage\fR
|
|
that should contain information about the user who submitted the command
|
|
as well as information about the execution environment of the command
|
|
if it was accepted.
|
|
.PP
|
|
Some variables have a
|
|
\fIclient\fR,
|
|
\fIrun\fR,
|
|
or
|
|
\fIsubmit\fR
|
|
prefix.
|
|
These prefixes are used to eliminate ambiguity for variables that
|
|
could apply to the client program, the user submitting the command,
|
|
or the command being run.
|
|
Variables with a
|
|
\fIclient\fR
|
|
prefix pertain to the program performing the connection to the log
|
|
server, for example
|
|
\fBsudo\fR.
|
|
Variables with a
|
|
\fIrun\fR
|
|
prefix pertain to the command that the user requested be run.
|
|
Variables with a
|
|
\fIsubmit\fR
|
|
prefix pertain to the user submitting the request
|
|
(the user running \fBsudo\fR).
|
|
.PP
|
|
The following
|
|
\fIInfoMessage\fR
|
|
entries are required:
|
|
.TS
|
|
l l l.
|
|
.PP
|
|
\fBKey\fR \fBType\fR \fBDescription\fR
|
|
.PP
|
|
command string command that was submitted
|
|
.PP
|
|
runuser string name of user the command was run as
|
|
.PP
|
|
submithost string name of host the command was submitted on
|
|
.PP
|
|
submituser string name of user submitting the command
|
|
.TE
|
|
.PP
|
|
The following
|
|
\fIInfoMessage\fR
|
|
entries are recognized, but not required:
|
|
.TS
|
|
l l l.
|
|
.PP
|
|
\fBKey\fR \fBType\fR \fBDescription\fR
|
|
.PP
|
|
clientargv StringList client's original argument vector
|
|
.PP
|
|
clientpid int64 client's process ID
|
|
.PP
|
|
clientppid int64 client's parent process ID
|
|
.PP
|
|
clientsid int64 client's terminal session ID
|
|
.PP
|
|
columns int64 number of columns in the terminal
|
|
.PP
|
|
lines int64 number of lines in the terminal
|
|
.PP
|
|
runargv StringList argument vector of command to run
|
|
.PP
|
|
runchroot string root directory of command to run
|
|
.PP
|
|
runcwd string running command's working directory
|
|
.PP
|
|
runenv StringList the running command's environment
|
|
.PP
|
|
rungid int64 primary group-ID of the command
|
|
.PP
|
|
rungids NumberList supplementary group-IDs for the command
|
|
.PP
|
|
rungroup string primary group name of the command
|
|
.PP
|
|
rungroups StringList supplementary group names for the command
|
|
.PP
|
|
runuid int64 run user's user-ID
|
|
.PP
|
|
submitcwd string submit user's current working directory
|
|
.PP
|
|
submitenv StringList the submit user's environment
|
|
.PP
|
|
submitgid int64 submit user's primary group-ID
|
|
.PP
|
|
submitgids NumberList submit user's supplementary group-IDs
|
|
.PP
|
|
submitgroup string submitting user's primary group name
|
|
.PP
|
|
submitgroups StringList submit user's supplementary group names
|
|
.PP
|
|
submituid int64 submit user's user-ID
|
|
.PP
|
|
ttyname string the terminal the command was submitted from
|
|
.TE
|
|
.PP
|
|
The server must accept other variables not listed above but may
|
|
ignore them.
|
|
.SH "EXAMPLES"
|
|
The Protocol Buffers description of the log server protocol, using
|
|
\(lqproto3\(rq
|
|
syntax, is included in full below.
|
|
.nf
|
|
.sp
|
|
.RS 0n
|
|
syntax = "proto3";
|
|
|
|
/*
|
|
* Client message to the server. Messages on the wire are
|
|
* prefixed with a 32-bit size in network byte order.
|
|
*/
|
|
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;
|
|
}
|
|
}
|
|
|
|
/* Equivalent of POSIX struct timespec */
|
|
message TimeSpec {
|
|
int64 tv_sec = 1; /* seconds */
|
|
int32 tv_nsec = 2; /* nanoseconds */
|
|
}
|
|
|
|
/* I/O buffer with keystroke data */
|
|
message IoBuffer {
|
|
TimeSpec delay = 1; /* elapsed time since last record */
|
|
bytes data = 2; /* keystroke data */
|
|
}
|
|
|
|
/*
|
|
* Key/value pairs, like Privilege Manager struct info.
|
|
* The value may be a number, a string, or a list of strings.
|
|
*/
|
|
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;
|
|
}
|
|
}
|
|
|
|
/*
|
|
* Event log data for command accepted by the policy.
|
|
*/
|
|
message AcceptMessage {
|
|
TimeSpec submit_time = 1; /* when command was submitted */
|
|
repeated InfoMessage info_msgs = 2; /* key,value event log data */
|
|
bool expect_iobufs = 3; /* true if I/O logging enabled */
|
|
}
|
|
|
|
/*
|
|
* Event log data for command rejected by the policy.
|
|
*/
|
|
message RejectMessage {
|
|
TimeSpec submit_time = 1; /* when command was submitted */
|
|
string reason = 2; /* reason command was rejected */
|
|
repeated InfoMessage info_msgs = 3; /* key,value event log data */
|
|
}
|
|
|
|
/* Message sent by client when command exits. */
|
|
/* Might revisit runtime and use end_time instead */
|
|
message ExitMessage {
|
|
TimeSpec run_time = 1; /* total elapsed run time */
|
|
int32 exit_value = 2; /* 0-255 */
|
|
bool dumped_core = 3; /* true if command dumped core */
|
|
string signal = 4; /* signal name if killed by signal */
|
|
string error = 5; /* if killed due to other error */
|
|
}
|
|
|
|
/* Alert message, policy module-specific. */
|
|
message AlertMessage {
|
|
TimeSpec alert_time = 1; /* time alert message occurred */
|
|
string reason = 2; /* policy alert error string */
|
|
repeated InfoMessage info_msgs = 3; /* key,value event log data */
|
|
}
|
|
|
|
/* Used to restart an existing I/O log on the server. */
|
|
message RestartMessage {
|
|
string log_id = 1; /* ID of log being restarted */
|
|
TimeSpec resume_point = 2; /* resume point (elapsed time) */
|
|
}
|
|
|
|
/* Window size change event. */
|
|
message ChangeWindowSize {
|
|
TimeSpec delay = 1; /* elapsed time since last record */
|
|
int32 rows = 2; /* new number of rows */
|
|
int32 cols = 3; /* new number of columns */
|
|
}
|
|
|
|
/* Command suspend/resume event. */
|
|
message CommandSuspend {
|
|
TimeSpec delay = 1; /* elapsed time since last record */
|
|
string signal = 2; /* signal that caused suspend/resume */
|
|
}
|
|
|
|
/*
|
|
* Server messages to the client. Messages on the wire are
|
|
* prefixed with a 32-bit size in network byte order.
|
|
*/
|
|
message ServerMessage {
|
|
oneof type {
|
|
ServerHello hello = 1; /* server hello message */
|
|
TimeSpec commit_point = 2; /* cumulative time of records stored */
|
|
string log_id = 3; /* ID of server-side I/O log */
|
|
string error = 4; /* error message from server */
|
|
string abort = 5; /* abort message, kill command */
|
|
}
|
|
}
|
|
|
|
/* Hello message from server when client connects. */
|
|
message ServerHello {
|
|
string server_id = 1; /* free-form server description */
|
|
string redirect = 2; /* optional redirect if busy */
|
|
repeated string servers = 3; /* optional list of known servers */
|
|
}
|
|
.RE
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
sudo_logsrvd.conf(@mansectform@),
|
|
sudoers(@mansectform@),
|
|
sudo(8),
|
|
sudo_logsrvd(8)
|
|
.PP
|
|
\fIProtocol Buffers\fR,
|
|
https://developers.google.com/protocol-buffers/.
|
|
.SH "AUTHORS"
|
|
Many people have worked on
|
|
\fBsudo\fR
|
|
over the years; this version consists of code written primarily by:
|
|
.sp
|
|
.RS 6n
|
|
Todd C. Miller
|
|
.RE
|
|
.PP
|
|
See the CONTRIBUTORS.md file in the
|
|
\fBsudo\fR
|
|
distribution (https://www.sudo.ws/about/contributors/) for an
|
|
exhaustive list of people who have contributed to
|
|
\fBsudo\fR.
|
|
.SH "BUGS"
|
|
If you believe you have found a bug in
|
|
\fBsudo_logsrv.proto\fR,
|
|
you can either file a bug report in the sudo bug database,
|
|
https://bugzilla.sudo.ws/, or open an issue at
|
|
https://github.com/sudo-project/sudo/issues.
|
|
If you would prefer to use email, messages may be sent to the
|
|
sudo-workers mailing list,
|
|
https://www.sudo.ws/mailman/listinfo/sudo-workers (public)
|
|
or <sudo@sudo.ws> (private).
|
|
.PP
|
|
Please not report security vulnerabilities through public GitHub
|
|
issues, Bugzilla or mailing lists.
|
|
Instead, report them via email to <Todd.Miller@sudo.ws>.
|
|
You may encrypt your message with PGP if you would like, using
|
|
the key found at https://www.sudo.ws/dist/PGPKEYS.
|
|
.SH "SUPPORT"
|
|
Limited free support is available via the sudo-users mailing list,
|
|
see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
|
|
search the archives.
|
|
.SH "DISCLAIMER"
|
|
\fBsudo\fR
|
|
is provided
|
|
\(lqAS IS\(rq
|
|
and any express or implied warranties, including, but not limited
|
|
to, the implied warranties of merchantability and fitness for a
|
|
particular purpose are disclaimed.
|
|
See the LICENSE.md file distributed with
|
|
\fBsudo\fR
|
|
or https://www.sudo.ws/about/license/ for complete details.
|