Imported Upstream version 3.12

16 files changed, 803 insertions, 35 deletions

diff --git a/docs/api/remctl.3 b/docs/api/remctl.3
index 4a581df..b3c618c 100644
--- a/docs/api/remctl.3
+++ b/docs/api/remctl.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL 3"
-.TH REMCTL 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_close.3 b/docs/api/remctl_close.3
index 76392bf..3bc5d15 100644
--- a/docs/api/remctl_close.3
+++ b/docs/api/remctl_close.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_CLOSE 3"
-.TH REMCTL_CLOSE 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_CLOSE 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_command.3 b/docs/api/remctl_command.3
index 24ff46b..e522f3f 100644
--- a/docs/api/remctl_command.3
+++ b/docs/api/remctl_command.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_COMMAND 3"
-.TH REMCTL_COMMAND 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_COMMAND 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_error.3 b/docs/api/remctl_error.3
index 98f04e1..688e5af 100644
--- a/docs/api/remctl_error.3
+++ b/docs/api/remctl_error.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_ERROR 3"
-.TH REMCTL_ERROR 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_ERROR 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_new.3 b/docs/api/remctl_new.3
index 72e07f2..2acb013 100644
--- a/docs/api/remctl_new.3
+++ b/docs/api/remctl_new.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_NEW 3"
-.TH REMCTL_NEW 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_NEW 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_noop.3 b/docs/api/remctl_noop.3
index 8b1ed8e..0a576ec 100644
--- a/docs/api/remctl_noop.3
+++ b/docs/api/remctl_noop.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_NOOP 3"
-.TH REMCTL_NOOP 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_NOOP 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_open.3 b/docs/api/remctl_open.3
index 405e97b..68dde52 100644
--- a/docs/api/remctl_open.3
+++ b/docs/api/remctl_open.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_OPEN 3"
-.TH REMCTL_OPEN 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_OPEN 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_output.3 b/docs/api/remctl_output.3
index 408aa8c..4cf5b7a 100644
--- a/docs/api/remctl_output.3
+++ b/docs/api/remctl_output.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_OUTPUT 3"
-.TH REMCTL_OUTPUT 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_OUTPUT 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_set_ccache.3 b/docs/api/remctl_set_ccache.3
index 875d1ae..841067f 100644
--- a/docs/api/remctl_set_ccache.3
+++ b/docs/api/remctl_set_ccache.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_SET_CCACHE 3"
-.TH REMCTL_SET_CCACHE 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_SET_CCACHE 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_set_source_ip.3 b/docs/api/remctl_set_source_ip.3
index 644bcc4..5625f6a 100644
--- a/docs/api/remctl_set_source_ip.3
+++ b/docs/api/remctl_set_source_ip.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_SET_SOURCE_IP 3"
-.TH REMCTL_SET_SOURCE_IP 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_SET_SOURCE_IP 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/api/remctl_set_timeout.3 b/docs/api/remctl_set_timeout.3
index 6a78bcb..35b9d15 100644
--- a/docs/api/remctl_set_timeout.3
+++ b/docs/api/remctl_set_timeout.3
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL_SET_TIMEOUT 3"
-.TH REMCTL_SET_TIMEOUT 3 "2016-05-07" "3.11" "remctl Library Reference"
+.TH REMCTL_SET_TIMEOUT 3 "2016-07-29" "3.12" "remctl Library Reference"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/remctl-shell.8.in b/docs/remctl-shell.8.in
new file mode 100644
index 0000000..b39be98
--- /dev/null
+++ b/docs/remctl-shell.8.in
@@ -0,0 +1,419 @@
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "REMCTL-SHELL 8"
+.TH REMCTL-SHELL 8 "2016-07-29" "3.12" "remctl"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+remctl\-shell \- Restricted shell that mimics a remctl server
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+remctl-shell [\fB\-dhqSv\fR] [\fB\-f\fR \fIconfig\fR] \fB\-c\fR \fIcommand\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+\&\fBremctl-shell\fR is a restricted shell that mimics the behavior of the
+\&\fBremctld\fR server without using the remctl protocol, GSS-API, or Kerberos.
+It's intended to be run via ssh as the shell for a special user (by
+convention, \f(CW\*(C`remctl\*(C'\fR, although the shell itself doesn't care), with an
+\&\fIauthorized_keys\fR file that specifies the user identity corresponding to
+each key that is allowed to run remctl commands.  All access control then
+works as normal.
+.PP
+The output of the command ran is returned on standard output and standard
+error, like a normal command run via ssh, and the exit status of
+\&\fBremctl-shell\fR will be the exit status of the command.  Only one command
+can be run per ssh connection, so this will be noticeably slower for each
+command execution than a well-designed remctl client and server design
+that holds connections open for multiple commands.
+.PP
+\&\fBremctl-shell\fR is designed to mimic the behavior of \fBremctld\fR and uses
+the same configuration syntax and environment variables.  See
+\&\*(L"\s-1CONFIGURATION FILE\*(R"\s0 in \fIremctld\fR\|(8) for configuration information and
+\&\s-1ENVIRONMENT\s0 below for more specific details about environment variable
+handling.  The location of the configuration file may be specified with
+the \fB\-f\fR option.  The default location is \fI\f(CI@sysconfdir\fI@/remctl.conf\fR.
+.PP
+Since \fBremctl-shell\fR is designed to be run by a potentially untrusted
+user as a shell, normally all error messages and logging is done via
+syslog and not sent to standard error.  See the \fB\-S\fR, \fB\-d\fR, and \fB\-q\fR
+options when running it manually to debug problems.  (When running
+manually, you will also normally need to set the \s-1REMCTL_USER\s0 and
+\&\s-1SSH_CONNECTION\s0 environment variables.)
+.SS "Quoting and Command Limitations"
+.IX Subsection "Quoting and Command Limitations"
+The ssh protocol is much less sophisticated than remctl at passing command
+arguments from the client to the server, so \fBremctl-shell\fR requires
+careful attention to command arguments and quoting.  ssh does no quoting
+of arguments, just adds a single space between each argument and passes
+them verbatim to the shell on the server side.  This means the client has
+to add quoting to any arguments containing whitespace.  \fBremctl-shell\fR
+supports single and double quotes, and supports using backslash to escape
+any character inside or outside either quotes.  However, be aware, when
+running ssh from the command line, that your shell will remove another
+level of quoting.  You will therefore usually have to double-quote
+arguments.
+.PP
+For example, to run the command \f(CW\*(C`log message\*(C'\fR with argument \f(CW\*(C`this is a
+message\*(C'\fR via ssh from the command line, use:
+.PP
+.Vb 1
+\&    ssh remctl@example.com log message "\*(Aqthis is a message\*(Aq"
+.Ve
+.PP
+The first level of \f(CW""\fR quoting will be removed by your local shell, and
+\&\fBremctl-shell\fR will interpret the second level of \f(CW\*(Aq\*(Aq\fR quotes.  Note
+that, because of how ssh does command argument passing, this is exactly
+equivalent to:
+.PP
+.Vb 1
+\&    ssh remctl@example.com "log message \*(Aqthis is a message\*(Aq"
+.Ve
+.PP
+since ssh doesn't preserve the distinction between separate arguments when
+creating the command to send to the remote server.  It may be less
+confusing to get in the habit of quoting the entire command.
+.PP
+Also be aware that the full command is passed via command line arguments,
+which means there is a tight limit on the length of the whole command plus
+arguments.  Expect to have problems if the total command length exceeds
+1000 characters.  For the same reason, binary data including nul
+characters cannot be passed via \fBremctl-shell\fR.  (The regular remctl
+protocol supports arbitrary-length arguments, limited only by server-side
+configuration and available server memory, and supports arbitrary binary
+data in arguments.)
+.ie n .SS """authorized_keys"" Configuration"
+.el .SS "\f(CWauthorized_keys\fP Configuration"
+.IX Subsection "authorized_keys Configuration"
+\&\fBremctl-shell\fR is intended for use via ssh using \f(CW\*(C`authorized_keys\*(C'\fR to
+manage authentication.  (If you have Kerberos available, it's generally
+better to use the normal \fBremctld\fR server and native remctl protocol.)
+The \f(CW\*(C`authorized_keys\*(C'\fR configuration must be set up to associate each key
+with an identity by setting the \s-1REMCTL_USER\s0 environment variable.  Using
+user identities that look like Kerberos principal names is strongly
+recommended, since it may make it easier to use some of the \s-1ACL\s0 methods
+intended for the normal remctl server.
+.PP
+\&\fBremctl-shell\fR will not make use of forwarded connections or agents, and
+will not pass them along to the processes they run, so all such ssh
+options should normally be disabled for defense in depth security.
+.PP
+Here is a recommended line in \f(CW\*(C`authorized_keys\*(C'\fR for the account managed
+by \fBremctl-shell\fR, with appropriate restrictions and an example of how to
+set the \s-1REMCTL_USER\s0 variable.  Backslashes and line breaks were added for
+clarity.  The actual entry should be a single long line.
+.PP
+.Vb 3
+\&    environment="REMCTL_USER=example@EXAMPLE.ORG",no\-agent\-forwarding,\e
+\&    no\-port\-forwarding,no\-pty,no\-user\-rc,no\-X11\-forwarding ssh\-rsa \e
+\&    AAAAB3NzaC1yc2EA... example@some\-host.example.org
+.Ve
+.PP
+Setting \f(CW\*(C`no\-user\-rc\*(C'\fR is particularly important for \fBremctl-shell\fR.  If
+you have OpenSSH 7.2 or later, which added the \f(CW\*(C`restrict\*(C'\fR keyword, you
+can instead use the much simpler:
+.PP
+.Vb 2
+\&    environment="REMCTL_USER=example@EXAMPLE.ORG",restrict ssh\-rsa \e
+\&    AAAAB3NzaC1yc2EA... example@some\-host.example.org
+.Ve
+.PP
+\&\s-1REMCTL_USER\s0 should be set to the identity string for the owner of that key
+pair, as used in the ACLs in your remctl configuration.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+\&\fBremctl-shell\fR is normally only run with the \fB\-c\fR option since it's
+intended for use as a shell.  However, it does support some other options
+for testing, and one can use a small wrapper program as the configured
+shell that passes additional options into \fBremctl-shell\fR if needed.
+.PP
+The start of each option description is annotated with the version of
+\&\fBremctl-shell\fR in which that option was added with its current meaning.
+.IP "\fB\-c\fR \fIcommand\fR" 4
+.IX Item "-c command"
+[3.12] The command to run.  This is how ssh passes the command string into
+\&\fBremctl-shell\fR.  \fBremctl-shell\fR will then parse it into separate
+arguments using an algorithm similar to that used by a shell.  See the
+above discussion of quoting for more information.
+.Sp
+The start of each option description is annotated with the version of
+\&\fBremctl-shell\fR in which that option was added with its current meaning.
+.IP "\fB\-d\fR" 4
+.IX Item "-d"
+[3.12] Enable verbose debug logging to syslog (or to standard output if
+\&\fB\-S\fR is also given).
+.IP "\fB\-f\fR \fIconfig\fR" 4
+.IX Item "-f config"
+[3.12] The configuration file for \fBremctld\fR, overriding the default path.
+.IP "\fB\-h\fR" 4
+.IX Item "-h"
+[3.12] Show a brief usage message and then exit.  This usage method will
+include a list of supported \s-1ACL\s0 types and can be used to determine if
+optional \s-1ACL\s0 methods were compiled into a given \fBremctl-shell\fR build.
+.IP "\fB\-q\fR" 4
+.IX Item "-q"
+[3.12] Suppress the normal informational logging of what commands are
+being executed and by whom.  This is intended primarily to avoid spamming
+syslog during testing.
+.IP "\fB\-S\fR" 4
+.IX Item "-S"
+[3.12] Rather than logging to syslog, log debug and routine connection
+messages to standard output and error messages to standard error.  In
+normal usage, this would send all the logging back to the client,
+intermixed with program output, so it's normally useful only for testing
+and debugging.
+.IP "\fB\-v\fR" 4
+.IX Item "-v"
+[3.12] Print the version of \fBremctl-shell\fR and exit.
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+\&\fBremctl-shell\fR itself requires the following environment variables be set
+when it is invoked, or it exits with an error and doesn't do anything.
+.IP "\s-1REMCTL_USER\s0" 4
+.IX Item "REMCTL_USER"
+The user used for logging and to make authorization decisions.  The
+security of all \fBremctl-shell\fR authorization checks is based on the
+accuracy of this environment variable, so be sure that it is set
+correctly.  The best way to do this is via \f(CW\*(C`environment\*(C'\fR stanzas in
+\&\fIauthorized_keys\fR as described above.
+.IP "\s-1SSH_CONNECTION\s0" 4
+.IX Item "SSH_CONNECTION"
+\&\fBsshd\fR uses this environment variable to communication information about
+the local and remote \s-1IP\s0 addresses and ports of the ssh connection.
+\&\fBremctl-shell\fR expects the first space-separated token in this
+environment variable to be the \s-1IP\s0 address of the client.  It then uses
+that to set \s-1REMOTE_ADDR\s0 in the environment of any commands it runs.
+.PP
+The following environment variables will be set for any commands run via
+\&\fBremctl-shell\fR (annotated with the version at which they were added).
+These are mostly the same as those set by \fBremctld\fR.  Differences are
+noted in each description.
+.IP "\s-1REMCTL_COMMAND\s0" 4
+.IX Item "REMCTL_COMMAND"
+[3.12] The command string that caused this command to be run.  This
+variable will contain only the command, not the subcommand or any
+additional arguments (which are passed as command arguments).
+.IP "\s-1REMOTE_ADDR\s0" 4
+.IX Item "REMOTE_ADDR"
+[3.12] The \s-1IP\s0 address of the remote host.  This may be IPv4 or IPv6.  This
+is taken from the \s-1SSH_CONNECTION\s0 environment variable.
+.IP "\s-1REMOTE_EXPIRES\s0" 4
+.IX Item "REMOTE_EXPIRES"
+[3.12] Normally, this communicates the time (in seconds since \s-1UNIX\s0 epoch)
+when the authenticated remote session will expire.  However, this is not a
+meaningful concept for ssh authentication via public key, and regardless
+is not communicated by \fBsshd\fR to the shell.  It is therefore always set
+to \f(CW0\fR by \fBremctl-shell\fR.
+.IP "\s-1REMOTE_HOST\s0" 4
+.IX Item "REMOTE_HOST"
+[3.12] The hostname of the remote host, if it was available.  If reverse
+name resolution failed, this environment variable will not be set.
+.Sp
+This is determined via a simple reverse \s-1DNS\s0 lookup and should be
+considered under the control of the client.  remctl commands should treat
+it with skepticism and not use it for anything other than logging
+purposes.
+.IP "\s-1REMOTE_USER\s0" 4
+.IX Item "REMOTE_USER"
+.PD 0
+.IP "\s-1REMUSER\s0" 4
+.IX Item "REMUSER"
+.PD
+[3.12] Set to the value of \s-1REMCTL_CLIENT\s0 as set in the environment of
+\&\fBremctl-shell\fR. This should be set security via \fIauthorized_keys\fR as
+discussed above.
+.PP
+Note that \s-1REMOTE_HOST\s0 is not set by \fBremctl-shell\fR, at least currently.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+Typically, \fBremctl-shell\fR will be set as the shell for a dedicated user,
+normally \f(CW\*(C`remctl\*(C'\fR, via the normal mechanism for local account creation.
+That account should be configured with an ssh \fIauthorized_keys\fR file as
+discussed above.  \fBremctl-shell\fR will then be invoked with:
+.PP
+.Vb 1
+\&    remctl\-shell \-c \*(Aqcommand subcommand argument\*(Aq
+.Ve
+.PP
+by \fBsshd\fR for each incoming connection from a user that has a key in the
+\&\fIauthorized_keys\fR file.
+.PP
+If you need to run a command manually for debugging, you can run the same
+command as above, but it's often more useful to send errors to standard
+error instead of to syslog.  You can do that with:
+.PP
+.Vb 1
+\&    remctl\-shell \-S \-c \*(Aqcommand subcommand argument\*(Aq
+.Ve
+.PP
+If you don't want to see the normal command logging, add the \fB\-q\fR option
+as well.  You can test an alternate configuration file by specifying it
+with the \fB\-f\fR option.
+.SH "COMPATIBILITY"
+.IX Header "COMPATIBILITY"
+\&\fBremctl-shell\fR was added in the remctl 3.12 release.
+.SH "CAVEATS"
+.IX Header "CAVEATS"
+Most of the caveats and differences between \fBremctl-shell\fR and the normal
+\&\fBremctld\fR server are from quoting and the limitations of passing
+arguments via the command line.  Review the section on quoting above for
+more information.
+.PP
+Normally, \fBremctl-shell\fR runs as a dedicated non-root user (as opposed to
+often running as root like \fBremctld\fR), which means that all commands will
+normally run as that user and the \f(CW\*(C`user\*(C'\fR configuration option will not
+work.  The easiest way to run commands as other users is to have the
+underlying command use \fBsudo\fR or some other user switching mechanism,
+which will normally require additional local configuration.
+.SH "AUTHOR"
+.IX Header "AUTHOR"
+\&\fBremctl-shell\fR was written by Russ Allbery <eagle@eyrie.org>.  Many
+thanks to Dropbox, Inc. for providing the time to write the initial
+implementation during Dropbox's annual Hack Week.
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright 2016 Dropbox, Inc.
+.PP
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fIremctld\fR\|(8), \fIsshd\fR\|(8)
+.PP
+The current version of this program is available from its web page at
+<http://www.eyrie.org/~eagle/software/remctl/>.
diff --git a/docs/remctl-shell.pod b/docs/remctl-shell.pod
new file mode 100644
index 0000000..af3cfc7
--- /dev/null
+++ b/docs/remctl-shell.pod
@@ -0,0 +1,308 @@
+=for stopwords
+remctl -dhqSv ACL Allbery GSS-API REMUSER nul remctld sshd subcommand
+
+=head1 NAME
+
+remctl-shell - Restricted shell that mimics a remctl server
+
+=head1 SYNOPSIS
+
+remctl-shell [B<-dhqSv>] [B<-f> I<config>] B<-c> I<command>
+
+=head1 DESCRIPTION
+
+B<remctl-shell> is a restricted shell that mimics the behavior of the
+B<remctld> server without using the remctl protocol, GSS-API, or Kerberos.
+It's intended to be run via ssh as the shell for a special user (by
+convention, C<remctl>, although the shell itself doesn't care), with an
+F<authorized_keys> file that specifies the user identity corresponding to
+each key that is allowed to run remctl commands.  All access control then
+works as normal.
+
+The output of the command ran is returned on standard output and standard
+error, like a normal command run via ssh, and the exit status of
+B<remctl-shell> will be the exit status of the command.  Only one command
+can be run per ssh connection, so this will be noticeably slower for each
+command execution than a well-designed remctl client and server design
+that holds connections open for multiple commands.
+
+B<remctl-shell> is designed to mimic the behavior of B<remctld> and uses
+the same configuration syntax and environment variables.  See
+L<remctld(8)/"CONFIGURATION FILE"> for configuration information and
+L<ENVIRONMENT> below for more specific details about environment variable
+handling.  The location of the configuration file may be specified with
+the B<-f> option.  The default location is F<@sysconfdir@/remctl.conf>.
+
+Since B<remctl-shell> is designed to be run by a potentially untrusted
+user as a shell, normally all error messages and logging is done via
+syslog and not sent to standard error.  See the B<-S>, B<-d>, and B<-q>
+options when running it manually to debug problems.  (When running
+manually, you will also normally need to set the REMCTL_USER and
+SSH_CONNECTION environment variables.)
+
+=head2 Quoting and Command Limitations
+
+The ssh protocol is much less sophisticated than remctl at passing command
+arguments from the client to the server, so B<remctl-shell> requires
+careful attention to command arguments and quoting.  ssh does no quoting
+of arguments, just adds a single space between each argument and passes
+them verbatim to the shell on the server side.  This means the client has
+to add quoting to any arguments containing whitespace.  B<remctl-shell>
+supports single and double quotes, and supports using backslash to escape
+any character inside or outside either quotes.  However, be aware, when
+running ssh from the command line, that your shell will remove another
+level of quoting.  You will therefore usually have to double-quote
+arguments.
+
+For example, to run the command C<log message> with argument C<this is a
+message> via ssh from the command line, use:
+
+    ssh remctl@example.com log message "'this is a message'"
+
+The first level of C<""> quoting will be removed by your local shell, and
+B<remctl-shell> will interpret the second level of C<''> quotes.  Note
+that, because of how ssh does command argument passing, this is exactly
+equivalent to:
+
+    ssh remctl@example.com "log message 'this is a message'"
+
+since ssh doesn't preserve the distinction between separate arguments when
+creating the command to send to the remote server.  It may be less
+confusing to get in the habit of quoting the entire command.
+
+Also be aware that the full command is passed via command line arguments,
+which means there is a tight limit on the length of the whole command plus
+arguments.  Expect to have problems if the total command length exceeds
+1000 characters.  For the same reason, binary data including nul
+characters cannot be passed via B<remctl-shell>.  (The regular remctl
+protocol supports arbitrary-length arguments, limited only by server-side
+configuration and available server memory, and supports arbitrary binary
+data in arguments.)
+
+=head2 C<authorized_keys> Configuration
+
+B<remctl-shell> is intended for use via ssh using C<authorized_keys> to
+manage authentication.  (If you have Kerberos available, it's generally
+better to use the normal B<remctld> server and native remctl protocol.)
+The C<authorized_keys> configuration must be set up to associate each key
+with an identity by setting the REMCTL_USER environment variable.  Using
+user identities that look like Kerberos principal names is strongly
+recommended, since it may make it easier to use some of the ACL methods
+intended for the normal remctl server.
+
+B<remctl-shell> will not make use of forwarded connections or agents, and
+will not pass them along to the processes they run, so all such ssh
+options should normally be disabled for defense in depth security.
+
+Here is a recommended line in C<authorized_keys> for the account managed
+by B<remctl-shell>, with appropriate restrictions and an example of how to
+set the REMCTL_USER variable.  Backslashes and line breaks were added for
+clarity.  The actual entry should be a single long line.
+
+    environment="REMCTL_USER=example@EXAMPLE.ORG",no-agent-forwarding,\
+    no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa \
+    AAAAB3NzaC1yc2EA... example@some-host.example.org
+
+Setting C<no-user-rc> is particularly important for B<remctl-shell>.  If
+you have OpenSSH 7.2 or later, which added the C<restrict> keyword, you
+can instead use the much simpler:
+
+    environment="REMCTL_USER=example@EXAMPLE.ORG",restrict ssh-rsa \
+    AAAAB3NzaC1yc2EA... example@some-host.example.org
+
+REMCTL_USER should be set to the identity string for the owner of that key
+pair, as used in the ACLs in your remctl configuration.
+
+=head1 OPTIONS
+
+B<remctl-shell> is normally only run with the B<-c> option since it's
+intended for use as a shell.  However, it does support some other options
+for testing, and one can use a small wrapper program as the configured
+shell that passes additional options into B<remctl-shell> if needed.
+
+The start of each option description is annotated with the version of
+B<remctl-shell> in which that option was added with its current meaning.
+
+=over 4
+
+=item B<-c> I<command>
+
+[3.12] The command to run.  This is how ssh passes the command string into
+B<remctl-shell>.  B<remctl-shell> will then parse it into separate
+arguments using an algorithm similar to that used by a shell.  See the
+above discussion of quoting for more information.
+
+The start of each option description is annotated with the version of
+B<remctl-shell> in which that option was added with its current meaning.
+
+=item B<-d>
+
+[3.12] Enable verbose debug logging to syslog (or to standard output if
+B<-S> is also given).
+
+=item B<-f> I<config>
+
+[3.12] The configuration file for B<remctld>, overriding the default path.
+
+=item B<-h>
+
+[3.12] Show a brief usage message and then exit.  This usage method will
+include a list of supported ACL types and can be used to determine if
+optional ACL methods were compiled into a given B<remctl-shell> build.
+
+=item B<-q>
+
+[3.12] Suppress the normal informational logging of what commands are
+being executed and by whom.  This is intended primarily to avoid spamming
+syslog during testing.
+
+=item B<-S>
+
+[3.12] Rather than logging to syslog, log debug and routine connection
+messages to standard output and error messages to standard error.  In
+normal usage, this would send all the logging back to the client,
+intermixed with program output, so it's normally useful only for testing
+and debugging.
+
+=item B<-v>
+
+[3.12] Print the version of B<remctl-shell> and exit.
+
+=back
+
+=head1 ENVIRONMENT
+
+B<remctl-shell> itself requires the following environment variables be set
+when it is invoked, or it exits with an error and doesn't do anything.
+
+=over 4
+
+=item REMCTL_USER
+
+The user used for logging and to make authorization decisions.  The
+security of all B<remctl-shell> authorization checks is based on the
+accuracy of this environment variable, so be sure that it is set
+correctly.  The best way to do this is via C<environment> stanzas in
+F<authorized_keys> as described above.
+
+=item SSH_CONNECTION
+
+B<sshd> uses this environment variable to communication information about
+the local and remote IP addresses and ports of the ssh connection.
+B<remctl-shell> expects the first space-separated token in this
+environment variable to be the IP address of the client.  It then uses
+that to set REMOTE_ADDR in the environment of any commands it runs.
+
+=back
+
+The following environment variables will be set for any commands run via
+B<remctl-shell> (annotated with the version at which they were added).
+These are mostly the same as those set by B<remctld>.  Differences are
+noted in each description.
+
+=over 4
+
+=item REMCTL_COMMAND
+
+[3.12] The command string that caused this command to be run.  This
+variable will contain only the command, not the subcommand or any
+additional arguments (which are passed as command arguments).
+
+=item REMOTE_ADDR
+
+[3.12] The IP address of the remote host.  This may be IPv4 or IPv6.  This
+is taken from the SSH_CONNECTION environment variable.
+
+=item REMOTE_EXPIRES
+
+[3.12] Normally, this communicates the time (in seconds since UNIX epoch)
+when the authenticated remote session will expire.  However, this is not a
+meaningful concept for ssh authentication via public key, and regardless
+is not communicated by B<sshd> to the shell.  It is therefore always set
+to C<0> by B<remctl-shell>.
+
+=item REMOTE_HOST
+
+[3.12] The hostname of the remote host, if it was available.  If reverse
+name resolution failed, this environment variable will not be set.
+
+This is determined via a simple reverse DNS lookup and should be
+considered under the control of the client.  remctl commands should treat
+it with skepticism and not use it for anything other than logging
+purposes.
+
+=item REMOTE_USER
+
+=item REMUSER
+
+[3.12] Set to the value of REMCTL_CLIENT as set in the environment of
+B<remctl-shell>. This should be set security via F<authorized_keys> as
+discussed above.
+
+=back
+
+Note that REMOTE_HOST is not set by B<remctl-shell>, at least currently.
+
+=head1 EXAMPLES
+
+Typically, B<remctl-shell> will be set as the shell for a dedicated user,
+normally C<remctl>, via the normal mechanism for local account creation.
+That account should be configured with an ssh F<authorized_keys> file as
+discussed above.  B<remctl-shell> will then be invoked with:
+
+    remctl-shell -c 'command subcommand argument'
+
+by B<sshd> for each incoming connection from a user that has a key in the
+F<authorized_keys> file.
+
+If you need to run a command manually for debugging, you can run the same
+command as above, but it's often more useful to send errors to standard
+error instead of to syslog.  You can do that with:
+
+    remctl-shell -S -c 'command subcommand argument'
+
+If you don't want to see the normal command logging, add the B<-q> option
+as well.  You can test an alternate configuration file by specifying it
+with the B<-f> option.
+
+=head1 COMPATIBILITY
+
+B<remctl-shell> was added in the remctl 3.12 release.
+
+=head1 CAVEATS
+
+Most of the caveats and differences between B<remctl-shell> and the normal
+B<remctld> server are from quoting and the limitations of passing
+arguments via the command line.  Review the section on quoting above for
+more information.
+
+Normally, B<remctl-shell> runs as a dedicated non-root user (as opposed to
+often running as root like B<remctld>), which means that all commands will
+normally run as that user and the C<user> configuration option will not
+work.  The easiest way to run commands as other users is to have the
+underlying command use B<sudo> or some other user switching mechanism,
+which will normally require additional local configuration.
+
+=head1 AUTHOR
+
+B<remctl-shell> was written by Russ Allbery <eagle@eyrie.org>.  Many
+thanks to Dropbox, Inc. for providing the time to write the initial
+implementation during Dropbox's annual Hack Week.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2016 Dropbox, Inc.
+
+Copying and distribution of this file, with or without modification, are
+permitted in any medium without royalty provided the copyright notice and
+this notice are preserved.  This file is offered as-is, without any
+warranty.
+  
+=head1 SEE ALSO
+
+remctld(8), sshd(8)
+
+The current version of this program is available from its web page at
+L<http://www.eyrie.org/~eagle/software/remctl/>.
+
+=cut
diff --git a/docs/remctl.1 b/docs/remctl.1
index 84d2515..08d882a 100644
--- a/docs/remctl.1
+++ b/docs/remctl.1
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTL 1"
-.TH REMCTL 1 "2016-05-07" "3.11" "remctl"
+.TH REMCTL 1 "2016-07-29" "3.12" "remctl"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
diff --git a/docs/remctld.8.in b/docs/remctld.8.in
index 0fe249e..50374a8 100644
--- a/docs/remctld.8.in
+++ b/docs/remctld.8.in
@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "REMCTLD 8"
-.TH REMCTLD 8 "2016-05-07" "3.11" "remctl"
+.TH REMCTLD 8 "2016-07-29" "3.12" "remctl"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -394,6 +394,21 @@ command line.  Only at most one argument may be passed on standard input
 to the command.  Be aware that even if the \fIsubcommand\fR is the designated
 argument to pass on standard input (\f(CW\*(C`stdin=1\*(C'\fR), the \fIsubcommand\fR may not
 contain \s-1NUL\s0 characters.
+.IP "sudo=(\fIusername\fR | #\fIuid\fR)" 4
+.IX Item "sudo=(username | #uid)"
+[3.12] Run this command as the specified user using \fBsudo\fR.  This is
+exactly equivalent to prepending \f(CW\*(C`sudo \-u \f(CIusername\f(CW \-\-\*(C'\fR to the command
+before running it.  The path to \fBsudo\fR is determined when \fBremctld\fR is
+built.
+.Sp
+The \fIuser\fR option is simpler and easier if \fBremctld\fR is running as root.
+However, it may be desirable in some configurations to run \fBremctld\fR as a
+non-root user, and \fBremctl-shell\fR (which shares the same configuration
+files) usually runs as a non-root user.  In those cases, this option can
+be used to use \fBsudo\fR to switch users before running the command.
+.Sp
+Since the argument is passed verbatim to \fBsudo\fR's \fB\-u\fR option, you can
+specify a numeric \s-1UID\s0 by prepending it with \f(CW\*(C`#\*(C'\fR.
 .IP "summary=\fIarg\fR" 4
 .IX Item "summary=arg"
 [3.2] Specifies the argument for this command that will print a usage
@@ -613,14 +628,11 @@ cleared by \fBremctld\fR before running any commands.
 .PP
 The following environment variables will be set for any commands run via
 \&\fBremctld\fR (annotated with the version at which they were added):
-.IP "\s-1REMOTE_USER\s0" 4
-.IX Item "REMOTE_USER"
-.PD 0
-.IP "\s-1REMUSER\s0" 4
-.IX Item "REMUSER"
-.PD
-[1.0 for \s-1REMUSER, 2.1\s0 for \s-1REMOTE_USER\s0] Set to the Kerberos principal of
-the authenticated client.
+.IP "\s-1REMCTL_COMMAND\s0" 4
+.IX Item "REMCTL_COMMAND"
+[2.16] The command string that caused this command to be run.  This
+variable will contain only the command, not the subcommand or any
+additional arguments (which are passed as command arguments).
 .IP "\s-1REMOTE_ADDR\s0" 4
 .IX Item "REMOTE_ADDR"
 [2.1] The \s-1IP\s0 address of the remote host.  This may be IPv4 or IPv6.
@@ -633,11 +645,19 @@ the Kerberos ticket used to authenticate to the server.
 .IX Item "REMOTE_HOST"
 [2.1] The hostname of the remote host, if it was available.  If reverse
 name resolution failed, this environment variable will not be set.
-.IP "\s-1REMCTL_COMMAND\s0" 4
-.IX Item "REMCTL_COMMAND"
-[2.16] The command string that caused this command to be run.  This
-variable will contain only the command, not the subcommand or any
-additional arguments (which are passed as command arguments).
+.Sp
+This is determined via a simple reverse \s-1DNS\s0 lookup and should be
+considered under the control of the client.  remctl commands should treat
+it with skepticism and not use it for anything other than logging
+purposes.
+.IP "\s-1REMOTE_USER\s0" 4
+.IX Item "REMOTE_USER"
+.PD 0
+.IP "\s-1REMUSER\s0" 4
+.IX Item "REMUSER"
+.PD
+[1.0 for \s-1REMUSER, 2.1\s0 for \s-1REMOTE_USER\s0] Set to the Kerberos principal of
+the authenticated client.
 .PP
 If the \fB\-k\fR flag is used, \fBremctld\fR will also set \s-1KRB5_KTNAME\s0 to the
 provided keytab path.  This is primarily for communication with the
diff --git a/docs/remctld.pod b/docs/remctld.pod
index c601043..5d7fcfa 100644
--- a/docs/remctld.pod
+++ b/docs/remctld.pod
@@ -289,6 +289,22 @@ to the command.  Be aware that even if the I<subcommand> is the designated
 argument to pass on standard input (C<stdin=1>), the I<subcommand> may not
 contain NUL characters.
 
+=item sudo=(I<username> | #I<uid>)
+
+[3.12] Run this command as the specified user using B<sudo>.  This is
+exactly equivalent to prepending C<sudo -u I<username> --> to the command
+before running it.  The path to B<sudo> is determined when B<remctld> is
+built.
+
+The I<user> option is simpler and easier if B<remctld> is running as root.
+However, it may be desirable in some configurations to run B<remctld> as a
+non-root user, and B<remctl-shell> (which shares the same configuration
+files) usually runs as a non-root user.  In those cases, this option can
+be used to use B<sudo> to switch users before running the command.
+
+Since the argument is passed verbatim to B<sudo>'s B<-u> option, you can
+specify a numeric UID by prepending it with C<#>.
+
 =item summary=I<arg>
 
 [3.2] Specifies the argument for this command that will print a usage
@@ -523,12 +539,11 @@ B<remctld> (annotated with the version at which they were added):
 
 =over 4
 
-=item REMOTE_USER
-
-=item REMUSER
+=item REMCTL_COMMAND
 
-[1.0 for REMUSER, 2.1 for REMOTE_USER] Set to the Kerberos principal of
-the authenticated client.
+[2.16] The command string that caused this command to be run.  This
+variable will contain only the command, not the subcommand or any
+additional arguments (which are passed as command arguments).
 
 =item REMOTE_ADDR
 
@@ -545,11 +560,17 @@ the Kerberos ticket used to authenticate to the server.
 [2.1] The hostname of the remote host, if it was available.  If reverse
 name resolution failed, this environment variable will not be set.
 
-=item REMCTL_COMMAND
+This is determined via a simple reverse DNS lookup and should be
+considered under the control of the client.  remctl commands should treat
+it with skepticism and not use it for anything other than logging
+purposes.
 
-[2.16] The command string that caused this command to be run.  This
-variable will contain only the command, not the subcommand or any
-additional arguments (which are passed as command arguments).
+=item REMOTE_USER
+
+=item REMUSER
+
+[1.0 for REMUSER, 2.1 for REMOTE_USER] Set to the Kerberos principal of
+the authenticated client.
 
 =back