--- embedaddon/sudo/doc/sudo_plugin.man.in	2013/07/22 10:46:12	1.1.1.4
+++ embedaddon/sudo/doc/sudo_plugin.man.in	2013/10/14 07:56:34	1.1.1.5
@@ -16,7 +16,7 @@
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.TH "SUDO_PLUGIN" "5" "March 5, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
+.TH "SUDO_PLUGIN" "5" "August 16, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -322,20 +322,31 @@ the
 \fB\-p\fR
 flag.
 .TP 6n
+remote_host=string
+The name of the remote host to run the command on, if specified via
+the
+\fB\-h\fR
+option.
+Support for running the command on a remote host is meant to be implemented
+via a helper program that is executed in place of the user-specified command.
+The
+\fBsudo\fR
+front end is only capable of executing commands on the local host.
+Only available starting with API version 1.4.
+.TP 6n
 run_shell=bool
 Set to true if the user specified the
 \fB\-s\fR
-flag, indicating that
-the user wishes to run a shell.
+flag, indicating that the user wishes to run a shell.
 .TP 6n
 runas_group=string
-The group name or gid to to run the command as, if specified via
+The group name or gid to run the command as, if specified via
 the
 \fB\-g\fR
 flag.
 .TP 6n
 runas_user=string
-The user name or uid to to run the command as, if specified via the
+The user name or uid to run the command as, if specified via the
 \fB\-u\fR
 flag.
 .TP 6n
@@ -441,13 +452,13 @@ pgid=int
 The ID of the process group that the running
 \fBsudo\fR
 process is a member of.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
 .TP 6n
 pid=int
 The process ID of the running
 \fBsudo\fR
 process.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
 .TP 6n
 plugin_options
 Any (non-comment) strings immediately after the plugin path are
@@ -480,7 +491,7 @@ ppid=int
 The parent process ID of the running
 \fBsudo\fR
 process.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
 .TP 6n
 sid=int
 The session ID of the running
@@ -488,7 +499,7 @@ The session ID of the running
 process or 0 if
 \fBsudo\fR
 is not part of a POSIX job control session.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
 .TP 6n
 tcpgid=int
 The ID of the foreground process group associated with the terminal
@@ -496,7 +507,7 @@ device associated with the
 \fBsudo\fR
 process or \-1 if there is no
 terminal present.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
 .TP 6n
 tty=string
 The path to the user's terminal device.
@@ -2162,6 +2173,47 @@ return SUDO_HOOK_RET_STOP;
 } while(0)
 .RE
 .fi
+.SS "Remote command execution"
+The
+\fBsudo\fR
+front end does not have native support for running remote commands.
+However, starting with
+\fBsudo\fR
+1.8.8, the
+\fB\-h\fR
+option may be used to specify a remote host that is passed
+to the policy plugin.
+A plugin may also accept a
+\fIrunas_user\fR
+in the form of
+``user@hostname''
+which will work with older versions of
+\fBsudo\fR.
+It is anticipated that remote commands will be supported by executing a
+``helper''
+program.
+The policy plugin should setup the execution environment such that the
+\fBsudo\fR
+front end will run the helper which, in turn, will connect to the
+remote host and run the command.
+.PP
+For example, the policy plugin could utilize
+\fBssh\fR
+to perform remote command execution.
+The helper program would be responsible for running
+\fBssh\fR
+with the proper options to use a private key or certificate
+that the remote host will accept and run a program
+on the remote host that would setup the execution environment
+accordingly.
+.PP
+Note that remote
+\fBsudoedit\fR
+functionality must be handled by the policy plugin, not
+\fBsudo\fR
+itself as the front end has no knowledge that a remote command is
+being executed.
+This may be addressed in a future revision of the plugin API.
 .SS "Conversation API"
 If the plugin needs to interact with the user, it may do so via the
 \fBconversation\fR()
@@ -2193,6 +2245,8 @@ struct sudo_conv_message {
     const char *msg;
 };
 
+#define SUDO_CONV_REPL_MAX      255
+
 struct sudo_conv_reply {
     char *reply;
 };
@@ -2227,9 +2281,19 @@ and
 \fRstruct sudo_conv_reply\fR
 for
 each message in the conversation.
-The plugin is responsible for freeing the reply buffer filled in to the
+The plugin is responsible for freeing the reply buffer located in each
 \fRstruct sudo_conv_reply\fR,
-if any.
+if it is not
+\fRNULL\fR.
+\fRSUDO_CONV_REPL_MAX\fR
+represents the maximum length of the reply buffer (not including
+the trailing NUL character).
+In practical terms, this is the longest password
+\fBsudo\fR
+will support.
+It is also useful as a maximum value for the
+\fBmemset_s\fR()
+function when clearing passwords filled in by the conversation function.
 .PP
 The
 \fBprintf\fR()-style
@@ -2524,6 +2588,13 @@ The
 \fBsudo\fR
 front end now installs default signal handlers to trap common signals
 while the plugin functions are run.
+.TP 6n
+Version 1.4 (sudo 1.8.8)
+The
+\fIremote_host\fR
+entry was added to the
+\fRsettings\fR
+list.
 .SH "SEE ALSO"
 sudo.conf(@mansectform@),
 sudoers(@mansectform@),