.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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 >0, 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 "REMCTLD 8" .TH REMCTLD 8 "2022-05-09" "3.18" "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" remctld \- Server for remctl, a remote command execution utility .SH "SYNOPSIS" .IX Header "SYNOPSIS" remctld [\fB\-dFhmSvZ\fR] [\fB\-b\fR \fIbind-address\fR [\fB\-b\fR \fIbind-address\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 Kerberos GSS-API Kerberos, 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/etc/remctl/remctl.conf\fR. For information on the format of the configuration file, see \*(L"\s-1CONFIGURATION FILE\*(R"\s0 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. .PP Command-line and configuration options and \s-1ACL\s0 methods are annotated below with the version at which they were added. For version information for more general features, see \s-1COMPATIBILITY\s0 below. .SH "OPTIONS" .IX Header "OPTIONS" The start of each option description is annotated with the version of \&\fBremctld\fR in which that option was added with its current meaning. .IP "\fB\-b\fR \fIbind-address\fR" 4 .IX Item "-b bind-address" [2.17] 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. \fIbind-address\fR must be an \&\s-1IP\s0 address (either IPv4 or IPv6), not a hostname. Only makes sense in combination with \fB\-m\fR. .Sp This option is ignored if \fBremctld\fR is passed already open sockets via the systemd socket activation protocol. In that case, the bind addresses of the sockets should be controlled via the systemd configuration. .IP "\fB\-d\fR" 4 .IX Item "-d" [1.10] 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" [2.8] 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" [1.0] The configuration file for \fBremctld\fR, overriding the default path. .IP "\fB\-h\fR" 4 .IX Item "-h" [1.10] 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 \fBremctld\fR build. .IP "\fB\-k\fR \fIkeytab\fR" 4 .IX Item "-k keytab" [2.8] 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" [2.8] 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. .Sp When running in stand-alone mode, send the \s-1SIGHUP\s0 signal to \fBremctld\fR to ask it to re-read its configuration file and \s-1SIGTERM\s0 to ask it to exit. .IP "\fB\-P\fR \fIfile\fR" 4 .IX Item "-P file" [2.0] 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" [1.0] 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. .Sp This option is ignored if \fBremctld\fR is passed already open sockets via the systemd socket activation protocol. In that case, the listening port should be controlled via the systemd configuration. .IP "\fB\-S\fR" 4 .IX Item "-S" [2.3] 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" [1.0] 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, \fBremctld\fR accepts any principal with a key in the default keytab file (which can be changed with the \fB\-k\fR option). This is normally the most desirable behavior. .IP "\fB\-v\fR" 4 .IX Item "-v" [1.10] Print the version of \fBremctld\fR and exit. .IP "\fB\-Z\fR" 4 .IX Item "-Z" [3.7] When \fBremctld\fR is running in stand-alone mode, after it has set up its network socket and is ready to answer requests, raise \s-1SIGSTOP.\s0 This signals to upstart, when using \f(CW\*(C`expect stop\*(C'\fR, that the daemon is ready to accept connections, and upstart will raise \s-1SIGCONT\s0 to allow \fBremctld\fR to continue. This option is probably only useful when using upstart as the init system. Only makes sense in combination with \fB\-m\fR. .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 \& command subcommand executable [option=value ...] acl [acl ...] .Ve .PP Each command consists of a command, a subcommand, and zero or more arguments. Each configuration line defines an acceptable command and subcommand (or, if \f(CW\*(C`ALL\*(C'\fR is used as mentioned below under \fIcommand\fR and \&\fIsubcommand\fR, a set of commands). The first configuration line matching the received command is used, so list more specific entries before more general entries. .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 configuration file is loaded when \fBremctld\fR starts and is normally not re-read. To trigger a re-read of the configuration file when \&\fBremctld\fR is running in stand-alone mode, send the \s-1SIGHUP\s0 signal to the \&\fBremctld\fR process. .PP The meaning of the fields on each configuration line are: .IP "\fIcommand\fR" 4 .IX Item "command" The command being issued or the special keyword \f(CW\*(C`ALL\*(C'\fR. Normally, related commands (such as all commands for managing a particular service) are grouped together as subcommands under one command. .Sp If the keyword \f(CW\*(C`ALL\*(C'\fR is used instead of a specific subcommand, this line matches all commands with the given subcommand (so \f(CW\*(C`ALL ALL\*(C'\fR 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 \f(CW\*(C`ALL\*(C'\fR catch-all. .Sp Note that while the subcommand is passed to the executable as a command-line option, the command is not. The command is available to the executable in the environment variable \s-1REMCTL_COMMAND\s0 (see \s-1ENVIRONMENT\s0 below). .Sp The command \f(CW\*(C`help\*(C'\fR is handled specially if no such command is defined in the configuration file. See below under the \f(CW\*(C`help\*(C'\fR and \f(CW\*(C`summary\*(C'\fR options. .IP "\fIsubcommand\fR" 4 .IX Item "subcommand" The subcommand within the command being requested, such as \f(CW\*(C`release\*(C'\fR for the release function of the \s-1AFS\s0 volume backend, or one of the special keywords \f(CW\*(C`ALL\*(C'\fR or \f(CW\*(C`EMPTY\*(C'\fR. .Sp If the keyword \f(CW\*(C`ALL\*(C'\fR 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 \f(CW\*(C`ALL\*(C'\fR catch-all. .Sp If the keyword \f(CW\*(C`EMPTY\*(C'\fR is used instead of a specific subcommand, this line matches only commands where no subcommand was given. .Sp The subcommand is always passed as the first argument to the executable program that is listed for that service unless no subcommand was given. .IP "\fIexecutable\fR" 4 .IX Item "executable" The full path to the command executable to run for this command and subcommand combination. (See examples below.) .IP "\fIoption\fR=\fIvalue\fR" 4 .IX Item "option=value" An option setting that applies to this command. Supported option settings, annotated with the version at which that option was added in its current form, are: .RS 4 .IP "help=\fIarg\fR" 4 .IX Item "help=arg" [3.2] Specifies the argument for this command that will print help for a particular subcommand to standard output. .Sp If remctld receives the command \f(CW\*(C`help\*(C'\fR with one or two arguments, and no \&\f(CW\*(C`help\*(C'\fR command is defined in the configuration file, the server will take the command arguments as a command and subcommand. It will then look through the configuration for a configuration line matching that command and subcommand with a \f(CW\*(C`help\*(C'\fR option set. If one is found and the user is authorized to run that command, the server will run the specified \&\fIexecutable\fR with the argument \fIarg\fR and second and optional third arguments taken from the arguments to the \f(CW\*(C`help\*(C'\fR command, sending the output back to the user. .Sp This permits a standard interface to get additional help for a particular remctl command. Also see the \f(CW\*(C`summary\*(C'\fR option. .IP "logmask=\fIn\fR[,...]" 4 .IX Item "logmask=n[,...]" [1.4] 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 private information such as passwords. The logmask list should contain argument numbers separated by commas, with the \fIsubcommand\fR considered argument 1. The \fIcommand\fR argument cannot be masked. .Sp For example, if the command is \f(CW\*(C`admin passwd \f(CIusername\f(CW \f(CIpassword\f(CW\*(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. If the command is \f(CW\*(C`user passwd \f(CIusername\f(CW \&\f(CIold\-password\f(CW \f(CInew\-password\f(CW\*(C'\fR, you'd want to set logmask to \f(CW\*(C`3,4\*(C'\fR. .ie n .IP "stdin=(\fIn\fR | ""last"")" 4 .el .IP "stdin=(\fIn\fR | \f(CWlast\fR)" 4 .IX Item "stdin=(n | last)" [2.14] Specifies that the \fIn\fRth 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 \fIsubcommand\fR considered argument 1) or the special value \&\f(CW\*(C`last\*(C'\fR, which indicates that the final argument (no matter how many there are) be passed on standard input. .Sp The \fIcommand\fR cannot be passed on standard input, so \fIn\fR must be at least \f(CW1\fR. If this option is set to \f(CW\*(C`last\*(C'\fR and no arguments are given except the \fIcommand\fR and possibly the \fIsubcommand\fR, nothing will be passed on standard input. .Sp This option is used primarily for passing large amounts of data that may not fit on the command line or data that contains \s-1NUL\s0 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. 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.13] Specifies the argument for this command that will print a usage summary to standard output. .Sp If remctld receives the command \f(CW\*(C`help\*(C'\fR with no arguments, and no \f(CW\*(C`help\*(C'\fR command is defined in the configuration file, the server will look through the configuration for any command with a \f(CW\*(C`summary\*(C'\fR option set. If this option is set, and the user is authorized to run the command, the server will run the specified \fIexecutable\fR with the argument \fIarg\fR, sending the output back to the user. It will do this for every command in the configuration that meets the above criteria. .Sp This allows display of a summary of available commands to the user based on which commands that user is authorized to run. It's a lightweight form of service discovery. Also see the \f(CW\*(C`help\*(C'\fR option. .IP "user=(\fIusername\fR | \fIuid\fR)" 4 .IX Item "user=(username | uid)" [3.1] Run this command as the specified user, which can be given as either a username or as a \s-1UID.\s0 Even if given as a \s-1UID,\s0 the user must be found in the user database (searched via \fBgetpwuid\fR\|(3)). \fBremctld\fR will run the command as the specified user, including that user's primary and supplemental groups. .RE .RS 4 .RE .IP "\fIacl\fR" 4 .IX Item "acl" One or more entries of the form [\fImethod\fR:]\fIdata\fR, where \fImethod\fR specifies an access control method to be used, and \fIdata\fR contains parameters whose meaning depends on the method. If the method is omitted, the data is processed as described for the \f(CW\*(C`file\*(C'\fR method. .Sp If \fImethod\fR is omitted, \fIacl\fR must either begin with \f(CW\*(C`/\*(C'\fR or must not contain \f(CW\*(C`=\*(C'\fR. Otherwise, it will be parsed as an option instead. If there is any ambiguity, prepend the \fImethod\fR. .Sp As a special exception for backward compatibility, the \s-1ACL\s0 \f(CW\*(C`ANYUSER\*(C'\fR (case-sensitive) is treated as equivalent to \f(CW\*(C`anyuser:auth\*(C'\fR. .Sp 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 may supported; however, be aware that the availability of several \s-1ACL\s0 types depends on whether \fBremctld\fR was built with that support. Each \s-1ACL\s0 type is annotated with the version in which it was added. .RS 4 .IP "anyuser" 4 .IX Item "anyuser" [3.10] Permit access to any user. This comes in two forms: .RS 4 .IP "anyuser:auth" 4 .IX Item "anyuser:auth" Permit any authenticated user. This means not only the local Kerberos realm but also any realm with which there is a cross-realm trust relationship. .IP "anyuser:anonymous" 4 .IX Item "anyuser:anonymous" Permit entirely anonymous users. This means no authentication whatsoever is required to run the command. Any client with network access to the server can run the command (using anonymous \s-1PKINIT\s0), assuming that anonymous service tickets are enabled for the local Kerberos realm. .RE .RS 4 .Sp For backwards compatibility, the \s-1ACL\s0 \f(CW\*(C`ANYUSER\*(C'\fR is treated as identical to \&\f(CW\*(C`anyuser:auth\*(C'\fR. This was the only supported any-user \s-1ACL\s0 syntax prior to remctl 3.10. .RE .IP "file" 4 .IX Item "file" [2.13] The data is the full path of an \s-1ACL\s0 file or to a directory containing \s-1ACL\s0 files. Directories are handled as described for the include directive in configuration files. An \s-1ACL\s0 file contains one entry per line, in the [\fImethod\fR:]\fIdata\fR form described above. Entries are handled exactly as if they had appeared in the configuration file except that the default method is \f(CW\*(C`princ\*(C'\fR instead of \f(CW\*(C`file\*(C'\fR. Blank lines and lines beginning with \f(CW\*(C`#\*(C'\fR are ignored in the \s-1ACL\s0 files. .Sp For backward compatibility, a line like: .Sp .Vb 1 \& include [:] .Ve .Sp in an \s-1ACL\s0 file behaves exactly as if the \f(CW\*(C`include\*(C'\fR directive had been omitted, except that the default method is \f(CW\*(C`file\*(C'\fR. Thus, writing: .Sp .Vb 1 \& include .Ve .Sp in an \s-1ACL\s0 file is the same as writing: .Sp .Vb 1 \& file: .Ve .Sp and is handled identically to the include directive in configuration files. .IP "princ" 4 .IX Item "princ" [2.13] The data is the name of a Kerberos v5 principal which is to be granted access, such as \f(CW\*(C`username@EXAMPLE.ORG\*(C'\fR. .IP "deny" 4 .IX Item "deny" [2.13] This method is used to selectively deny access. The data is parsed as a [\fImethod\fR:]\fIdata\fR and evaluated as described above, with the default scheme being \f(CW\*(C`princ\*(C'\fR. If it matches, access is denied immediately without examining any further entries. Otherwise, processing continues. .Sp Remember that access is granted as soon as an entry matches. For \f(CW\*(C`deny\*(C'\fR rules to be effective, they therefore must come before any ACLs they are intended to override. Be careful when using \f(CW\*(C`deny\*(C'\fR when including a directory of \s-1ACL\s0 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 \f(CW\*(C`deny\*(C'\fR \s-1ACL\s0 rules first. .Sp Note that \f(CW\*(C`deny\*(C'\fR only denies access; it never grants it. Thus, deny alone does not grant access to anyone, and using deny on itself as in \&\f(CW\*(C`deny:deny:foo\*(C'\fR neither denies nor grants access to anyone. .IP "gput" 4 .IX Item "gput" [2.13] This method is used to grant access based on the \s-1CMU GPUT\s0 (Global Privileged User Table \*(-- see \fBgput\fR\|(5)). The data is either a \s-1GPUT\s0 role name or a string of the form \fIgroup\fR[\fIxform\fR], where \fIgroup\fR is a \s-1GPUT\s0 role name and \fIxform\fR is a \s-1GPUT\s0 transform string. Access is granted if the user is a member of the specified \s-1GPUT\s0 group, after applying either the optional \fIxform\fR or the default transform. .Sp This method is supported only if \fBremctld\fR was compiled with \s-1GPUT\s0 support by using the \f(CW\*(C`\-\-with\-gput\*(C'\fR configure option. .IP "localgroup" 4 .IX Item "localgroup" [3.9] This method is used to grant or deny access based on membership in local \s-1UNIX\s0 groups. The data is taken to be a name of a local system group. The user principal is converted to a local user name with \fBkrb5_aname_to_localname\fR\|(3) and then compared to the members of the given group. .Sp For example, to allow access to the members of group \f(CW\*(C`goodguys\*(C'\fR, use an \&\s-1ACL\s0 of \f(CW\*(C`localgroup:goodguys\*(C'\fR syntax. To deny access to the members of group \f(CW\*(C`badguys\*(C'\fR, use \f(CW\*(C`deny:localgroup:badguys\*(C'\fR. .Sp \&\fBkrb5_aname_to_localname()\fR follows local configuration rules to determine how to convert Kerberos principal to local users. If the realm of the principal is not in a local realm and is not otherwise covered by one of those rules, the principal will be unchanged, which will almost certainly mean that it will not be a member of any local group and access will be denied. .Sp This method is supported only if \fBremctld\fR was built with Kerberos support and the \fBgetgrnam_r\fR\|(3) library function was supported by the C library when it was built. .IP "pcre" 4 .IX Item "pcre" [2.16] 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 \f(CW\*(C`deny:pcre:\f(CIregex\f(CW\*(C'\fR syntax. .Sp The regular expression is not automatically anchored, so be careful to anchor it at the start and end (with \f(CW\*(C`\eA\*(C'\fR and \f(CW\*(C`\ez\*(C'\fR) to ensure that the entire principal name is matched, unless you intend to allow partial matches. .Sp This method is supported only if \fBremctld\fR was compiled with \s-1PCRE\s0 support (either \s-1PCRE2\s0 or \s-1PCRE1\s0). .IP "regex" 4 .IX Item "regex" [2.16] This method is used to grant or deny access based on \s-1POSIX\s0 extended regular expressions. The data is taken to be a \s-1POSIX\s0 extended regular expression (like those used by \fBegrep\fR) and matched against the user identity. To deny access, use the \f(CW\*(C`deny:regex:\f(CIregex\f(CW\*(C'\fR syntax. .Sp The regular expression is not automatically anchored, so be careful to anchor it at the start and end (with \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR) to ensure that the entire principal name is matched, unless you intend to allow partial matches. .Sp This method is supported only if a library for POSIX-compatible regular expressions was found when \fBremctld\fR was built. .RE .RS 4 .Sp To see the list of \s-1ACL\s0 types supported by a particular build of \&\fBremctld\fR, run \f(CW\*(C`remctld \-h\*(C'\fR. .Sp The keyword \s-1ANYUSER\s0 may be used instead of the ACLs 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. .RE .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" \&\fBremctld\fR itself uses the following environment variables when run in stand-alone mode (\fB\-m\fR): .IP "\s-1LISTEN_FDS\s0" 4 .IX Item "LISTEN_FDS" .PD 0 .IP "\s-1LISTEN_PID\s0" 4 .IX Item "LISTEN_PID" .PD If these environment variables are set, \fBremctld\fR will expect to be provided its listening sockets via the systemd socket activation protocol and will not attempt to bind its own sockets. For more details on the protocol, see \fBdaemon\fR\|(7) and \fBsd_listen_fds\fR\|(3). .IP "\s-1NOTIFY_SOCKET\s0" 4 .IX Item "NOTIFY_SOCKET" If this environment variable is set, \fBremctld\fR will notify the socket named in this variable when it is ready to accept incoming packets using the systemd status notification protocol. For more details, see \&\fBdaemon\fR\|(7) and \fBsd_notify\fR\|(3). .Sp Note that using socket activation is recommended when running under systemd in stand-alone mode, and status notification is not necessary or useful when using socket activation. .PP When running in stand-alone mode, these environment variables will be 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-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. .IP "\s-1REMOTE_EXPIRES\s0" 4 .IX Item "REMOTE_EXPIRES" [3.10] The time (in seconds since \s-1UNIX\s0 epoch) when the authenticated remote session will expire. This will normally be the expiration time of the Kerberos ticket used to authenticate to the server. .IP "\s-1REMOTE_HOST\s0" 4 .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. .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 GSS-API library, but this setting will also be inherited by any commands run by \fBremctld\fR. .SH "EXAMPLES" .IX Header "EXAMPLES" \&\fBremctld\fR is normally started in one of two ways: either as a stand-alone daemon, or via some network management service (for example, systemd or inetd) that handles listening for incoming connections and forking \&\fBremctld\fR as needed. .PP To start \fBremctld\fR in stand-alone mode instead, run: .PP .Vb 1 \& remctld \-m .Ve .PP To start \fBremctld\fR in stand-alone mode in the foreground, use: .PP .Vb 1 \& remctld \-F \-m .Ve .PP This is a typical invocation with systemd using socket activation. For upstart (with \f(CW\*(C`expect stop\*(C'\fR), use: .PP .Vb 1 \& remctld \-F \-m \-Z .Ve .PP To start \fBremctld\fR via inetd, add this line to \fI/etc/inetd.conf\fR: .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 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. .PP Example \s-1ACL\s0 file: .PP .Vb 5 \& # This is a comment. \& deny:baduser@EXAMPLE.ORG \& file:/etc/remctl/acl/admins \& principal:service/admin@EXAMPLE.ORG \& service/other@EXAMPLE.ORG .Ve .PP This \s-1ACL\s0 file will reject \f(CW\*(C`baduser@EXAMPLE.ORG\*(C'\fR even if that user would have been allowed by one of the other \s-1ACL\s0 rules. It will then grant access according to the \s-1ACL\s0 entries in \fI/etc/remctl/acl/admins\fR and the specific principals \f(CW\*(C`service/admin@EXAMPLE.ORG\*(C'\fR and \&\f(CW\*(C`service/other@EXAMPLE.ORG\*(C'\fR. The last line takes advantage of the default \s-1ACL\s0 method of \f(CW\*(C`principal\*(C'\fR when processing an \s-1ACL\s0 file. .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" The version at which various command-line and configuration options and \&\s-1ACL\s0 methods were added to \fBremctld\fR are noted in their descriptions. Below is the version information for more general features, in reverse order of when the feature was added. .PP Support for the systemd readiness protocol and socket activation, including honoring the environment variables \s-1LISTEN_FDS, LISTEN_PID,\s0 and \&\s-1NOTIFY_SOCKET,\s0 was added in version 3.7. .PP Special handling of the \f(CW\*(C`help\*(C'\fR and \f(CW\*(C`summary\*(C'\fR commands was added in version 3.2. .PP Support for the \f(CW\*(C`ALL\*(C'\fR keyword in the command field of the configuration file was added in version 2.15. (It has always been supported in the subcommand field.) .PP Support for the \f(CW\*(C`EMPTY\*(C'\fR keyword in the subcommand field of the configuration file was added in version 2.15. .PP Support for \s-1ACL\s0 schemes and the \fImethod\fR:\fIdata\fR syntax was added in remctl 2.13. Prior versions of \fBremctld\fR expected only files in the main \&\fBremctld\fR configuration file, and only principals or lines starting with \&\f(CW\*(C`include\*(C'\fR in those files, without any \fImethod\fR: prefixes. .PP The default listening port with the \fB\-m\fR option was changed to the IANA-registered port of 4373 in version 2.11. .PP Support for IPv6 addresses in the \s-1REMOTE_ADDR\s0 environment variable was added in version 2.4. .PP \&\fBremctld\fR used to set the environment variable \s-1SCPRINCIPAL\s0 when running commands, for (partial) backward compatibility with \fBsysctld\fR, but stopped doing so in version 2.1. .PP \&\f(CW\*(C`include\*(C'\fR directives in \s-1ACL\s0 files were added in version 1.11. \f(CW\*(C`include\*(C'\fR directives in configuration files were added in version 1.8. .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 \fBgssapi\fR\|(3). .PP \&\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 in systemd, your inetd server, or the equivalent, or with \fBulimit\fR when running it as a standalone daemon or under \fBtcpserver\fR. .PP Command arguments may not contain \s-1NUL\s0 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 \f(CW\*(C`stdin=\*(C'\fR option in the configuration file. At most one argument may be passed that way. .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 "AUTHOR" .IX Header "AUTHOR" \&\fBremctld\fR was originally written by Anton Ushakov. Updates and current maintenance are done by Russ Allbery . .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2015\-2016, 2018, 2022 Russ Allbery .PP Copyright 2002\-2012, 2014 The Board of Trustees of the Leland Stanford Junior University .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. .PP SPDX-License-Identifier: \s-1FSFAP\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBremctl\fR\|(1), \fBsyslog\fR\|(3), \fBtcpserver\fR\|(1) .PP The current version of this program is available from its web page at .