1SUDO_LOGSRV.PROTO(5)        BSD File Formats Manual       SUDO_LOGSRV.PROTO(5)
2

NAME

4     sudo_logsrv.proto — Sudo log server protocol
5

DESCRIPTION

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
12     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
18     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

Client Messages

24     A ClientMessage is a container used to encapsulate all the possible mes‐
25     sage types a client may send to the server.
26
27     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
45     The different ClientMessage sub-messages the client may sent to the
46     server are described below.
47
48   TimeSpec
49     message TimeSpec {
50         int64 tv_sec = 1;
51         int32 tv_nsec = 2;
52     }
53
54     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
58   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
75     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
82   ClientHello hello_msg
83     message ClientHello {
84       string client_id = 1;
85     }
86
87     A ClientHello message consists of client information that may be sent to
88     the server when the client first connects.
89
90     client_id
91             A free-form client description.  This usually includes the name
92             and version of the client implementation.
93
94   AcceptMessage accept_msg
95     message AcceptMessage {
96       TimeSpec submit_time = 1;
97       repeated InfoMessage info_msgs = 2;
98       bool expect_iobufs = 3;
99     }
100
101     An AcceptMessage is sent by the client when a command is allowed by the
102     security policy.  It contains the following members:
103
104     submit_time
105             The wall clock time when the command was submitted to the secu‐
106             rity policy.
107
108     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
115     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
120     If an AcceptMessage is sent, the client must not send a RejectMessage or
121     RestartMessage.
122
123   RejectMessage reject_msg
124     message RejectMessage {
125       TimeSpec submit_time = 1;
126       string reason = 2;
127       repeated InfoMessage info_msgs = 3;
128     }
129
130     A RejectMessage is sent by the client when a command is denied by the se‐
131     curity policy.  It contains the following members:
132
133     submit_time
134             The wall clock time when the command was submitted to the secu‐
135             rity policy.
136
137     reason  The reason the security policy gave for denying the command.
138
139     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
144     If a RejectMessage is sent, the client must not send an AcceptMessage or
145     RestartMessage.
146
147   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
156     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
159     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
164     exit_value
165             The command's exit value in the range 0-255.
166
167     dumped_core
168             True if the command was terminated by a signal and dumped core.
169
170     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
174     error   A message from the client indicating that the command was termi‐
175             nated unexpectedly due to an error.
176
177     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
181   RestartMessage restart_msg
182     message RestartMessage {
183       string log_id = 1;
184       TimeSpec resume_point = 2;
185     }
186
187     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
190     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
194     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
203     If a RestartMessage is sent, the client must not send an AcceptMessage or
204     RejectMessage.
205
206   AlertMessage alert_msg
207     message AlertMessage {
208       TimeSpec alert_time = 1;
209       string reason = 2;
210       repeated InfoMessage info_msgs = 3;
211     }
212
213     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
217     alert_time
218             The wall clock time when the alert occurred.
219
220     reason  The reason for the alert.
221
222     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
227   IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf
228     message IoBuffer {
229       TimeSpec delay = 1;
230       bytes data = 2;
231     }
232
233     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
237     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
241     data    The binary I/O log data from terminal input, terminal output,
242             standard input, standard output, or standard error.
243
244   ChangeWindowSize winsize_event
245     message ChangeWindowSize {
246       TimeSpec delay = 1;
247       int32 rows = 2;
248       int32 cols = 3;
249     }
250
251     A ChangeWindowSize message is sent by the client when the terminal run‐
252     ning the command changes size.  It contains the following members:
253
254     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
258     rows    The new number of terminal rows.
259
260     cols    The new number of terminal columns.
261
262   CommandSuspend suspend_event
263     message CommandSuspend {
264       TimeSpec delay = 1;
265       string signal = 2;
266     }
267
268     A CommandSuspend message is sent by the client when the command is either
269     suspended or resumed.  It contains the following members:
270
271     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
275     signal  The signal name without the leading “SIG”.  For example, STOP,
276             TSTP, CONT.
277

Server Messages

279     A ServerMessage is a container used to encapsulate all the possible mes‐
280     sage types the server may send to a client.
281
282     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
292     The different ServerMessage sub-messages the server may sent to the
293     client are described below.
294
295   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
303     The ServerHello message consists of server information sent when the
304     client first connects.  It contains the following members:
305
306     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
311     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
318     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
324     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
332   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
339   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
343   string error
344     A fatal server-side error.  The server will close the connection after
345     sending the error message.
346
347   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

Protocol flow of control

354     The expected protocol flow is as follows:
355
356     1.   Client connects to the first available server.  If the client is
357          configured to use TLS, a TLS handshake will be attempted.
358
359     2.   Client sends ClientHello.  This is currently optional but allows the
360          server to detect a non-TLS connection on the TLS port.
361
362     3.   Server sends ServerHello.
363
364     4.   Client responds with either AcceptMessage, RejectMessage, or
365          RestartMessage.
366
367     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
370     6.   Client sends zero or more IoBuffer messages.
371
372     7.   Server periodically responds to IoBuffer messages with a
373          commit_point.
374
375     8.   Client sends an ExitMessage when the command exits or is killed.
376
377     9.   Server sends the final commit_point if one is pending.
378
379     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
383     11.  Server shuts down its side of the TLS connection if TLS is in use,
384          and closes the connection.
385
386     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

EVENT LOG VARIABLES

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
396     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
405     The following InfoMessage entries are required:
406
407     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
413     The following InfoMessage entries are recognized, but not required:
414
415     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
440     The server must accept other variables not listed above but may ignore
441     them.
442

EXAMPLES

444     The Protocol Buffers description of the log server protocol, using
445     “proto3” syntax, is included in full below.
446
447     syntax = "proto3";
448
449     /*
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
470     /* Equivalent of POSIX struct timespec */
471     message TimeSpec {
472         int64 tv_sec = 1;           /* seconds */
473         int32 tv_nsec = 2;          /* nanoseconds */
474     }
475
476     /* 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
482     /*
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
502     /*
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
511     /*
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
520     /* 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
530     /* 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
537     /* 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
543     /* 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
550     /* 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
556     /*
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
570     /* 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

SEE ALSO

578     sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_logsrvd(8)
579
580     Protocol Buffers, https://developers.google.com/protocol-buffers/.
581

AUTHORS

583     Many people have worked on sudo over the years; this version consists of
584     code written primarily by:
585
586           Todd C. Miller
587
588     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

BUGS

593     If you believe you have found a bug in sudo, you can submit a bug report
594     at https://bugzilla.sudo.ws/
595

SUPPORT

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

DISCLAIMER

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.
607
608Sudo 1.9.12p2                 September 13, 2022                 Sudo 1.9.12p2
Impressum