Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
SUDO_LOGSRV.PROTO(5)	       File Formats Manual	    SUDO_LOGSRV.PROTO(5)

NAME
     sudo_logsrv.proto -- Sudo log server protocol

DESCRIPTION
     Starting  with version 1.9.0, sudo supports sending event and I/O logs to a
     log server.  The protocol used is written in Google's Protocol Buffers  do-
     main  specific  language.	 The  "EXAMPLES" section includes a complete de-
     scription of the protocol in Protocol Buffers format.

     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 "length-prefix framing" and is how Google suggests handling
     the lack of message delimiters.

     The  protocol  is	made  up  of  two  basic  messages,  ClientMessage   and
     ServerMessage,  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.

Client Messages
     A ClientMessage is a container used to encapsulate all the possible message
     types a client may send to the server.

     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;
       }
     }

     The  different ClientMessage sub-messages the client may sent to the server
     are described below.

   TimeSpec
     message TimeSpec {
	 int64 tv_sec = 1;
	 int32 tv_nsec = 2;
     }

     A TimeSpec is the equivalent of a POSIX struct timespec, containing seconds
     and nanoseconds members.  The tv_sec member is a 64-bit integer to  support
     dates after the year 2038.

   InfoMessage
     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;
       }
     }

     An  InfoMessage 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 InfoMessage entries.  See  the  "EVENT  LOG  VARIABLES"
     section for more information.

   ClientHello hello_msg
     message ClientHello {
       string client_id = 1;
     }

     A	ClientHello  message  consists of client information that may be sent to
     the server when the client first connects.

     client_id
	     A free-form client description.  This usually includes the name and
	     version of the client implementation.

   AcceptMessage accept_msg
     message AcceptMessage {
       TimeSpec submit_time = 1;
       repeated InfoMessage info_msgs = 2;
       bool expect_iobufs = 3;
     }

     An AcceptMessage is sent by the client when a command is allowed by the se-
     curity policy.  It contains the following members:

     submit_time
	     The wall clock time when the command was submitted to the	security
	     policy.

     info_msgs
	     An  array of InfoMessage describing the user who submitted the com-
	     mand as well as the execution environment of the command.	This in-
	     formation 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.

     expect_iobufs
	     Set to true if the server should expect IoBuffer messages to follow
	     (for  I/O	logging)  or  false  if the server should only store the
	     event log.

     If an AcceptMessage is sent, the client must not send  a  RejectMessage  or
     RestartMessage.

   RejectMessage reject_msg
     message RejectMessage {
       TimeSpec submit_time = 1;
       string reason = 2;
       repeated InfoMessage info_msgs = 3;
     }

     A RejectMessage is sent by the client when a command is denied by the secu-
     rity policy.  It contains the following members:

     submit_time
	     The  wall clock time when the command was submitted to the security
	     policy.

     reason  The reason the security policy gave for denying the command.

     info_msgs
	     An array of InfoMessage describing the user who submitted the  com-
	     mand as well as the execution environment of the command.	This in-
	     formation is used to generate an event log entry.

     If  a  RejectMessage  is sent, the client must not send an AcceptMessage or
     RestartMessage.

   ExitMessage exit_msg
     message ExitMessage {
       TimeSpec run_time = 1;
       int32 exit_value = 2;
       bool dumped_core = 3;
       string signal = 4;
       string error = 5;
     }

     An ExitMessage is sent by the client after the command has  exited  or  has
     been terminated by a signal.  It contains the following members:

     run_time
	     The  total amount of elapsed time since the command started, calcu-
	     lated using a monotonic clock where possible.  This is not the wall
	     clock time.

     exit_value
	     The command's exit value in the range 0-255.

     dumped_core
	     True if the command was terminated by a signal and dumped core.

     signal  If the command was terminated by a signal, this is set to the  name
	     of  the  signal without the leading "SIG".  For example, INT, TERM,
	     KILL, SEGV.

     error   A message from the client indicating that the  command  was  termi-
	     nated unexpectedly due to an error.

     When performing I/O logging, the client should wait for a commit_point cor-
     responding  to  the final IoBuffer before closing the connection unless the
     final commit_point has already been received.

   RestartMessage restart_msg
     message RestartMessage {
       string log_id = 1;
       TimeSpec resume_point = 2;
     }

     A RestartMessage is sent by the client to resume sending  an  existing  I/O
     log that was previously interrupted.  It contains the following members:

     log_id  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.

     resume_point
	     The point in time after which to resume the I/O log.   This  is  in
	     the  form	of  a TimeSpec representing the amount of time since the
	     command started, not the wall clock time.	The resume_point  should
	     correspond  to  a commit_point previously sent to the client by the
	     server.  If the  server  receives	a  RestartMessage  containing  a
	     resume_point  it has not previously seen, an error will be returned
	     to the client and the connection will be dropped.

     If a RestartMessage is sent, the client must not send an  AcceptMessage  or
     RejectMessage.

   AlertMessage alert_msg
     message AlertMessage {
       TimeSpec alert_time = 1;
       string reason = 2;
       repeated InfoMessage info_msgs = 3;
     }

     An AlertMessage 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:

     alert_time
	     The wall clock time when the alert occurred.

     reason  The reason for the alert.

     info_msgs
	     An optional array of InfoMessage 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.

   IoBuffer ttyin_buf | ttyout_buf | stdin_buf | stdout_buf | stderr_buf
     message IoBuffer {
       TimeSpec delay = 1;
       bytes data = 2;
     }

     An IoBuffer is used to represent data from terminal input, terminal output,
     standard input, standard output, or standard error.  It contains  the  fol-
     lowing members:

     delay   The  elapsed  time since the last record in the form of a TimeSpec.
	     The delay should be calculated using a monotonic clock where possi-
	     ble.

     data    The binary I/O log data from terminal input, terminal output, stan-
	     dard input, standard output, or standard error.

   ChangeWindowSize winsize_event
     message ChangeWindowSize {
       TimeSpec delay = 1;
       int32 rows = 2;
       int32 cols = 3;
     }

     A ChangeWindowSize message is sent by the client when the terminal  running
     the command changes size.	It contains the following members:

     delay   The  elapsed  time since the last record in the form of a TimeSpec.
	     The delay should be calculated using a monotonic clock where possi-
	     ble.

     rows    The new number of terminal rows.

     cols    The new number of terminal columns.

   CommandSuspend suspend_event
     message CommandSuspend {
       TimeSpec delay = 1;
       string signal = 2;
     }

     A CommandSuspend message is sent by the client when the command  is  either
     suspended or resumed.  It contains the following members:

     delay   The  elapsed  time since the last record in the form of a TimeSpec.
	     The delay should be calculated using a monotonic clock where possi-
	     ble.

     signal  The signal name without the  leading  "SIG".   For  example,  STOP,
	     TSTP, CONT.

