NAME
remctld - Server for remctl, a remote command execution utility
SYNOPSIS
remctld [-dFhmSv] [-f config] [-k keytab] [-P file] [-p port] [-s
service]
DESCRIPTION
remctld is the server for remctl. It accepts a connection from remctl,
receives the command to execute and the arguments, verifies
authorization of the user and executes the command, returning the
result back to the client. All connections are authenticated using
GSS-API Kerberos v5, and all transmissions are also encrypted using the
GSS-API privacy layer.
remctld is normally started using tcpserver or from inetd, but it may
be run in stand-alone mode as a daemon using -m. Either -s must be
given to use an alternate identity (which will require the same flag be
used for remctl client invocations), or it must be run as root to read
the host keytab file. remctld logs its activity using syslog (the
daemon facility).
The location of the configuration file may be specified with the -f
option. The default location is /etc/remctl/remctl.conf. For
information on the format of the configuration file, see "CONFIGURATION
FILE" below.
When the command is run, several environment variables will be set
providing information about the remote connection. See ENVIRONMENT
below for more information.
OPTIONS
-d Enable verbose debug logging to syslog (or to standard output if -S
is also given).
-F Normally when running in stand-alone mode (-m), remctld backgrounds
itself to run as a daemon, changes directory to /, and drops any
controlling terminal. This flag suppresses this behavior, usually
for debugging or so that remctld can be monitored by other
processes.
-f config
The configuration file for remctld, overriding the default path.
-h 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 remctld build.
-k keytab
Use keytab as the keytab for server credentials rather than the
system default or the value of the KRB5_KTNAME environment
variable. Using -k just sets the KRB5_KTNAME environment variable
internally in the process.
-m Enable stand-alone mode. remctld will listen to its configured
port and fork a new child for each incoming connection. By
default, when this option is used, remctld also changes directory
to /, backgrounds itself, and closes standard input, output, and
error. To not background, pass -F as well. To not close standard
output and error and continue using them for logging, pass -S as
well.
To determine the port, remctld attempts to look up the "remctl"
service in the local /etc/services file and uses the port defined
there. If the "remctl" service could not be found, it uses 4373,
the registered remctl port.
-P file
When running in stand-alone mode (-m), write the PID of remctld to
file. This option is ignored unless -m is also given.
-p port
When running in stand-alone mode, Listen on port port rather than
the default. This option does nothing unless used with -m.
-S Rather than logging to syslog, log debug and routine connection
messages to standard output and error messages to standard error.
This option is mostly useful for testing and debugging.
-s service
Specifies which principal is used as the server identity for client
authentication. The client must also use the same identity as the
server identity for authentication to succeed. By default, remctld
accepts any principal with a key in the default keytab file (which
can be changed with the -k option). This is normally the most
desirable behavior.
-v Print the version of remctld and exit.
CONFIGURATION FILE
The configuration file defines the allowed commands and specifies
access control information. The configuration file format is lines of
space- or tab-separated strings, where each line is:
command subcommand executable [option=value ...] acl [acl ...]
Each command consists of a command, a subcommand, and zero or more
arguments. Each configuration line defines an acceptable command and
subcommand (or, if "ALL" is used as mentioned below under command and
subcommand, a set of commands). The first configuration line matching
the received command is used, so list more specific entries before more
general entries.
Blank lines and lines beginning with "#" are ignored. Lines can be
continued on the next line by ending them with a backslash ("\"). Be
aware that comments can be continued with a backslash as well.
As a special case, a line like:
include file
will include file as if its contents were pasted verbatim into the
configuration file at that point. file may be a directory, in which
case all files whose names do not contain a period found in that
directory will be included (in no particular order). file should be a
fully qualified path.
The meaning of these fields is:
command
The command being issued or the special keyword "ALL". Normally,
related commands (such as all commands for managing a particular
service) are grouped together as subcommands under one command.
If the keyword "ALL" is used instead of a specific subcommand, this
line matches all commands with the given subcommand (so "ALL ALL"
matches any command) and can be used to dispatch all commands to
the same executable with the same ACLs. Since the first matching
entry is used, list entries for specific commands first (if any)
and then the "ALL" catch-all. Note that while the subcommand is
passed to the executable, the command is not, so the program run
will not be able to distinguish between different commands.
subcommand
The subcommand within the command being requested, such as
"release" for the release function of the AFS volume backend, or
one of the special keywords "ALL" or "EMPTY".
If the keyword "ALL" is used instead of a specific subcommand, this
line matches all subcommands with the given command and can be used
to dispatch all subcommands under that command to the same
executable with the same ACLs. Since the first matching entry is
used, list entries for specific services first (if any) and then
the "ALL" catch-all.
If the keyword "EMPTY" is used instead of a specific subcommand,
this line matches only commands where no subcommand was given.
The subcommand is always passed as the first argument to the
executable program that is listed for that service unless no
subcommand was given.
executable
The full path to the command executable to run for this command and
subcommand combination. (See examples below.)
option=value
An option setting that applies to this command. Supported option
settings are:
logmask=n[,...]
Limit logging of command arguments. Any argument listed in the
logmask list will have its value logged as "**MASKED**". This
is to avoid logging the arguments of commands that take private
information such as passwords. The logmask list should contain
argument numbers separated by commas, with the subcommand
considered argument 1. The command argument cannot be masked.
For example, if the command is "admin passwd username
password", then you’d want to set logmask to 3, so the password
argument gets logged as "**MASKED**". If the command is "user
passwd username old-password new-password", you’d want to set
logmask to "3,4".
stdin=(n | "last")
Specifies that the nth or last argument to the command be
passed on standard input instead of on the command line. The
value of this option must either be the number of argument to
pass on standard input (with the subcommand considered argument
1) or the special value "last", which indicates that the final
argument (no matter how many there are) be passed on standard
input.
The subcommand cannot be passed on standard input, so n must be
at least 2. If this option is set to "last" and no arguments
are given except the command and possibly the subcommand,
nothing will be passed on standard input.
This option is used primarily for passing large amounts of data
that may not fit on the command line or data that contains NUL
characters. It can also be used for arguments like passwords
that shouldn’t be exposed on the command line. Only at most
one argument may be passed on standard input to the command.
acl One or more entries of the form [method:]data, where method
specifies an access control method to be used, and data contains
parameters whose meaning depends on the method. If the method is
omitted, the data is processed as described for the "file" method.
If method is omitted, acl must either begin with "/" or must not
contain "=". Otherwise, it will be parsed as an option instead.
If there is any ambiguity, prepend the method.
Each entry is checked in order, and access is granted as soon as an
entry matches. If no entry matches, access is denied. The
following methods are supported:
file
The data is the full path of an ACL file or to a directory
containing ACL files. Directories are handled as described for
the include directive in configuration files. An ACL file
contains one entry per line, in the [method:]data form
described above. Entries are handled exactly as if they had
appeared in the configuration file except that the default
method is "princ" instead of "file". Blank lines and lines
beginning with "#" are ignored in the ACL files.
For backward compatibility, a line like:
include [<method>:]<data>
in an ACL file behaves exactly as if the "include" directive
had been omitted, except that the default method is "file".
Thus, writing:
include <path>
in an ACL file is the same as writing:
file:<path>
and is handled identically to the include directive in
configuration files.
princ
The data is the name of a Kerberos v5 principal which is to be
granted access, such as "username@EXAMPLE.ORG".
deny
This method is used to selectively deny access. The data is
parsed as a [method:]data and evaluated as described above,
with the default scheme being "princ". If it matches, access
is denied immediately without examining any further entries.
Otherwise, processing continues.
Remember that access is granted as soon as an entry matches.
For "deny" rules to be effective, they therefore must come
before any ACLs they are intended to override. Be careful when
using "deny" when including a directory of ACL files, since the
files in that directory are read in an undefined order (not in
alphabetical order by filename). It’s best to explicitly
include the file containing "deny" ACL rules first.
Note that "deny" only denies access; it never grants it. Thus,
deny alone does not grant access to anyone, and using deny on
itself as in "deny:deny:foo" neither denies nor grants access
to anyone.
gput
This method is used to grant access based on the CMU GPUT
(Global Privileged User Table -- see gput(5)). The data is
either a GPUT role name or a string of the form group[xform],
where group is a GPUT role name and xform is a GPUT transform
string. Access is granted if the user is a member of the
specified GPUT group, after applying either the optional xform
or the default transform.
This method is supported only if remctld was compiled with GPUT
support by using the "--with-gput" configure option.
pcre
This method is used to grant or deny access based on Perl-
compatible regular expressions. The data is taken to be a
Perl-compatible regular expression and matched against the user
identity. To deny access, use the "deny:pcre:regex" syntax.
This method is supported only if remctld was compiled with PCRE
support by using the "--with-pcre" configure option.
To see the list of ACL types supported by a particular build of
remctld, run "remctld -h".
The keyword ANYUSER may be used instead of the ACLs to allow access
to all users. The user still needs to authenticate to remctld;
this only affects authorization. This can be used for backend
programs that want to check ACLs themselves and will retrieve the
authenticated principal from the REMOTE_USER environment variable.
Note that ANYUSER accepts any authenticated user, including cross-
realm users from foreign Kerberos realms.
Support for ACL schemes is new in remctl 2.13. Prior versions of
remctld expected only files in the main remctld configuration file,
and only principals or lines starting with "include" in those
files, without any method: prefixes.
ENVIRONMENT
The following environment variables will be set for any commands run
via remctld:
REMOTE_USER
REMUSER
Set to the Kerberos principal of the authenticated client. REMUSER
has always been set by remctld; REMOTE_USER is also set (to the
same value) starting with remctl 2.1.
REMOTE_ADDR
The IP address of the remote host. Currently, this is always an
IPv4 address, but in the future it may be set to an IPv6 address.
This environment variable was added in remctl 2.1.
REMOTE_HOST
The hostname of the remote host, if it was available. If reverse
name resolution failed, this environment variable will not be set.
This variable was added in remctl 2.1.
REMCTL_COMMAND
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). This
variable was added in remctl 2.16.
remctld also used to set SCPRINCIPAL for (partial) backward
compatibility with sysctld, but stopped doing so as of remctl 2.1.
If the -k flag is used, remctld will also set KRB5_KTNAME to the
provided keytab path. This is primarily for communication with the
GSS-API library, but this setting will also be inherited by any
commands run by remctld.
EXAMPLES
Typically remctld is to be started as follows, where "hostname" is the
machine where remctld will run, and 4373 is the port:
tcpserver hostname 4373 remctld
The equivalent line for /etc/inetd.conf is:
4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
or:
remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
if the "remctl" service is listed in your /etc/services file.
To start remctld in stand-alone mode instead, run:
remctld -m
Example configuration file:
# Comments can be used like this.
accounts create /usr/local/bin/doaccount /etc/acl/group1 \
/etc/acl/group2
accounts delete /usr/local/bin/doaccount /etc/acl/group3
accounts view /usr/local/bin/doaccount ANYUSER
accounts passwd /usr/local/bin/dopasswd logmask=3 /etc/acl/group1
printing ALL /usr/local/bin/printthing /etc/acl/group2
The commands "accounts create", "accounts delete", and so forth will
all be passed to /usr/local/bin/doaccount with the first argument being
the specific subcommand, with the exception of "accounts passwd". That
command will be passed to /usr/local/bin/dopasswd instead, but it will
still get "passwd" as its first argument. The third argument to
"accounts passwd" (presumably the password) will not be logged to
syslog. All commands starting with "printing" will be passed to
/usr/local/bin/printthing.
Example ACL file using the scheme support new in remctl 2.13:
# This is a comment.
deny:baduser@EXAMPLE.ORG
file:/etc/remctl/acl/admins
principal:service/admin@EXAMPLE.ORG
service/other@EXAMPLE.ORG
This ACL file will reject "baduser@EXAMPLE.ORG" even if that user would
have been allowed by one of the other ACL rules. It will then grant
access according to the ACL entries in /etc/remctl/acl/admins and the
specific principals "service/admin@EXAMPLE.ORG" and
"service/other@EXAMPLE.ORG". The last line takes advantage of the
default ACL method of "principal" when processing an ACL file.
CAVEATS
When using Heimdal with triple-DES keys and talking to old clients that
only speak version one of the remctl protocol, remctld may have
problems with MIC verification. This doesn’t affect new clients and
servers since the version two protocol doesn’t use MICs. If you are
using Heimdal and run into MIC verification problems, see the
COMPATIBILITY section of gssapi(3).
remctld does not itself impose any limits on the number of child
processes or other system resources. You may want to set resource
limits in your inetd server or with ulimit when running it as a
standalone daemon or under tcpserver.
Command arguments may not contain NUL characters and must be shorter
than the operating system limit on the length of a command line since
they’re passed to the command as command-line arguments. The exception
is an argument passed via standard input using the "stdin=" option in
the configuration file. At most one argument may be passed that way.
NOTES
The remctl port number, 4373, was derived by tracing the diagonals of a
QWERTY keyboard up from the letters "remc" to the number row.
SEE ALSO
remctl(1), syslog(3), tcpserver(1)
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/remctl/>.
AUTHOR
Anton Ushakov <antonu@stanford.edu> is the original author. Updates
and current maintenance are done by Russ Allbery <rra@stanford.edu>.
COPYRIGHT AND LICENSE
Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Board of
Trustees, Leland Stanford Jr. University. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stanford University not
be used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission. Stanford
University makes no representations about the suitability of this
software for any purpose. It is provided "as is" without express or
implied warranty.
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.