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 }
42 }
43 The different ClientMessage sub-messages the client may sent to the
45 server are described below.
46 TimeSpec
48 message TimeSpec {
49 int64 tv_sec = 1;
50 int32 tv_nsec = 2;
51 }
52 A TimeSpec is the equivalent of a POSIX struct timespec, containing sec‐
54 onds and nanoseconds members. The tv_sec member is a 64-bit integer to
55 support dates after the year 2038.
56 InfoMessage
58 message InfoMessage {
59 message StringList {
60 repeated string strings = 1;
61 }
62 message NumberList {
63 repeated int64 numbers = 1;
64 }
65 string key = 1;
66 oneof value {
67 int64 numval = 2;
68 string strval = 3;
69 StringList strlistval = 4;
70 NumberList numlistval = 5;
71 }
72 }
73 An InfoMessage is used to represent information about the invoking user
75 as well as the execution environment the command runs in the form of key-
76 value pairs. The key is always a string but the value may be a 64-bit
77 integer, a string, an array of strings or an array of 64-bit integers.
78 The event log data is composed of InfoMessage entries. See the EVENT LOG
79 VARIABLES section for more information.
80 AcceptMessage accept_msg
82 message AcceptMessage {
83 TimeSpec submit_time = 1;
84 repeated InfoMessage info_msgs = 2;
85 bool expect_iobufs = 3;
86 }
87 An AcceptMessage is sent by the client when a command is allowed by the
89 security policy. It contains the following members:
90 submit_time
92 The wall clock time when the command was submitted to the secu‐
93 rity policy.
94 info_msgs
96 An array of InfoMessage describing the user who submitted the
97 command as well as the execution environment of the command.
98 This information is used to generate an event log entry and may
99 also be used by server to determine where and how the I/O log is
100 stored. as choose the
101 expect_iobufs
103 Set to true if the server should expect IoBuffer messages to fol‐
104 low (for I/O logging) or false if the server should only store
105 the event log.
106 If an AcceptMessage is sent, the client must not send a RejectMessage or
108 RestartMessage.
109 RejectMessage reject_msg
111 message RejectMessage {
112 TimeSpec submit_time = 1;
113 string reason = 2;
114 repeated InfoMessage info_msgs = 3;
115 }
116 A RejectMessage is sent by the client when a command is denied by the
118 security policy. It contains the following members:
119 submit_time
121 The wall clock time when the command was submitted to the secu‐
122 rity policy.
123 reason The reason the security policy gave for denying the command.
125 info_msgs
127 An array of InfoMessage describing the user who submitted the
128 command as well as the execution environment of the command.
129 This information is used to generate an event log entry.
130 If a RejectMessage is sent, the client must not send an AcceptMessage or
132 RestartMessage.
133 ExitMessage exit_msg
135 message ExitMessage {
136 TimeSpec run_time = 1;
137 int32 exit_value = 2;
138 bool dumped_core = 3;
139 string signal = 4;
140 string error = 5;
141 }
142 An ExitMessage is sent by the client after the command has exited or has
144 been terminated by a signal. It contains the following members:
145 run_time
147 The total amount of elapsed time since the command started, cal‐
148 culated using a monotonic clock where possible. This is not the
149 wall clock time.
150 exit_value
152 The command's exit value in the range 0-255.
153 dumped_core
155 True if the command was terminated by a signal and dumped core.
156 signal If the command was terminated by a signal, this is set to the
158 name of the signal without the leading “SIG”. For example, INT,
159 TERM, KILL, SEGV.
160 error A message from the client indicating that the command was termi‐
162 nated unexpectedly due to an error.
163 When performing I/O logging, the client should wait for a commit_point
165 corresponding to the final IoBuffer before closing the connection unless
166 the final commit_point has already been received.
167 RestartMessage restart_msg
169 message RestartMessage {
170 string log_id = 1;
171 TimeSpec resume_point = 2;
172 }
173 A RestartMessage is sent by the client to resume sending an existing I/O
175 log that was previously interrupted. It contains the following members:
176 log_id The the server-side name for an I/O log that was previously sent
178 to the client by the server. This may be a path name on the
179 server or some other kind of server-side identifier.
180 resume_point
182 The point in time after which to resume the I/O log. This is in
183 the form of a TimeSpec representing the amount of time since the
184 command started, not the wall clock time. The resume_point
185 should correspond to a commit_point previously sent to the client
186 by the server. If the server receives a RestartMessage contain‐
187 ing a resume_point it has not previously seen, an error will be
188 returned to the client and the connection will be dropped.
189 If a RestartMessage is sent, the client must not send an AcceptMessage or
191 RejectMessage.
192 AlertMessage alert_msg
194 message AlertMessage {
195 TimeSpec alert_time = 1;
196 string reason = 2;
197 }
198 An AlertMessage is sent by the client to indicate a problem detected by
200 the security policy while the command is running that should be stored in
201 the event log. It contains the following members:
202 alert_time
204 The wall clock time when the alert occurred.
205 reason The reason for the alert.
207 IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf
209 message IoBuffer {
210 TimeSpec delay = 1;
211 bytes data = 2;
212 }
213 An IoBuffer is used to represent data from terminal input, terminal out‐
215 put, standard input, standard output or standard error. It contains the
216 following members:
217 delay The elapsed time since the last record in the form of a TimeSpec.
219 The delay should be calculated using a monotonic clock where pos‐
220 sible.
221 data The binary I/O log data from terminal input, terminal output,
223 standard input, standard output or standard error.
224 ChangeWindowSize winsize_event
226 message ChangeWindowSize {
227 TimeSpec delay = 1;
228 int32 rows = 2;
229 int32 cols = 3;
230 }
231 A ChangeWindowSize message is sent by the client when the terminal run‐
233 ning the command changes size. It contains the following members:
234 delay The elapsed time since the last record in the form of a TimeSpec.
236 The delay should be calculated using a monotonic clock where pos‐
237 sible.
238 rows The new number of terminal rows.
240 cols The new number of terminal columns.
242 CommandSuspend suspend_event
244 message CommandSuspend {
245 TimeSpec delay = 1;
246 string signal = 2;
247 }
248 A CommandSuspend message is sent by the client when the command is either
250 suspended or resumed. It contains the following members:
251 delay The elapsed time since the last record in the form of a TimeSpec.
253 The delay should be calculated using a monotonic clock where pos‐
254 sible.
255 signal The signal name without the leading “SIG”. For example, STOP,
257 TSTP, CONT.
258
260 A ServerMessage is a container used to encapsulate all the possible mes‐
261 sage types the server may send to a client.
262 message ServerMessage {
264 oneof type {
265 ServerHello hello = 1;
266 TimeSpec commit_point = 2;
267 string log_id = 3;
268 string error = 4;
269 string abort = 5;
270 }
271 }
272 The different ServerMessage sub-messages the server may sent to the
274 client are described below.
275 ServerHello hello
277 message ServerHello {
278 string server_id = 1;
279 string redirect = 2;
280 repeated string servers = 3;
281 }
282 The ServerHello message consists of server information sent when the
284 client first connects. It contains the following members:
285 server_id
287 A free-form server description. Usually this includes the name
288 and version of the implementation running on the log server.
289 This member is always present.
290 redirect
292 A host and port separated by a colon (‘’): that the client should
293 connect to instead. The host may be a host name, an IPv4
294 address, or an IPv6 address in square brackets. This may be used
295 for server load balancing. The server will disconnect after
296 sending the ServerHello when it includes a redirect.
297 servers
299 A list of other known log servers. This can be used to implement
300 log server redundancy and allows the client to discover all other
301 log servers simply by connecting to one known server. This mem‐
302 ber may be omitted when there is only a single log server.
303 TimeSpec commit_point
305 A periodic time stamp sent by the server to indicate when I/O log buffers
306 have been committed to storage. This message is not sent after every
307 IoBuffer but rather at a server-configurable interval. When the server
308 receives an ExitMessage, it will respond with a commit_point correspond‐
309 ing to the last received IoBuffer before closing the connection.
310 string log_id
312 The server-side ID of the I/O log being stored, sent in response to an
313 AcceptMessage where expect_iobufs is true.
314 string error
316 A fatal server-side error. The server will close the connection after
317 sending the error message.
318 string abort
320 An abort message from the server indicates that the client should kill
321 the command and terminate the session. It may be used to implement sim‐
322 ple server-side policy. The server will close the connection after send‐
323 ing the abort message.
324
326 The expected protocol flow is as follows:
327 1. Client connect to server.
329 2. Server sends ServerHello.
331 3. Client responds with either AcceptMessage, RejectMessage, or
333 RestartMessage.
334 4. If client sent a AcceptMessage with expect_iobufs set, server cre‐
336 ates a new I/O log and responds with a log_id.
337 5. Client sends zero or more IoBuffer messages.
339 6. Server periodically responds to IoBuffer messages with a
341 commit_point.
342 7. Client sends an ExitMessage when the command exits or is killed.
344 8. Server sends the final commit_point if one is pending.
346 9. Server closes the connection.
348 At any point, the server may send an error or abort message to the client
350 at which point the server will close the connection. If an abort message
351 is received, the client should terminate the running command.
352
354 AcceptMessage and RejectMessage classes contain an array of InfoMessage
355 that should contain information about the user who submitted the command
356 as well as information about the execution environment of the command if
357 it was accepted.
358 Some variables have a client, run, or submit prefix. These prefixes are
360 used to eliminate ambiguity for variables that could apply to the client
361 program, the user submitting the command, or the command being run.
362 Variables with a client prefix pertain to the program performing the con‐
363 nection to the log server, for example sudo. Variables with a run prefix
364 pertain to the command that the user requested be run. Variables with a
365 submit prefix pertain to the user submitting the request (the user
366 running sudo).
367 The following InfoMessage entries are required:
369 Key Type Description
371 command string command that was submitted
372 runuser string name of user the command was run as
373 submithost string name of host the command was submitted on
374 submituser string name of user submitting the command
375 The following InfoMessage entries are recognized, but not required:
377 Key Type Description
379 clientargv StringList client's original argument vector
380 clientpid int64 client's process ID
381 clientppid int64 client's parent process ID
382 clientsid int64 client's terminal session ID
383 columns int64 number of columns in the terminal
384 lines int64 number of lines in the terminal
385 runargv StringList argument vector of command to run
386 runchroot string root directory of command to run
387 runcwd string running command's working directory
388 runenv StringList the running command's environment
389 rungid int64 primary group-ID of the command
390 rungids NumberList supplementary group-IDs for the command
391 rungroup string primary group name of the command
392 rungroups StringList supplementary group names for the command
393 runuid int64 run user's user-ID
394 submitcwd string submit user's current working directory
395 submitenv StringList the submit user's environment
396 submitgid int64 submit user's primary group-ID
397 submitgids NumberList submit user's supplementary group-IDs
398 submitgroup string submitting user's primary group name
399 submitgroups StringList submit user's supplementary group names
400 submituid int64 submit user's user-ID
401 ttyname string the terminal the command was submitted from
402 The server must accept other variables not listed above but may ignore
404 them.
405
407 The Protocol Buffers description of the log server protocol is included
408 in full below. Note that this uses the newer “proto3” syntax.
409 syntax = "proto3";
411 /*
413 * Client message to the server. Messages on the wire are
414 * prefixed with a 32-bit size in network byte order.
415 */
416 message ClientMessage {
417 oneof type {
418 AcceptMessage accept_msg = 1;
419 RejectMessage reject_msg = 2;
420 ExitMessage exit_msg = 3;
421 RestartMessage restart_msg = 4;
422 AlertMessage alert_msg = 5;
423 IoBuffer ttyin_buf = 6;
424 IoBuffer ttyout_buf = 7;
425 IoBuffer stdin_buf = 8;
426 IoBuffer stdout_buf = 9;
427 IoBuffer stderr_buf = 10;
428 ChangeWindowSize winsize_event = 11;
429 CommandSuspend suspend_event = 12;
430 }
431 }
432 /* Equivalent of POSIX struct timespec */
434 message TimeSpec {
435 int64 tv_sec = 1; /* seconds */
436 int32 tv_nsec = 2; /* nanoseconds */
437 }
438 /* I/O buffer with keystroke data */
440 message IoBuffer {
441 TimeSpec delay = 1; /* elapsed time since last record */
442 bytes data = 2; /* keystroke data */
443 }
444 /*
446 * Key/value pairs, like Privilege Manager struct info.
447 * The value may be a number, a string, or a list of strings.
448 */
449 message InfoMessage {
450 message StringList {
451 repeated string strings = 1;
452 }
453 message NumberList {
454 repeated int64 numbers = 1;
455 }
456 string key = 1;
457 oneof value {
458 int64 numval = 2;
459 string strval = 3;
460 StringList strlistval = 4;
461 NumberList numlistval = 5;
462 }
463 }
464 /*
466 * Event log data for command accepted by the policy.
467 */
468 message AcceptMessage {
469 TimeSpec submit_time = 1; /* when command was submitted */
470 repeated InfoMessage info_msgs = 2; /* key,value event log data */
471 bool expect_iobufs = 3; /* true if I/O logging enabled */
472 }
473 /*
475 * Event log data for command rejected by the policy.
476 */
477 message RejectMessage {
478 TimeSpec submit_time = 1; /* when command was submitted */
479 string reason = 2; /* reason command was rejected */
480 repeated InfoMessage info_msgs = 3; /* key,value event log data */
481 }
482 /* Message sent by client when command exits. */
484 /* Might revisit runtime and use end_time instead */
485 message ExitMessage {
486 TimeSpec run_time = 1; /* total elapsed run time */
487 int32 exit_value = 2; /* 0-255 */
488 bool dumped_core = 3; /* true if command dumped core */
489 string signal = 4; /* signal name if killed by signal */
490 string error = 5; /* if killed due to other error */
491 }
492 /* Alert message, policy module-specific. */
494 message AlertMessage {
495 TimeSpec alert_time = 1; /* time alert message occurred */
496 string reason = 2; /* description of policy violation */
497 }
498 /* Used to restart an existing I/O log on the server. */
500 message RestartMessage {
501 string log_id = 1; /* ID of log being restarted */
502 TimeSpec resume_point = 2; /* resume point (elapsed time) */
503 }
504 /* Window size change event. */
506 message ChangeWindowSize {
507 TimeSpec delay = 1; /* elapsed time since last record */
508 int32 rows = 2; /* new number of rows */
509 int32 cols = 3; /* new number of columns */
510 }
511 /* Command suspend/resume event. */
513 message CommandSuspend {
514 TimeSpec delay = 1; /* elapsed time since last record */
515 string signal = 2; /* signal that caused suspend/resume */
516 }
517 /*
519 * Server messages to the client. Messages on the wire are
520 * prefixed with a 32-bit size in network byte order.
521 */
522 message ServerMessage {
523 oneof type {
524 ServerHello hello = 1; /* server hello message */
525 TimeSpec commit_point = 2; /* cumulative time of records stored */
526 string log_id = 3; /* ID of server-side I/O log */
527 string error = 4; /* error message from server */
528 string abort = 5; /* abort message, kill command */
529 }
530 }
531 /* Hello message from server when client connects. */
533 message ServerHello {
534 string server_id = 1; /* free-form server description */
535 string redirect = 2; /* optional redirect if busy */
536 repeated string servers = 3; /* optional list of known servers */
537 }
538
540 sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_logsrvd(8)
541 Protocol Buffers, https://developers.google.com/protocol-buffers/.
543
545 See the HISTORY file in the sudo distribution (https://www.sudo.ws/his‐
546 tory.html) for a brief history of sudo.
547
549 Many people have worked on sudo over the years; this version consists of
550 code written primarily by:
551 Todd C. Miller
553 See the CONTRIBUTORS file in the sudo distribution
555 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
556 who have contributed to sudo.
557
559 If you feel you have found a bug in sudo, please submit a bug report at
560 https://bugzilla.sudo.ws/
561
563 Limited free support is available via the sudo-users mailing list, see
564 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
565 the archives.
566
568 sudo is provided “AS IS” and any express or implied warranties, includ‐
569 ing, but not limited to, the implied warranties of merchantability and
570 fitness for a particular purpose are disclaimed. See the LICENSE file
571 distributed with sudo or https://www.sudo.ws/license.html for complete
572 details.
573Sudo 1.9.0b4 October 6, 2019 Sudo 1.9.0b4