Server Messages
     A ServerMessage is a container used to encapsulate all the possible message
     types the server may send to a client.

     message ServerMessage {
       oneof type {
	 ServerHello hello = 1;
	 TimeSpec commit_point = 2;
	 string log_id = 3;
	 string error = 4;
	 string abort = 5;
       }
     }

     The  different ServerMessage sub-messages the server may sent to the client
     are described below.

   ServerHello hello
     message ServerHello {
       string server_id = 1;
       string redirect = 2;
       repeated string servers = 3;
       bool subcommands = 4;
     }

     The ServerHello message consists of server information sent when the client
     first connects.  It contains the following members:

     server_id
	     A free-form server description.  Usually this includes the name and
	     version of the implementation running on the log server.  This mem-
	     ber is always present.

     redirect
	     A host and port separated by a colon (`'): 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
	     ServerHello when it includes a redirect.

     servers
	     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.

     subcommands
	     If set, the server supports logging additional  commands  during  a
	     session.	The  client  may  send an AcceptMessage or RejectMessage
	     when sudo is running in intercept mode.   In  this  mode,	commands
	     spawned  from the initial command authorized by sudo are subject to
	     policy restrictions and/or are logged.  If  subcommands  is  false,
	     the client must not attempt to log additional commands.

   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
     IoBuffer but rather at a server-configurable interval.  When the server re-
     ceives an ExitMessage, it will respond with a commit_point corresponding to
     the last received IoBuffer before closing the connection.

   string log_id
     The  server-side  ID  of  the  I/O log being stored, sent in response to an
     AcceptMessage where expect_iobufs is true.

   string error
     A fatal server-side error.  The server  will  close  the  connection  after
     sending the error message.

   string abort
     An  abort 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
     abort message.

Protocol flow of control
     The expected protocol flow is as follows:

     1.   Client  connects to the first available server.  If the client is con-
	  figured to use TLS, a TLS handshake will be attempted.

     2.   Client sends ClientHello.  This is currently optional but  allows  the
	  server to detect a non-TLS connection on the TLS port.

     3.   Server sends ServerHello.

     4.   Client   responds   with   either   AcceptMessage,  RejectMessage,  or
	  RestartMessage.

     5.   If client sent a AcceptMessage with expect_iobufs set, server  creates
	  a new I/O log and responds with a log_id.

     6.   Client sends zero or more IoBuffer messages.

     7.   Server periodically responds to IoBuffer messages with a commit_point.

     8.   Client sends an ExitMessage when the command exits or is killed.

     9.   Server sends the final commit_point if one is pending.

     10.  Server closes the connection.  After receiving the final commit_point,
	  the client shuts down its side of the TLS connection if TLS is in use,
	  and closes the connection.

     11.  Server shuts down its side of the TLS connection if TLS is in use, and
	  closes the connection.

     At  any  point, the server may send an error or abort message to the client
     at which point the server will close the connection.  If an  abort  message
     is received, the client should terminate the running command.

EVENT LOG VARIABLES
     AcceptMessage,  AlertMessage  and RejectMessage classes contain an array of
     InfoMessage 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.

     Some variables have a client, run, or submit 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.   Vari-
     ables with a client prefix pertain to the program performing the connection
     to  the  log server, for example sudo.  Variables with a run prefix pertain
     to the command that the user requested be run.   Variables  with  a  submit
     prefix pertain to the user submitting the request (the user running sudo).

     The following InfoMessage entries are required:

     Key	    Type	  Description
     command	    string	  command that was submitted
     runuser	    string	  name of user the command was run as
     submithost     string	  name of host the command was submitted on
     submituser     string	  name of user submitting the command

     The following InfoMessage entries are recognized, but not required:

     Key	    Type	  Description
     clientargv     StringList	  client's original argument vector
     clientpid	    int64	  client's process ID
     clientppid     int64	  client's parent process ID
     clientsid	    int64	  client's terminal session ID
     columns	    int64	  number of columns in the terminal
     lines	    int64	  number of lines in the terminal
     runargv	    StringList	  argument vector of command to run
     runchroot	    string	  root directory of command to run
     runcwd	    string	  running command's working directory
     runenv	    StringList	  the running command's environment
     rungid	    int64	  primary group-ID of the command
     rungids	    NumberList	  supplementary group-IDs for the command
     rungroup	    string	  primary group name of the command
     rungroups	    StringList	  supplementary group names for the command
     runuid	    int64	  run user's user-ID
     submitcwd	    string	  submit user's current working directory
     submitenv	    StringList	  the submit user's environment
     submitgid	    int64	  submit user's primary group-ID
     submitgids     NumberList	  submit user's supplementary group-IDs
     submitgroup    string	  submitting user's primary group name
     submitgroups   StringList	  submit user's supplementary group names
     submituid	    int64	  submit user's user-ID
     ttyname	    string	  terminal the command was submitted from

     The  server  must	accept	other  variables not listed above but may ignore
     them.

EXAMPLES
     The Protocol Buffers description of the log server protocol, using "proto3"
     syntax, is included in full below.

     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 */
     }

SEE ALSO
     sudo_logsrvd.conf(5), sudoers(5), sudo(8), sudo_logsrvd(8)

     Protocol Buffers, https://protobuf.dev/.

AUTHORS
     Many people have worked on sudo over the years; this  version  consists  of
     code written primarily by:

	   Todd C. Miller

     See     the    CONTRIBUTORS.md    file    in    the    sudo    distribution
     (https://www.sudo.ws/about/contributors/) for an exhaustive list of  people
     who have contributed to sudo.

BUGS
     If  you  believe  you have found a bug in sudo_logsrv.proto, 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).

     Please do 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.

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.

DISCLAIMER
     sudo is provided "AS IS" 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	distrib-
     uted with sudo or https://www.sudo.ws/about/license/ for complete details.

Sudo 1.9.17p2		       September 13, 2022	    SUDO_LOGSRV.PROTO(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sudo_logsrv.proto&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>

home | help