.\" Automatically generated by Pod::Man 2.08 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "REMCTLD 8"
.TH REMCTLD 8 "2008-03-30" "2.12" "System Daemons"
.SH "NAME"
remctld \- Server for remctl, a remote command execution utility
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
remctld [\fB\-dFhmSv\fR] [\fB\-f\fR \fIconfig\fR] [\fB\-k\fR \fIkeytab\fR] [\fB\-P\fR \fIfile\fR]
[\fB\-p\fR \fIport\fR] [\fB\-s\fR \fIservice\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBremctld\fR 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.
.PP
\&\fBremctld\fR is normally started using \fBtcpserver\fR or from \fBinetd\fR, but it
may be run in stand-alone mode as a daemon using \fB\-m\fR.  Either \fB\-s\fR must
be given to use an alternate identity (which will require the same flag be
used for \fBremctl\fR client invocations), or it must be run as root to read
the host keytab file.  \fBremctld\fR logs its activity using syslog (the
daemon facility).
.PP
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.  For
information on the format of the configuration file, see \*(L"\s-1CONFIGURATION\s0
\&\s-1FILE\s0\*(R" below.
.PP
When the command is run, several environment variables will be set
providing information about the remote connection.  See \s-1ENVIRONMENT\s0
below for more information.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-d\fR" 4
.IX Item "-d"
Enable verbose debug logging to syslog (or to standard output if \fB\-S\fR is
also given).
.IP "\fB\-F\fR" 4
.IX Item "-F"
Normally when running in stand-alone mode (\fB\-m\fR), \fBremctld\fR backgrounds
itself to run as a daemon, changes directory to \fI/\fR, and drops any
controlling terminal.  This flag suppresses this behavior, usually for
debugging or so that \fBremctld\fR can be monitored by other processes.
.IP "\fB\-f\fR \fIconfig\fR" 4
.IX Item "-f config"
The configuration file for \fBremctld\fR, overriding the default path.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Show a brief usage message and then exit.
.IP "\fB\-k\fR \fIkeytab\fR" 4
.IX Item "-k keytab"
Use \fIkeytab\fR as the keytab for server credentials rather than the system
default or the value of the \s-1KRB5_KTNAME\s0 environment variable.  Using \fB\-k\fR
just sets the \s-1KRB5_KTNAME\s0 environment variable internally in the process.
.IP "\fB\-m\fR" 4
.IX Item "-m"
Enable stand-alone mode.  \fBremctld\fR will listen to its configured port
and fork a new child for each incoming connection.  By default, when this
option is used, \fBremctld\fR also changes directory to \fI/\fR, backgrounds
itself, and closes standard input, output, and error.  To not background,
pass \fB\-F\fR as well.  To not close standard output and error and continue
using them for logging, pass \fB\-S\fR as well.
.Sp
To determine the port, \fBremctld\fR attempts to look up the \f(CW\*(C`remctl\*(C'\fR
service in the local \fI/etc/services\fR file and uses the port defined
there.  If the \f(CW\*(C`remctl\*(C'\fR service could not be found, it uses 4373, the
registered remctl port.
.IP "\fB\-P\fR \fIfile\fR" 4
.IX Item "-P file"
When running in stand-alone mode (\fB\-m\fR), write the \s-1PID\s0 of \fBremctld\fR to
\&\fIfile\fR.  This option is ignored unless \fB\-m\fR is also given.
.IP "\fB\-p\fR \fIport\fR" 4
.IX Item "-p port"
When running in stand-alone mode, Listen on port \fIport\fR rather than the
default.  This option does nothing unless used with \fB\-m\fR.
.IP "\fB\-S\fR" 4
.IX Item "-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.
.IP "\fB\-s\fR \fIservice\fR" 4
.IX Item "-s service"
This option is used to specify the Kerberos service principal for
\&\fBremctld\fR to run as, the default is the server host principal:
\&\*(L"host/<machinename>.stanford.edu\*(R"
.IP "\fB\-v\fR" 4
.IX Item "-v"
Print the version of \fBremctld\fR and exit.
.SH "CONFIGURATION FILE"
.IX Header "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:
.PP
.Vb 1
\&    type service executable [logmask=n[,...]] {aclfile}+
.Ve
.PP
Each command consists of a type, a service, and zero or more arguments.
Each configuration line defines an acceptable commands (or, if \f(CW\*(C`ALL\*(C'\fR is
used as mentioned below under \fIservice\fR, a set of commands).
.PP
Blank lines and lines beginning with \f(CW\*(C`#\*(C'\fR are ignored.  Lines can be
continued on the next line by ending them with a backslash (\f(CW\*(C`\e\*(C'\fR).  Be
aware that comments can be continued with a backslash as well.
.PP
As a special case, a line like:
.PP
.Vb 1
\&    include file
.Ve
.PP
will include \fIfile\fR as if its contents were pasted verbatim into the
configuration file at that point.  \fIfile\fR 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).  \fIfile\fR should be a fully
qualified path.
.PP
The meaning of these fields is:
.IP "\fItype\fR" 4
.IX Item "type"
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.
.IP "\fIservice\fR" 4
.IX Item "service"
The service within the type being requested, such as \f(CW\*(C`release\*(C'\fR for the
release function of the \s-1AFS\s0 volume backend.  \fIservice\fR can also be
thought of as the sub\-command.  If the keyword \f(CW\*(C`ALL\*(C'\fR 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 \f(CW\*(C`ALL\*(C'\fR catch\-all.
.Sp
\&\fBremctld\fR accepts commands with no service argument, only a type, such
commands will only match a line in the configuration file if an \f(CW\*(C`ALL\*(C'\fR
line is present for that type.  (The \fBremctl\fR client will not send such
commands, but they can be sent using the client library or via another
implementation.)
.Sp
The service is always passed as the first argument to the executable
program that is listed for that service unless no service was given.
.IP "\fIexecutable\fR" 4
.IX Item "executable"
The full path to the commmand executable to run for this type-service 
combination.  (See examples below.)
.IP "\fIlogmask=n[,...]\fR" 4
.IX Item "logmask=n[,...]"
Limit logging of command arguments.  Any argument listed in the logmask
list will have its value logged as \*(L"**MASKED**\*(R".  This is to avoid logging
the arguments of commands that take privileged information.
.Sp
For example, if the command is \f(CW\*(C`admin passwd {username} {passwd}\*(C'\fR, then
you'd want to set logmask to \f(CW3\fR, so the password argument gets logged as
\&\f(CW\*(C`**MASKED**\*(C'\fR.
.IP "\fIaclfile\fR" 4
.IX Item "aclfile"
The full paths of one or more access control files, each containing one 
Kerberos v5 principal per line, such as \f(CW\*(C`username@stanford.edu\*(C'\fR.  Blank
lines and lines beginning with \f(CW\*(C`#\*(C'\fR are ignored in the \s-1ACL\s0 files.  As a
special case, a line like:
.Sp
.Vb 1
\&    include file
.Ve
.Sp
in an \s-1ACL\s0 file includes other \s-1ACL\s0 files and is handled identically to the
include directive in configuration files.
.Sp
The keyword \s-1ANYUSER\s0 may be used instead of the aclfiles to allow access to
all users.  The user still needs to authenticate to \fBremctld\fR; 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 \s-1REMOTE_USER\s0 environment variable.  Note that \s-1ANYUSER\s0 accepts \fBany\fR
authenticated user, including cross-realm users from foreign Kerberos
realms.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
The following environment variables will be set for any commands run via
\&\fBremctld\fR:
.IP "\s-1REMOTE_USER\s0" 4
.IX Item "REMOTE_USER"
.PD 0
.IP "\s-1REMUSER\s0" 4
.IX Item "REMUSER"
.PD
Set to the Kerberos principal of the authenticated client.  \s-1REMUSER\s0 has
always been set by \fBremctld\fR; \s-1REMOTE_USER\s0 is also set (to the same value)
starting with remctl 2.1.
.IP "\s-1REMOTE_ADDR\s0" 4
.IX Item "REMOTE_ADDR"
The \s-1IP\s0 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.
.IP "\s-1REMOTE_HOST\s0" 4
.IX 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.
.PP
\&\fBremctld\fR also used to set \s-1SCPRINCIPAL\s0 for (partial) backward
compatibility with \fBsysctld\fR, but stopped doing so as of remctl 2.1.
.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
GSS-API library, but this setting will also be inherited by any commands
run by \fBremctld\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Typically \fBremctld\fR is to be started as follows, where \*(L"hostname\*(R" is the
machine where remctld will run, and 4373 is the port:
.PP
.Vb 1
\&    tcpserver hostname 4373 remctld
.Ve
.PP
The equivalent line for \fI/etc/inetd.conf\fR is:
.PP
.Vb 1
\&    4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
.Ve
.PP
or:
.PP
.Vb 1
\&    remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
.Ve
.PP
if the \f(CW\*(C`remctl\*(C'\fR service is listed in your \fI/etc/services\fR file.
.PP
To start \fBremctld\fR in stand-alone mode instead, run:
.PP
.Vb 1
\&    remctld \-m
.Ve
.PP
Example configuration file:
.PP
.Vb 7
\& # Comments can be used like this.
\& accounts create /usr/local/bin/doaccount  /etc/acl/group1 \e
\&     /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
.Ve
.PP
The commands \f(CW\*(C`accounts create\*(C'\fR, \f(CW\*(C`accounts delete\*(C'\fR, and so forth will all
be passed to /usr/local/bin/doaccount with the first argument being the
specific subcommand, with the exception of \f(CW\*(C`accounts passwd\*(C'\fR.  That
command will be passed to /usr/local/bin/dopasswd instead, but it will
still get \f(CW\*(C`passwd\*(C'\fR as its first argument.  The third argument to
\&\f(CW\*(C`accounts passwd\*(C'\fR (presumably the password) will not be logged to syslog.
All commands starting with \f(CW\*(C`printing\*(C'\fR will be passed to
/usr/local/bin/printthing.
.SH "CAVEATS"
.IX Header "CAVEATS"
When using Heimdal with triple-DES keys and talking to old clients that
only speak version one of the remctl protocol, \fBremctld\fR may have
problems with \s-1MIC\s0 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 \s-1MIC\s0 verification problems, see the \s-1COMPATIBILITY\s0
section of \fIgssapi\fR\|(3).
.PP
When running in daemon mode, \fBremctld\fR does not itself impose any limits
on the number of child processes or other system resources.  You may want
to set resource limits with \fBulimit\fR.
.SH "NOTES"
.IX Header "NOTES"
The remctl port number, 4373, was derived by tracing the diagonals of a
\&\s-1QWERTY\s0 keyboard up from the letters \f(CW\*(C`remc\*(C'\fR to the number row.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIremctl\fR\|(1), \fIsyslog\fR\|(3), \fItcpserver\fR\|(1)
.PP
The current version of this program is available from its web page at
<http://www.eyrie.org/~eagle/software/remctl/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Anton Ushakov <antonu@stanford.edu> is the original author.  Updates and
current maintenance are done by Russ Allbery <rra@stanford.edu>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2002, 2003, 2004, 2005, 2006, 2007, 2008 Board of Trustees,
Leland Stanford Jr. University.  All rights reserved.
.PP
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 \*(L"as is\*(R" without express or implied warranty.
.PP
\&\s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1AND\s0 \s-1WITHOUT\s0 \s-1ANY\s0 \s-1EXPRESS\s0 \s-1OR\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0, \s-1INCLUDING\s0, \s-1WITHOUT\s0 \s-1LIMITATION\s0, \s-1THE\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0
\&\s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.
