From 05807cf5e1d51a6923532e063eb5ed9b0b3385be Mon Sep 17 00:00:00 2001
From: "Todd C. Miller" <Todd.Miller@courtesan.com>
Date: Mon, 27 Dec 2010 14:43:50 -0500
Subject: [PATCH] Document iolog_file and supported escape sequences for
 sudoers. Clarify that iolog_file can contain directories.

---
 doc/sudo_plugin.pod |  3 ++-
 doc/sudoers.pod     | 65 ++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 61 insertions(+), 7 deletions(-)

diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod
index 89536ed3a..99eebcaf9 100644
--- a/doc/sudo_plugin.pod
+++ b/doc/sudo_plugin.pod
@@ -576,7 +576,8 @@ no effect.
 
 =item iolog_file=string
 
-File name to use when I/O logging is enabled, relative to I<iolog_dir>.
+File name to use when I/O logging is enabled, relative to I<iolog_dir>
+(may also contain directory components).
 This is a hint to the I/O logging plugin which may choose to ignore
 it.  If no I/O logging plugin is loaded, this setting has no effect.
 
diff --git a/doc/sudoers.pod b/doc/sudoers.pod
index 3f4e7eeff..842dd4f38 100644
--- a/doc/sudoers.pod
+++ b/doc/sudoers.pod
@@ -1123,11 +1123,64 @@ list that exists and is executable.  The default is C<"@editor@">.
 
 =item iolog_dir
 
-The directory in which to store input/output logs when the I<log_input>
-or I<log_output> options are enabled or when the <LOG_INPUT> or
-C<LOG_OUTPUT> tags are present for a command.
+The top-level directory to use when constructing the path name for
+the input/output log directory.  Only used if the I<log_input> or
+I<log_output> options are enabled or when the <LOG_INPUT> or
+C<LOG_OUTPUT> tags are present for a command.  The session sequence
+number, if any, is stored in the directory.
 The default is C<"@iolog_dir@">.
 
+The following percent (`C<%>') escape sequences are supported:
+
+=over 4
+
+=item C<%{seq}>
+
+expanded to a monotonically increasing base-36 sequence number, such as 0100A5,
+where every two digits are used to form a new directory, e.g. F<01/00/A5>
+
+=item C<%{user}>
+
+expanded to the invoking user's login name
+
+=item C<%{group}>
+
+expanded to the name of the invoking user's real group ID
+
+=item C<%{runas_user}>
+
+expanded to the login name of the user the command will
+be run as (e.g. root)
+
+=item C<%{runas_group}>
+
+expanded to the group name of the user the command will
+be run as (e.g. wheel)
+
+=item C<%{hostname}>
+
+expanded to the local host name without the domain name
+
+=item C<%{command}>
+
+expanded to the base name of the command being run
+
+=back
+
+In addition, any escape sequences supported by the system's strftime()
+function will be expanded.
+
+=item iolog_file
+
+The path name, relative to I<iolog_dir>, in which to store input/output
+logs when the I<log_input> or I<log_output> options are enabled or
+when the <LOG_INPUT> or C<LOG_OUTPUT> tags are present for a command.
+Note that I<iolog_file> may contain directory components.
+The default is C<"%{seq}">.
+
+See the I<iolog_dir> option above for a list of supported percent
+(`C<%>') escape sequences.
+
 =item mailsub
 
 Subject of the mail sent to the I<mailto> user. The escape C<%h>
@@ -1145,7 +1198,7 @@ support C<LD_PRELOAD> or its equivalent.  Defaults to F<@noexec_file@>.
 
 The default prompt to use when asking for a password; can be overridden
 via the B<-p> option or the C<SUDO_PROMPT> environment variable.
-The following percent (`C<%>') escapes are supported:
+The following percent (`C<%>') escape sequences are supported:
 
 =over 4
 
@@ -1834,8 +1887,8 @@ user specification.
 
 =head1 SEE ALSO
 
-L<rsh(1)>, L<su(1)>, L<fnmatch(3)>, L<glob(3)>, L<sudoers.ldap(5)>,
-L<sudo_plugin(8)>, L<sudo(8)>, L<visudo(8)>
+L<rsh(1)>, L<su(1)>, L<fnmatch(3)>, L<glob(3)>, L<strftime(3)>,
+L<sudoers.ldap(5)>, L<sudo_plugin(8)>, L<sudo(8)>, L<visudo(8)>
 
 =head1 CAVEATS