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 de‐
10 scription 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 se‐
131 curity 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 bool subcommands = 4;
301 }
302 The ServerHello message consists of server information sent when the
304 client first connects. It contains the following members:
305 server_id
307 A free-form server description. Usually this includes the name
308 and version of the implementation running on the log server.
309 This member is always present.
310 redirect
312 A host and port separated by a colon (‘’): that the client should
313 connect to instead. The host may be a host name, an IPv4 ad‐
314 dress, or an IPv6 address in square brackets. This may be used
315 for server load balancing. The server will disconnect after
316 sending the ServerHello when it includes a redirect.
317 servers
319 A list of other known log servers. This can be used to implement
320 log server redundancy and allows the client to discover all other
321 log servers simply by connecting to one known server. This mem‐
322 ber may be omitted when there is only a single log server.
323 subcommands
325 If set, the server supports logging additional commands during a
326 session. The client may send an AcceptMessage or RejectMessage
327 when sudo is running in intercept mode. In this mode, commands
328 spawned from the initial command authorized by sudo are subject
329 to policy restrictions and/or are logged. If subcommands is
330 false, the client must not attempt to log additional commands.
331 TimeSpec commit_point
333 A periodic time stamp sent by the server to indicate when I/O log buffers
334 have been committed to storage. This message is not sent after every
335 IoBuffer but rather at a server-configurable interval. When the server
336 receives an ExitMessage, it will respond with a commit_point correspond‐
337 ing to the last received IoBuffer before closing the connection.
338 string log_id
340 The server-side ID of the I/O log being stored, sent in response to an
341 AcceptMessage where expect_iobufs is true.
342 string error
344 A fatal server-side error. The server will close the connection after
345 sending the error message.
346 string abort
348 An abort message from the server indicates that the client should kill
349 the command and terminate the session. It may be used to implement sim‐
350 ple server-side policy. The server will close the connection after send‐
351 ing the abort message.
352
354 The expected protocol flow is as follows:
355 1. Client connects to the first available server. If the client is
357 configured to use TLS, a TLS handshake will be attempted.
358 2. Client sends ClientHello. This is currently optional but allows the
360 server to detect a non-TLS connection on the TLS port.
361 3. Server sends ServerHello.
363 4. Client responds with either AcceptMessage, RejectMessage, or
365 RestartMessage.
366 5. If client sent a AcceptMessage with expect_iobufs set, server cre‐
368 ates a new I/O log and responds with a log_id.
369 6. Client sends zero or more IoBuffer messages.
371 7. Server periodically responds to IoBuffer messages with a
373 commit_point.
374 8. Client sends an ExitMessage when the command exits or is killed.
376 9. Server sends the final commit_point if one is pending.
378 10. Server closes the connection. After receiving the final
380 commit_point, the client shuts down its side of the TLS connection
381 if TLS is in use, and closes the connection.
382 11. Server shuts down its side of the TLS connection if TLS is in use,
384 and closes the connection.
385 At any point, the server may send an error or abort message to the client
387 at which point the server will close the connection. If an abort message
388 is received, the client should terminate the running command.
389
391 AcceptMessage, AlertMessage and RejectMessage classes contain an array of
392 InfoMessage that should contain information about the user who submitted
393 the command as well as information about the execution environment of the
394 command if it was accepted.
395 Some variables have a client, run, or submit prefix. These prefixes are
397 used to eliminate ambiguity for variables that could apply to the client
398 program, the user submitting the command, or the command being run.
399 Variables with a client prefix pertain to the program performing the con‐
400 nection to the log server, for example sudo. Variables with a run prefix
401 pertain to the command that the user requested be run. Variables with a
402 submit prefix pertain to the user submitting the request (the user
403 running sudo).
404 The following InfoMessage entries are required:
406 Key Type Description
408 command string command that was submitted
409 runuser string name of user the command was run as
410 submithost string name of host the command was submitted on
411 submituser string name of user submitting the command
412 The following InfoMessage entries are recognized, but not required:
414 Key Type Description
416 clientargv StringList client's original argument vector
417 clientpid int64 client's process ID
418 clientppid int64 client's parent process ID
419 clientsid int64 client's terminal session ID
420 columns int64 number of columns in the terminal
421 lines int64 number of lines in the terminal
422 runargv StringList argument vector of command to run
423 runchroot string root directory of command to run
424 runcwd string running command's working directory
425 runenv StringList the running command's environment
426 rungid int64 primary group-ID of the command
427 rungids NumberList supplementary group-IDs for the command
428 rungroup string primary group name of the command
429 rungroups StringList supplementary group names for the command
430 runuid int64 run user's user-ID
431 submitcwd string submit user's current working directory
432 submitenv StringList the submit user's environment
433 submitgid int64 submit user's primary group-ID
434 submitgids NumberList submit user's supplementary group-IDs
435 submitgroup string submitting user's primary group name
436 submitgroups StringList submit user's supplementary group names
437 submituid int64 submit user's user-ID
438 ttyname string the terminal the command was submitted from
439 The server must accept other variables not listed above but may ignore
441 them.
442
444 The Protocol Buffers description of the log server protocol, using
445 “proto3” syntax, is included in full below.
446 syntax = "proto3";
448 /*
450 * Client message to the server. Messages on the wire are
451 * prefixed with a 32-bit size in network byte order.
452 */
453 message ClientMessage {
454 oneof type {
455 AcceptMessage accept_msg = 1;
456 RejectMessage reject_msg = 2;
457 ExitMessage exit_msg = 3;
458 RestartMessage restart_msg = 4;
459 AlertMessage alert_msg = 5;
460 IoBuffer ttyin_buf = 6;
461 IoBuffer ttyout_buf = 7;
462 IoBuffer stdin_buf = 8;
463 IoBuffer stdout_buf = 9;
464 IoBuffer stderr_buf = 10;
465 ChangeWindowSize winsize_event = 11;
466 CommandSuspend suspend_event = 12;
467 }
468 }
469 /* Equivalent of POSIX struct timespec */
471 message TimeSpec {
472 int64 tv_sec = 1; /* seconds */
473 int32 tv_nsec = 2; /* nanoseconds */
474 }
475 /* I/O buffer with keystroke data */
477 message IoBuffer {
478 TimeSpec delay = 1; /* elapsed time since last record */
479 bytes data = 2; /* keystroke data */
480 }
481 /*
483 * Key/value pairs, like Privilege Manager struct info.
484 * The value may be a number, a string, or a list of strings.
485 */
486 message InfoMessage {
487 message StringList {
488 repeated string strings = 1;
489 }
490 message NumberList {
491 repeated int64 numbers = 1;
492 }
493 string key = 1;
494 oneof value {
495 int64 numval = 2;
496 string strval = 3;
497 StringList strlistval = 4;
498 NumberList numlistval = 5;
499 }
500 }
501 /*
503 * Event log data for command accepted by the policy.
504 */
505 message AcceptMessage {
506 TimeSpec submit_time = 1; /* when command was submitted */
507 repeated InfoMessage info_msgs = 2; /* key,value event log data */
508 bool expect_iobufs = 3; /* true if I/O logging enabled */
509 }
510 /*
512 * Event log data for command rejected by the policy.
513 */
514 message RejectMessage {
515 TimeSpec submit_time = 1; /* when command was submitted */
516 string reason = 2; /* reason command was rejected */
517 repeated InfoMessage info_msgs = 3; /* key,value event log data */
518 }
519 /* Message sent by client when command exits. */
521 /* Might revisit runtime and use end_time instead */
522 message ExitMessage {
523 TimeSpec run_time = 1; /* total elapsed run time */
524 int32 exit_value = 2; /* 0-255 */
525 bool dumped_core = 3; /* true if command dumped core */
526 string signal = 4; /* signal name if killed by signal */
527 string error = 5; /* if killed due to other error */
528 }
529 /* Alert message, policy module-specific. */
531 message AlertMessage {
532 TimeSpec alert_time = 1; /* time alert message occurred */
533 string reason = 2; /* policy alert error string */
534 repeated InfoMessage info_msgs = 3; /* key,value event log data */
535 }
536 /* Used to restart an existing I/O log on the server. */
538 message RestartMessage {
539 string log_id = 1; /* ID of log being restarted */
540 TimeSpec resume_point = 2; /* resume point (elapsed time) */
541 }
542 /* Window size change event. */
544 message ChangeWindowSize {
545 TimeSpec delay = 1; /* elapsed time since last record */
546 int32 rows = 2; /* new number of rows */
547 int32 cols = 3; /* new number of columns */
548 }
549 /* Command suspend/resume event. */
551 message CommandSuspend {
552 TimeSpec delay = 1; /* elapsed time since last record */
553 string signal = 2; /* signal that caused suspend/resume */
554 }
555 /*
557 * Server messages to the client. Messages on the wire are
558 * prefixed with a 32-bit size in network byte order.
559 */
560 message ServerMessage {
561 oneof type {
562 ServerHello hello = 1; /* server hello message */
563 TimeSpec commit_point = 2; /* cumulative time of records stored */
564 string log_id = 3; /* ID of server-side I/O log */
565 string error = 4; /* error message from server */
566 string abort = 5; /* abort message, kill command */
567 }
568 }
569 /* Hello message from server when client connects. */
571 message ServerHello {
572 string server_id = 1; /* free-form server description */
573 string redirect = 2; /* optional redirect if busy */
574 repeated string servers = 3; /* optional list of known servers */
575 }
576
578 sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_logsrvd(8)
579 Protocol Buffers, https://developers.google.com/protocol-buffers/.
581
583 Many people have worked on sudo over the years; this version consists of
584 code written primarily by:
585 Todd C. Miller
587 See the CONTRIBUTORS.md file in the sudo distribution
589 (https://www.sudo.ws/about/contributors/) for an exhaustive list of peo‐
590 ple who have contributed to sudo.
591
593 If you believe you have found a bug in sudo, you can submit a bug report
594 at https://bugzilla.sudo.ws/
595
597 Limited free support is available via the sudo-users mailing list, see
598 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
599 the archives.
600
602 sudo is provided “AS IS” and any express or implied warranties, includ‐
603 ing, but not limited to, the implied warranties of merchantability and
604 fitness for a particular purpose are disclaimed. See the LICENSE.md file
605 distributed with sudo or https://www.sudo.ws/about/license/ for complete
606 details.
607Sudo 1.9.12p2 September 13, 2022 Sudo 1.9.12p2