=head1 NAME remctld - Server for remctl, a remote command execution utility =head1 SYNOPSIS remctld [B<-dFhmSv>] [B<-f> I] [B<-k> I] [B<-P> I] [B<-p> I] [B<-s> I] =head1 DESCRIPTION B 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. B is normally started using B or from B, but it may be run in stand-alone mode as a daemon using B<-m>. Either B<-s> must be given to use an alternate identity (which will require the same flag be used for B client invocations), or it must be run as root to read the host keytab file. B logs its activity using syslog (the daemon facility). The location of the configuration file may be specified with the B<-f> option. The default location is F<@sysconfdir@/remctl.conf>. For information on the format of the configuration file, see L<"CONFIGURATION FILE"> below. When the command is run, several environment variables will be set providing information about the remote connection. See L below for more information. =head1 OPTIONS =over 4 =item B<-d> Enable verbose debug logging to syslog (or to standard output if B<-S> is also given). =item B<-F> Normally when running in stand-alone mode (B<-m>), B backgrounds itself to run as a daemon, changes directory to F, and drops any controlling terminal. This flag suppresses this behavior, usually for debugging or so that B can be monitored by other processes. =item B<-f> I The configuration file for B, overriding the default path. =item B<-h> Show a brief usage message and then exit. =item B<-k> I Use I as the keytab for server credentials rather than the system default or the value of the KRB5_KTNAME environment variable. Using B<-k> just sets the KRB5_KTNAME environment variable internally in the process. =item B<-m> Enable stand-alone mode. B will listen to its configured port and fork a new child for each incoming connection. By default, when this option is used, B also changes directory to F, backgrounds itself, and closes standard input, output, and error. To not background, pass B<-F> as well. To not close standard output and error and continue using them for logging, pass B<-S> as well. To determine the port, B attempts to look up the C service in the local F file and uses the port defined there. If the C service could not be found, it uses 4373, the registered remctl port. =item B<-P> I When running in stand-alone mode (B<-m>), write the PID of B to I. This option is ignored unless B<-m> is also given. =item B<-p> I When running in stand-alone mode, Listen on port I rather than the default. This option does nothing unless used with B<-m>. =item B<-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. =item B<-s> I This option is used to specify the Kerberos service principal for B to run as, the default is the server host principal: "host/.stanford.edu" =item B<-v> Print the version of B and exit. =back =head1 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: type service executable [logmask=n[,...]] {aclfile}+ Each command consists of a type, a service, and zero or more arguments. Each configuration line defines an acceptable commands (or, if C is used as mentioned below under I, a set of commands). Blank lines and lines beginning with C<#> are ignored. Lines can be continued on the next line by ending them with a backslash (C<\>). Be aware that comments can be continued with a backslash as well. As a special case, a line like: include file will include I as if its contents were pasted verbatim into the configuration file at that point. I 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). I should be a fully qualified path. The meaning of these fields is: =over 4 =item I The type of the command being requested. Normally, related commands (such as all commands for managing a particular service) are grouped together under one type. =item I The service within the type being requested, such as C for the release function of the AFS volume backend. I can also be thought of as the sub-command. If the keyword C is used instead of a specific service, this line matches all commands with the given type and can be used to dispatch all services under that type to the same executable with the same ACLs. The first matching entry is used; one may list specific services first and then an C catch-all. B accepts commands with no service argument, only a type, such commands will only match a line in the configuration file if an C line is present for that type. (The B client will not send such commands, but they can be sent using the client library or via another implementation.) The service is always passed as the first argument to the executable program that is listed for that service unless no service was given. =item I The full path to the commmand executable to run for this type-service combination. (See examples below.) =item I 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 privileged information. For example, if the command is C, then you'd want to set logmask to C<3>, so the password argument gets logged as C<**MASKED**>. =item I The full paths of one or more access control files, each containing one Kerberos v5 principal per line, such as C. Blank lines and lines beginning with C<#> are ignored in the ACL files. As a special case, a line like: include file in an ACL file includes other ACL files and is handled identically to the include directive in configuration files. The keyword ANYUSER may be used instead of the aclfiles to allow access to all users. The user still needs to authenticate to B; 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 B authenticated user, including cross-realm users from foreign Kerberos realms. =back =head1 ENVIRONMENT The following environment variables will be set for any commands run via B: =over 4 =item REMOTE_USER =item REMUSER Set to the Kerberos principal of the authenticated client. REMUSER has always been set by B; REMOTE_USER is also set (to the same value) starting with remctl 2.1. =item 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. =item 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. =back B also used to set SCPRINCIPAL for (partial) backward compatibility with B, but stopped doing so as of remctl 2.1. If the B<-k> flag is used, B 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 B. =head1 EXAMPLES Typically B 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 F 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 C service is listed in your F file. To start B 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 C, C, and so forth will all be passed to /usr/local/bin/doaccount with the first argument being the specific subcommand, with the exception of C. That command will be passed to /usr/local/bin/dopasswd instead, but it will still get C as its first argument. The third argument to C (presumably the password) will not be logged to syslog. All commands starting with C will be passed to /usr/local/bin/printthing. =head1 CAVEATS When using Heimdal with triple-DES keys and talking to old clients that only speak version one of the remctl protocol, B 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). When running in daemon mode, B does not itself impose any limits on the number of child processes or other system resources. You may want to set resource limits with B. =head1 NOTES The remctl port number, 4373, was derived by tracing the diagonals of a QWERTY keyboard up from the letters C to the number row. =head1 SEE ALSO remctl(1), syslog(3), tcpserver(1) The current version of this program is available from its web page at L. =head1 AUTHOR Anton Ushakov is the original author. Updates and current maintenance are done by Russ Allbery . =head1 COPYRIGHT AND LICENSE Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 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. =cut