table of contents
other versions
- wheezy 3.2-4
- wheezy-backports 3.9-1~bpo70+1
- jessie 3.9-1+b2
- testing 3.13-1+b1
- unstable 3.13-1+b1
REMCTLD(8) | remctl | REMCTLD(8) |
NAME¶
remctld - Server for remctl, a remote command execution utilitySYNOPSIS¶
remctld [ -dFhmSv] [-b bind-address [-b bind-address ...]][ -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¶
- -b bind-address
- When running as a standalone server, bind to the specified local address rather than listening on all interfaces. This option may be given multiple times to bind to multiple addresses. bind-address must be an IP address (either IPv4 or IPv6), not a hostname. Only makes sense in combination with -m.
- -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.
- -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 filewill 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.
- 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".
- 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:
- help=arg
- Specifies the argument for this command that will print
help for a particular subcommand to standard output.
- 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.
- 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.
- summary=arg
- Specifies the argument for this command that will print a
usage summary to standard output.
- user=(username | uid)
- Run this command as the specified user, which can be given as either a username or as a UID. Even if given as a UID, the user must be found in the user database (searched via getpwuid(3)). remctld will run the command as the specified user, including that user's primary and supplemental groups.
- 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.
- 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.
include [<method>:]<data>
include <path>
file:<path>
- 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.
- 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.
- 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.
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.
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 remctldThe equivalent line for /etc/inetd.conf is:
4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctldor:
remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctldif the "remctl" service is listed in your /etc/services file. To start remctld in stand-alone mode instead, run:
remctld -mExample 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/group2The 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.ORGThis 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, 2010, 2011, 2012 The Board of Trustees of the Leland Stanford Junior University 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.2012-06-19 | 3.2 |