1SUDO_LOGSRV.PROTO(5) BSD File Formats Manual SUDO_LOGSRV.PROTO(5)
2
4 sudo_logsrv.proto — Sudo log server protocol
5
7 Starting with version 1.9.0, sudo supports sending event and I/O logs to
8 a log server. The protocol used is written in Google's Protocol Buffers
9 domain specific language. The EXAMPLES section includes a complete
10 description of the protocol in Protocol Buffers format.
11 Because there is no way to determine message boundaries when using Proto‐
13 col Buffers, the wire size of each message is sent immediately preceding
14 the message itself as a 32-bit unsigned integer in network byte order.
15 This is referred to as “length-prefix framing” and is how Google suggests
16 handling the lack of message delimiters.
17 The protocol is made up of two basic messages, ClientMessage and
19 ServerMessage, described below. The server must accept messages up to
20 two megabytes in size. The server may return an error if the client
21 tries to send a message larger than two megabytes.
22
24 A ClientMessage is a container used to encapsulate all the possible mes‐
25 sage types a client may send to the server.
26 message ClientMessage {
28 oneof type {
29 AcceptMessage accept_msg = 1;
30 RejectMessage reject_msg = 2;
31 ExitMessage exit_msg = 3;
32 RestartMessage restart_msg = 4;
33 AlertMessage alert_msg = 5;
34 IoBuffer ttyin_buf = 6;
35 IoBuffer ttyout_buf = 7;
36 IoBuffer stdin_buf = 8;
37 IoBuffer stdout_buf = 9;
38 IoBuffer stderr_buf = 10;
39 ChangeWindowSize winsize_event = 11;
40 CommandSuspend suspend_event = 12;
41 ClientHello hello_msg = 13;
42 }
43 }
44 The different ClientMessage sub-messages the client may sent to the
46 server are described below.
47 TimeSpec
49 message TimeSpec {
50 int64 tv_sec = 1;
51 int32 tv_nsec = 2;
52 }
53 A TimeSpec is the equivalent of a POSIX struct timespec, containing sec‐
55 onds and nanoseconds members. The tv_sec member is a 64-bit integer to
56 support dates after the year 2038.
57 InfoMessage
59 message InfoMessage {
60 message StringList {
61 repeated string strings = 1;
62 }
63 message NumberList {
64 repeated int64 numbers = 1;
65 }
66 string key = 1;
67 oneof value {
68 int64 numval = 2;
69 string strval = 3;
70 StringList strlistval = 4;
71 NumberList numlistval = 5;
72 }
73 }
74 An InfoMessage is used to represent information about the invoking user
76 as well as the execution environment the command runs in the form of key-
77 value pairs. The key is always a string but the value may be a 64-bit
78 integer, a string, an array of strings or an array of 64-bit integers.
79 The event log data is composed of InfoMessage entries. See the EVENT LOG
80 VARIABLES section for more information.
81 ClientHello hello_msg
83 message ClientHello {
84 string client_id = 1;
85 }
86 A ClientHello message consists of client information that may be sent to
88 the server when the client first connects.
89 client_id
91 A free-form client description. This usually includes the name
92 and version of the client implementation.
93 AcceptMessage accept_msg
95 message AcceptMessage {
96 TimeSpec submit_time = 1;
97 repeated InfoMessage info_msgs = 2;
98 bool expect_iobufs = 3;
99 }
100 An AcceptMessage is sent by the client when a command is allowed by the
102 security policy. It contains the following members:
103 submit_time
105 The wall clock time when the command was submitted to the secu‐
106 rity policy.
107 info_msgs
109 An array of InfoMessage describing the user who submitted the
110 command as well as the execution environment of the command.
111 This information is used to generate an event log entry and may
112 also be used by server to determine where and how the I/O log is
113 stored.
114 expect_iobufs
116 Set to true if the server should expect IoBuffer messages to fol‐
117 low (for I/O logging) or false if the server should only store
118 the event log.
119 If an AcceptMessage is sent, the client must not send a RejectMessage or
121 RestartMessage.
122 RejectMessage reject_msg
124 message RejectMessage {
125 TimeSpec submit_time = 1;
126 string reason = 2;
127 repeated InfoMessage info_msgs = 3;
128 }
129 A RejectMessage is sent by the client when a command is denied by the
131 security policy. It contains the following members:
132 submit_time
134 The wall clock time when the command was submitted to the secu‐
135 rity policy.
136 reason The reason the security policy gave for denying the command.
138 info_msgs
140 An array of InfoMessage describing the user who submitted the
141 command as well as the execution environment of the command.
142 This information is used to generate an event log entry.
143 If a RejectMessage is sent, the client must not send an AcceptMessage or
145 RestartMessage.
146 ExitMessage exit_msg
148 message ExitMessage {
149 TimeSpec run_time = 1;
150 int32 exit_value = 2;
151 bool dumped_core = 3;
152 string signal = 4;
153 string error = 5;
154 }
155 An ExitMessage is sent by the client after the command has exited or has
157 been terminated by a signal. It contains the following members:
158 run_time
160 The total amount of elapsed time since the command started, cal‐
161 culated using a monotonic clock where possible. This is not the
162 wall clock time.
163 exit_value
165 The command's exit value in the range 0-255.
166 dumped_core
168 True if the command was terminated by a signal and dumped core.
169 signal If the command was terminated by a signal, this is set to the
171 name of the signal without the leading “SIG”. For example, INT,
172 TERM, KILL, SEGV.
173 error A message from the client indicating that the command was termi‐
175 nated unexpectedly due to an error.
176 When performing I/O logging, the client should wait for a commit_point
178 corresponding to the final IoBuffer before closing the connection unless
179 the final commit_point has already been received.
180 RestartMessage restart_msg
182 message RestartMessage {
183 string log_id = 1;
184 TimeSpec resume_point = 2;
185 }
186 A RestartMessage is sent by the client to resume sending an existing I/O
188 log that was previously interrupted. It contains the following members:
189 log_id The the server-side name for an I/O log that was previously sent
191 to the client by the server. This may be a path name on the
192 server or some other kind of server-side identifier.
193 resume_point
195 The point in time after which to resume the I/O log. This is in
196 the form of a TimeSpec representing the amount of time since the
197 command started, not the wall clock time. The resume_point
198 should correspond to a commit_point previously sent to the client
199 by the server. If the server receives a RestartMessage contain‐
200 ing a resume_point it has not previously seen, an error will be
201 returned to the client and the connection will be dropped.
202 If a RestartMessage is sent, the client must not send an AcceptMessage or
204 RejectMessage.
205 AlertMessage alert_msg
207 message AlertMessage {
208 TimeSpec alert_time = 1;
209 string reason = 2;
210 repeated InfoMessage info_msgs = 3;
211 }
212 An AlertMessage is sent by the client to indicate a problem detected by
214 the security policy while the command is running that should be stored in
215 the event log. It contains the following members:
216 alert_time
218 The wall clock time when the alert occurred.
219 reason The reason for the alert.
221 info_msgs
223 An optional array of InfoMessage describing the user who submit‐
224 ted the command as well as the execution environment of the com‐
225 mand. This information is used to generate an event log entry.
226 IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf
228 message IoBuffer {
229 TimeSpec delay = 1;
230 bytes data = 2;
231 }
232 An IoBuffer is used to represent data from terminal input, terminal out‐
234 put, standard input, standard output or standard error. It contains the
235 following members:
236 delay The elapsed time since the last record in the form of a TimeSpec.
238 The delay should be calculated using a monotonic clock where pos‐
239 sible.
240 data The binary I/O log data from terminal input, terminal output,
242 standard input, standard output or standard error.
243 ChangeWindowSize winsize_event
245 message ChangeWindowSize {
246 TimeSpec delay = 1;
247 int32 rows = 2;
248 int32 cols = 3;
249 }
250 A ChangeWindowSize message is sent by the client when the terminal run‐
252 ning the command changes size. It contains the following members:
253 delay The elapsed time since the last record in the form of a TimeSpec.
255 The delay should be calculated using a monotonic clock where pos‐
256 sible.
257 rows The new number of terminal rows.
259 cols The new number of terminal columns.
261 CommandSuspend suspend_event
263 message CommandSuspend {
264 TimeSpec delay = 1;
265 string signal = 2;
266 }
267 A CommandSuspend message is sent by the client when the command is either
269 suspended or resumed. It contains the following members:
270 delay The elapsed time since the last record in the form of a TimeSpec.
272 The delay should be calculated using a monotonic clock where pos‐
273 sible.
274 signal The signal name without the leading “SIG”. For example, STOP,
276 TSTP, CONT.
277
279 A ServerMessage is a container used to encapsulate all the possible mes‐
280 sage types the server may send to a client.
281 message ServerMessage {
283 oneof type {
284 ServerHello hello = 1;
285 TimeSpec commit_point = 2;
286 string log_id = 3;
287 string error = 4;
288 string abort = 5;
289 }
290 }
291 The different ServerMessage sub-messages the server may sent to the
293 client are described below.
294 ServerHello hello
296 message ServerHello {
297 string server_id = 1;
298 string redirect = 2;
299 repeated string servers = 3;
300 }
301 The ServerHello message consists of server information sent when the
303 client first connects. It contains the following members:
304 server_id
306 A free-form server description. Usually this includes the name
307 and version of the implementation running on the log server.
308 This member is always present.
309 redirect
311 A host and port separated by a colon (‘’): that the client should
312 connect to instead. The host may be a host name, an IPv4
313 address, or an IPv6 address in square brackets. This may be used
314 for server load balancing. The server will disconnect after
315 sending the ServerHello when it includes a redirect.
316 servers
318 A list of other known log servers. This can be used to implement
319 log server redundancy and allows the client to discover all other
320 log servers simply by connecting to one known server. This mem‐
321 ber may be omitted when there is only a single log server.
322 TimeSpec commit_point
324 A periodic time stamp sent by the server to indicate when I/O log buffers
325 have been committed to storage. This message is not sent after every
326 IoBuffer but rather at a server-configurable interval. When the server
327 receives an ExitMessage, it will respond with a commit_point correspond‐
328 ing to the last received IoBuffer before closing the connection.
329 string log_id
331 The server-side ID of the I/O log being stored, sent in response to an
332 AcceptMessage where expect_iobufs is true.
333 string error
335 A fatal server-side error. The server will close the connection after
336 sending the error message.
337 string abort
339 An abort message from the server indicates that the client should kill
340 the command and terminate the session. It may be used to implement sim‐
341 ple server-side policy. The server will close the connection after send‐
342 ing the abort message.
343
345 The expected protocol flow is as follows:
346 1. Client connects to the first available server. If the client is
348 configured to use TLS, a TLS handshake will be attempted.
349 2. Client sends ClientHello. This is currently optional but allows the
351 server to detect a non-TLS connection on the TLS port.
352 3. Server sends ServerHello.
354 4. Client responds with either AcceptMessage, RejectMessage, or
356 RestartMessage.
357 5. If client sent a AcceptMessage with expect_iobufs set, server cre‐
359 ates a new I/O log and responds with a log_id.
360 6. Client sends zero or more IoBuffer messages.
362 7. Server periodically responds to IoBuffer messages with a
364 commit_point.
365 8. Client sends an ExitMessage when the command exits or is killed.
367 9. Server sends the final commit_point if one is pending.
369 10. Server closes the connection. After receiving the final
371 commit_point, the client shuts down its side of the TLS connection
372 if TLS is in use, and closes the connection.
373 11. Server shuts down its side of the TLS connection if TLS is in use,
375 and closes the connection.
376 At any point, the server may send an error or abort message to the client
378 at which point the server will close the connection. If an abort message
379 is received, the client should terminate the running command.
380
382 AcceptMessage, AlertMessage and RejectMessage classes contain an array of
383 InfoMessage that should contain information about the user who submitted
384 the command as well as information about the execution environment of the
385 command if it was accepted.
386 Some variables have a client, run, or submit prefix. These prefixes are
388 used to eliminate ambiguity for variables that could apply to the client
389 program, the user submitting the command, or the command being run.
390 Variables with a client prefix pertain to the program performing the con‐
391 nection to the log server, for example sudo. Variables with a run prefix
392 pertain to the command that the user requested be run. Variables with a
393 submit prefix pertain to the user submitting the request (the user
394 running sudo).
395 The following InfoMessage entries are required:
397 Key Type Description
399 command string command that was submitted
400 runuser string name of user the command was run as
401 submithost string name of host the command was submitted on
402 submituser string name of user submitting the command
403 The following InfoMessage entries are recognized, but not required:
405 Key Type Description
407 clientargv StringList client's original argument vector
408 clientpid int64 client's process ID
409 clientppid int64 client's parent process ID
410 clientsid int64 client's terminal session ID
411 columns int64 number of columns in the terminal
412 lines int64 number of lines in the terminal
413 runargv StringList argument vector of command to run
414 runchroot string root directory of command to run
415 runcwd string running command's working directory
416 runenv StringList the running command's environment
417 rungid int64 primary group-ID of the command
418 rungids NumberList supplementary group-IDs for the command
419 rungroup string primary group name of the command
420 rungroups StringList supplementary group names for the command
421 runuid int64 run user's user-ID
422 submitcwd string submit user's current working directory
423 submitenv StringList the submit user's environment
424 submitgid int64 submit user's primary group-ID
425 submitgids NumberList submit user's supplementary group-IDs
426 submitgroup string submitting user's primary group name
427 submitgroups StringList submit user's supplementary group names
428 submituid int64 submit user's user-ID
429 ttyname string the terminal the command was submitted from
430 The server must accept other variables not listed above but may ignore
432 them.
433
435 The Protocol Buffers description of the log server protocol is included
436 in full below. Note that this uses the newer “proto3” syntax.
437 syntax = "proto3";
439 /*
441 * Client message to the server. Messages on the wire are
442 * prefixed with a 32-bit size in network byte order.
443 */
444 message ClientMessage {
445 oneof type {
446 AcceptMessage accept_msg = 1;
447 RejectMessage reject_msg = 2;
448 ExitMessage exit_msg = 3;
449 RestartMessage restart_msg = 4;
450 AlertMessage alert_msg = 5;
451 IoBuffer ttyin_buf = 6;
452 IoBuffer ttyout_buf = 7;
453 IoBuffer stdin_buf = 8;
454 IoBuffer stdout_buf = 9;
455 IoBuffer stderr_buf = 10;
456 ChangeWindowSize winsize_event = 11;
457 CommandSuspend suspend_event = 12;
458 }
459 }
460 /* Equivalent of POSIX struct timespec */
462 message TimeSpec {
463 int64 tv_sec = 1; /* seconds */
464 int32 tv_nsec = 2; /* nanoseconds */
465 }
466 /* I/O buffer with keystroke data */
468 message IoBuffer {
469 TimeSpec delay = 1; /* elapsed time since last record */
470 bytes data = 2; /* keystroke data */
471 }
472 /*
474 * Key/value pairs, like Privilege Manager struct info.
475 * The value may be a number, a string, or a list of strings.
476 */
477 message InfoMessage {
478 message StringList {
479 repeated string strings = 1;
480 }
481 message NumberList {
482 repeated int64 numbers = 1;
483 }
484 string key = 1;
485 oneof value {
486 int64 numval = 2;
487 string strval = 3;
488 StringList strlistval = 4;
489 NumberList numlistval = 5;
490 }
491 }
492 /*
494 * Event log data for command accepted by the policy.
495 */
496 message AcceptMessage {
497 TimeSpec submit_time = 1; /* when command was submitted */
498 repeated InfoMessage info_msgs = 2; /* key,value event log data */
499 bool expect_iobufs = 3; /* true if I/O logging enabled */
500 }
501 /*
503 * Event log data for command rejected by the policy.
504 */
505 message RejectMessage {
506 TimeSpec submit_time = 1; /* when command was submitted */
507 string reason = 2; /* reason command was rejected */
508 repeated InfoMessage info_msgs = 3; /* key,value event log data */
509 }
510 /* Message sent by client when command exits. */
512 /* Might revisit runtime and use end_time instead */
513 message ExitMessage {
514 TimeSpec run_time = 1; /* total elapsed run time */
515 int32 exit_value = 2; /* 0-255 */
516 bool dumped_core = 3; /* true if command dumped core */
517 string signal = 4; /* signal name if killed by signal */
518 string error = 5; /* if killed due to other error */
519 }
520 /* Alert message, policy module-specific. */
522 message AlertMessage {
523 TimeSpec alert_time = 1; /* time alert message occurred */
524 string reason = 2; /* policy alert error string */
525 repeated InfoMessage info_msgs = 3; /* key,value event log data */
526 }
527 /* Used to restart an existing I/O log on the server. */
529 message RestartMessage {
530 string log_id = 1; /* ID of log being restarted */
531 TimeSpec resume_point = 2; /* resume point (elapsed time) */
532 }
533 /* Window size change event. */
535 message ChangeWindowSize {
536 TimeSpec delay = 1; /* elapsed time since last record */
537 int32 rows = 2; /* new number of rows */
538 int32 cols = 3; /* new number of columns */
539 }
540 /* Command suspend/resume event. */
542 message CommandSuspend {
543 TimeSpec delay = 1; /* elapsed time since last record */
544 string signal = 2; /* signal that caused suspend/resume */
545 }
546 /*
548 * Server messages to the client. Messages on the wire are
549 * prefixed with a 32-bit size in network byte order.
550 */
551 message ServerMessage {
552 oneof type {
553 ServerHello hello = 1; /* server hello message */
554 TimeSpec commit_point = 2; /* cumulative time of records stored */
555 string log_id = 3; /* ID of server-side I/O log */
556 string error = 4; /* error message from server */
557 string abort = 5; /* abort message, kill command */
558 }
559 }
560 /* Hello message from server when client connects. */
562 message ServerHello {
563 string server_id = 1; /* free-form server description */
564 string redirect = 2; /* optional redirect if busy */
565 repeated string servers = 3; /* optional list of known servers */
566 }
567
569 sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_logsrvd(8)
570 Protocol Buffers, https://developers.google.com/protocol-buffers/.
572
574 See the HISTORY file in the sudo distribution (https://www.sudo.ws/his‐
575 tory.html) for a brief history of sudo.
576
578 Many people have worked on sudo over the years; this version consists of
579 code written primarily by:
580 Todd C. Miller
582 See the CONTRIBUTORS file in the sudo distribution
584 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
585 who have contributed to sudo.
586
588 If you feel you have found a bug in sudo, please submit a bug report at
589 https://bugzilla.sudo.ws/
590
592 Limited free support is available via the sudo-users mailing list, see
593 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
594 the archives.
595
597 sudo is provided “AS IS” and any express or implied warranties, includ‐
598 ing, but not limited to, the implied warranties of merchantability and
599 fitness for a particular purpose are disclaimed. See the LICENSE file
600 distributed with sudo or https://www.sudo.ws/license.html for complete
601 details.
602Sudo 1.9.5p2 November 6, 2020 Sudo 1.9.5p2