1REMCTLD(8) remctl REMCTLD(8)
2
6 remctld - Server for remctl, a remote command execution utility
7
9 remctld [-dFhmSvZ] [-b bind-address [-b bind-address ...]]
10 [-f config] [-k keytab] [-P file] [-p port]
11 [-s service]
12
14 remctld is the server for remctl. It accepts a connection from remctl,
15 receives the command to execute and the arguments, verifies
16 authorization of the user and executes the command, returning the
17 result back to the client. All connections are authenticated using
18 Kerberos GSS-API Kerberos, and all transmissions are also encrypted
19 using the GSS-API privacy layer.
20 remctld is normally started using tcpserver or from inetd, but it may
22 be run in stand-alone mode as a daemon using -m. Either -s must be
23 given to use an alternate identity (which will require the same flag be
24 used for remctl client invocations), or it must be run as root to read
25 the host keytab file. remctld logs its activity using syslog (the
26 daemon facility).
27 The location of the configuration file may be specified with the -f
29 option. The default location is /etc/remctl.conf. For information on
30 the format of the configuration file, see "CONFIGURATION FILE" below.
31 When the command is run, several environment variables will be set
33 providing information about the remote connection. See ENVIRONMENT
34 below for more information.
35 Command-line and configuration options and ACL methods are annotated
37 below with the version at which they were added. For version
38 information for more general features, see COMPATIBILITY below.
39
41 The start of each option description is annotated with the version of
42 remctld in which that option was added with its current meaning.
43 -b bind-address
45 [2.17] When running as a standalone server, bind to the specified
46 local address rather than listening on all interfaces. This option
47 may be given multiple times to bind to multiple addresses. bind-
48 address must be an IP address (either IPv4 or IPv6), not a
49 hostname. Only makes sense in combination with -m.
50 This option is ignored if remctld is passed already open sockets
52 via the systemd socket activation protocol. In that case, the bind
53 addresses of the sockets should be controlled via the systemd
54 configuration.
55 -d [1.10] Enable verbose debug logging to syslog (or to standard
57 output if -S is also given).
58 -F [2.8] Normally when running in stand-alone mode (-m), remctld
60 backgrounds itself to run as a daemon, changes directory to /, and
61 drops any controlling terminal. This flag suppresses this
62 behavior, usually for debugging or so that remctld can be monitored
63 by other processes.
64 -f config
66 [1.0] The configuration file for remctld, overriding the default
67 path.
68 -h [1.10] Show a brief usage message and then exit. This usage method
70 will include a list of supported ACL types and can be used to
71 determine if optional ACL methods were compiled into a given
72 remctld build.
73 -k keytab
75 [2.8] Use keytab as the keytab for server credentials rather than
76 the system default or the value of the KRB5_KTNAME environment
77 variable. Using -k just sets the KRB5_KTNAME environment variable
78 internally in the process.
79 -m [2.8] Enable stand-alone mode. remctld will listen to its
81 configured port and fork a new child for each incoming connection.
82 By default, when this option is used, remctld also changes
83 directory to /, backgrounds itself, and closes standard input,
84 output, and error. To not background, pass -F as well. To not
85 close standard output and error and continue using them for
86 logging, pass -S as well.
87 To determine the port, remctld attempts to look up the "remctl"
89 service in the local /etc/services file and uses the port defined
90 there. If the "remctl" service could not be found, it uses 4373,
91 the registered remctl port.
92 When running in stand-alone mode, send the SIGHUP signal to remctld
94 to ask it to re-read its configuration file and SIGTERM to ask it
95 to exit.
96 -P file
98 [2.0] When running in stand-alone mode (-m), write the PID of
99 remctld to file. This option is ignored unless -m is also given.
100 -p port
102 [1.0] When running in stand-alone mode, listen on port port rather
103 than the default. This option does nothing unless used with -m.
104 This option is ignored if remctld is passed already open sockets
106 via the systemd socket activation protocol. In that case, the
107 listening port should be controlled via the systemd configuration.
108 -S [2.3] Rather than logging to syslog, log debug and routine
110 connection messages to standard output and error messages to
111 standard error. This option is mostly useful for testing and
112 debugging.
113 -s service
115 [1.0] Specifies which principal is used as the server identity for
116 client authentication. The client must also use the same identity
117 as the server identity for authentication to succeed. By default,
118 remctld accepts any principal with a key in the default keytab file
119 (which can be changed with the -k option). This is normally the
120 most desirable behavior.
121 -v [1.10] Print the version of remctld and exit.
123 -Z [3.7] When remctld is running in stand-alone mode, after it has set
125 up its network socket and is ready to answer requests, raise
126 SIGSTOP. This signals to upstart, when using "expect stop", that
127 the daemon is ready to accept connections, and upstart will raise
128 SIGCONT to allow remctld to continue. This option is probably only
129 useful when using upstart as the init system. Only makes sense in
130 combination with -m.
131
133 The configuration file defines the allowed commands and specifies
134 access control information. The configuration file format is lines of
135 space- or tab-separated strings, where each line is:
136 command subcommand executable [option=value ...] acl [acl ...]
138 Each command consists of a command, a subcommand, and zero or more
140 arguments. Each configuration line defines an acceptable command and
141 subcommand (or, if "ALL" is used as mentioned below under command and
142 subcommand, a set of commands). The first configuration line matching
143 the received command is used, so list more specific entries before more
144 general entries.
145 Blank lines and lines beginning with "#" are ignored. Lines can be
147 continued on the next line by ending them with a backslash ("\"). Be
148 aware that comments can be continued with a backslash as well.
149 As a special case, a line like:
151 include file
153 will include file as if its contents were pasted verbatim into the
155 configuration file at that point. file may be a directory, in which
156 case all files whose names do not contain a period found in that
157 directory will be included (in no particular order). file should be a
158 fully qualified path.
159 The configuration file is loaded when remctld starts and is normally
161 not re-read. To trigger a re-read of the configuration file when
162 remctld is running in stand-alone mode, send the SIGHUP signal to the
163 remctld process.
164 The meaning of the fields on each configuration line are:
166 command
168 The command being issued or the special keyword "ALL". Normally,
169 related commands (such as all commands for managing a particular
170 service) are grouped together as subcommands under one command.
171 If the keyword "ALL" is used instead of a specific subcommand, this
173 line matches all commands with the given subcommand (so "ALL ALL"
174 matches any command) and can be used to dispatch all commands to
175 the same executable with the same ACLs. Since the first matching
176 entry is used, list entries for specific commands first (if any)
177 and then the "ALL" catch-all.
178 Note that while the subcommand is passed to the executable as a
180 command-line option, the command is not. The command is available
181 to the executable in the environment variable REMCTL_COMMAND (see
182 ENVIRONMENT below).
183 The command "help" is handled specially if no such command is
185 defined in the configuration file. See below under the "help" and
186 "summary" options.
187 subcommand
189 The subcommand within the command being requested, such as
190 "release" for the release function of the AFS volume backend, or
191 one of the special keywords "ALL" or "EMPTY".
192 If the keyword "ALL" is used instead of a specific subcommand, this
194 line matches all subcommands with the given command and can be used
195 to dispatch all subcommands under that command to the same
196 executable with the same ACLs. Since the first matching entry is
197 used, list entries for specific services first (if any) and then
198 the "ALL" catch-all.
199 If the keyword "EMPTY" is used instead of a specific subcommand,
201 this line matches only commands where no subcommand was given.
202 The subcommand is always passed as the first argument to the
204 executable program that is listed for that service unless no
205 subcommand was given.
206 executable
208 The full path to the command executable to run for this command and
209 subcommand combination. (See examples below.)
210 option=value
212 An option setting that applies to this command. Supported option
213 settings, annotated with the version at which that option was added
214 in its current form, are:
215 help=arg
217 [3.2] Specifies the argument for this command that will print
218 help for a particular subcommand to standard output.
219 If remctld receives the command "help" with one or two
221 arguments, and no "help" command is defined in the
222 configuration file, the server will take the command arguments
223 as a command and subcommand. It will then look through the
224 configuration for a configuration line matching that command
225 and subcommand with a "help" option set. If one is found and
226 the user is authorized to run that command, the server will run
227 the specified executable with the argument arg and second and
228 optional third arguments taken from the arguments to the "help"
229 command, sending the output back to the user.
230 This permits a standard interface to get additional help for a
232 particular remctl command. Also see the "summary" option.
233 logmask=n[,...]
235 [1.4] Limit logging of command arguments. Any argument listed
236 in the logmask list will have its value logged as "**MASKED**".
237 This is to avoid logging the arguments of commands that take
238 private information such as passwords. The logmask list should
239 contain argument numbers separated by commas, with the
240 subcommand considered argument 1. The command argument cannot
241 be masked.
242 For example, if the command is "admin passwd username
244 password", then you'd want to set logmask to 3, so the password
245 argument gets logged as "**MASKED**". If the command is "user
246 passwd username old-password new-password", you'd want to set
247 logmask to "3,4".
248 stdin=(n | "last")
250 [2.14] Specifies that the nth or last argument to the command
251 be passed on standard input instead of on the command line.
252 The value of this option must either be the number of argument
253 to pass on standard input (with the subcommand considered
254 argument 1) or the special value "last", which indicates that
255 the final argument (no matter how many there are) be passed on
256 standard input.
257 The command cannot be passed on standard input, so n must be at
259 least 1. If this option is set to "last" and no arguments are
260 given except the command and possibly the subcommand, nothing
261 will be passed on standard input.
262 This option is used primarily for passing large amounts of data
264 that may not fit on the command line or data that contains NUL
265 characters. It can also be used for arguments like passwords
266 that shouldn't be exposed on the command line. Only at most
267 one argument may be passed on standard input to the command.
268 Be aware that even if the subcommand is the designated argument
269 to pass on standard input ("stdin=1"), the subcommand may not
270 contain NUL characters.
271 sudo=(username | #uid)
273 [3.12] Run this command as the specified user using sudo. This
274 is exactly equivalent to prepending "sudo -u username --" to
275 the command before running it. The path to sudo is determined
276 when remctld is built.
277 The user option is simpler and easier if remctld is running as
279 root. However, it may be desirable in some configurations to
280 run remctld as a non-root user, and remctl-shell (which shares
281 the same configuration files) usually runs as a non-root user.
282 In those cases, this option can be used to use sudo to switch
283 users before running the command.
284 Since the argument is passed verbatim to sudo's -u option, you
286 can specify a numeric UID by prepending it with "#".
287 summary=arg
289 [3.13] Specifies the argument for this command that will print
290 a usage summary to standard output.
291 If remctld receives the command "help" with no arguments, and
293 no "help" command is defined in the configuration file, the
294 server will look through the configuration for any command with
295 a "summary" option set. If this option is set, and the user is
296 authorized to run the command, the server will run the
297 specified executable with the argument arg, sending the output
298 back to the user. It will do this for every command in the
299 configuration that meets the above criteria.
300 This allows display of a summary of available commands to the
302 user based on which commands that user is authorized to run.
303 It's a lightweight form of service discovery. Also see the
304 "help" option.
305 user=(username | uid)
307 [3.1] Run this command as the specified user, which can be
308 given as either a username or as a UID. Even if given as a
309 UID, the user must be found in the user database (searched via
310 getpwuid(3)). remctld will run the command as the specified
311 user, including that user's primary and supplemental groups.
312 acl One or more entries of the form [method:]data, where method
314 specifies an access control method to be used, and data contains
315 parameters whose meaning depends on the method. If the method is
316 omitted, the data is processed as described for the "file" method.
317 If method is omitted, acl must either begin with "/" or must not
319 contain "=". Otherwise, it will be parsed as an option instead.
320 If there is any ambiguity, prepend the method.
321 As a special exception for backward compatibility, the ACL
323 "ANYUSER" (case-sensitive) is treated as equivalent to
324 "anyuser:auth".
325 Each entry is checked in order, and access is granted as soon as an
327 entry matches. If no entry matches, access is denied. The
328 following methods may supported; however, be aware that the
329 availability of several ACL types depends on whether remctld was
330 built with that support. Each ACL type is annotated with the
331 version in which it was added.
332 anyuser
334 [3.10] Permit access to any user. This comes in two forms:
335 anyuser:auth
337 Permit any authenticated user. This means not only the
338 local Kerberos realm but also any realm with which there is
339 a cross-realm trust relationship.
340 anyuser:anonymous
342 Permit entirely anonymous users. This means no
343 authentication whatsoever is required to run the command.
344 Any client with network access to the server can run the
345 command (using anonymous PKINIT), assuming that anonymous
346 service tickets are enabled for the local Kerberos realm.
347 For backwards compatibility, the ACL "ANYUSER" is treated as
349 identical to "anyuser:auth". This was the only supported any-
350 user ACL syntax prior to remctl 3.10.
351 file
353 [2.13] The data is the full path of an ACL file or to a
354 directory containing ACL files. Directories are handled as
355 described for the include directive in configuration files. An
356 ACL file contains one entry per line, in the [method:]data form
357 described above. Entries are handled exactly as if they had
358 appeared in the configuration file except that the default
359 method is "princ" instead of "file". Blank lines and lines
360 beginning with "#" are ignored in the ACL files.
361 For backward compatibility, a line like:
363 include [<method>:]<data>
365 in an ACL file behaves exactly as if the "include" directive
367 had been omitted, except that the default method is "file".
368 Thus, writing:
369 include <path>
371 in an ACL file is the same as writing:
373 file:<path>
375 and is handled identically to the include directive in
377 configuration files.
378 princ
380 [2.13] The data is the name of a Kerberos v5 principal which is
381 to be granted access, such as "username@EXAMPLE.ORG".
382 deny
384 [2.13] This method is used to selectively deny access. The
385 data is parsed as a [method:]data and evaluated as described
386 above, with the default scheme being "princ". If it matches,
387 access is denied immediately without examining any further
388 entries. Otherwise, processing continues.
389 Remember that access is granted as soon as an entry matches.
391 For "deny" rules to be effective, they therefore must come
392 before any ACLs they are intended to override. Be careful when
393 using "deny" when including a directory of ACL files, since the
394 files in that directory are read in an undefined order (not in
395 alphabetical order by filename). It's best to explicitly
396 include the file containing "deny" ACL rules first.
397 Note that "deny" only denies access; it never grants it. Thus,
399 deny alone does not grant access to anyone, and using deny on
400 itself as in "deny:deny:foo" neither denies nor grants access
401 to anyone.
402 gput
404 [2.13] This method is used to grant access based on the CMU
405 GPUT (Global Privileged User Table -- see gput(5)). The data
406 is either a GPUT role name or a string of the form
407 group[xform], where group is a GPUT role name and xform is a
408 GPUT transform string. Access is granted if the user is a
409 member of the specified GPUT group, after applying either the
410 optional xform or the default transform.
411 This method is supported only if remctld was compiled with GPUT
413 support by using the "--with-gput" configure option.
414 localgroup
416 [3.9] This method is used to grant or deny access based on
417 membership in local UNIX groups. The data is taken to be a
418 name of a local system group. The user principal is converted
419 to a local user name with krb5_aname_to_localname(3) and then
420 compared to the members of the given group.
421 For example, to allow access to the members of group
423 "goodguys", use an ACL of "localgroup:goodguys" syntax. To
424 deny access to the members of group "badguys", use
425 "deny:localgroup:badguys".
426 krb5_aname_to_localname() follows local configuration rules to
428 determine how to convert Kerberos principal to local users. If
429 the realm of the principal is not in a local realm and is not
430 otherwise covered by one of those rules, the principal will be
431 unchanged, which will almost certainly mean that it will not be
432 a member of any local group and access will be denied.
433 This method is supported only if remctld was built with
435 Kerberos support and the getgrnam_r(3) library function was
436 supported by the C library when it was built.
437 pcre
439 [2.16] This method is used to grant or deny access based on
440 Perl-compatible regular expressions. The data is taken to be a
441 Perl-compatible regular expression and matched against the user
442 identity. To deny access, use the "deny:pcre:regex" syntax.
443 The regular expression is not automatically anchored, so be
445 careful to anchor it at the start and end (with "\A" and "\z")
446 to ensure that the entire principal name is matched, unless you
447 intend to allow partial matches.
448 This method is supported only if remctld was compiled with PCRE
450 support (either PCRE2 or PCRE1).
451 regex
453 [2.16] This method is used to grant or deny access based on
454 POSIX extended regular expressions. The data is taken to be a
455 POSIX extended regular expression (like those used by egrep)
456 and matched against the user identity. To deny access, use the
457 "deny:regex:regex" syntax.
458 The regular expression is not automatically anchored, so be
460 careful to anchor it at the start and end (with "^" and "$") to
461 ensure that the entire principal name is matched, unless you
462 intend to allow partial matches.
463 This method is supported only if a library for POSIX-compatible
465 regular expressions was found when remctld was built.
466 To see the list of ACL types supported by a particular build of
468 remctld, run "remctld -h".
469 The keyword ANYUSER may be used instead of the ACLs to allow access
471 to all users. The user still needs to authenticate to remctld;
472 this only affects authorization. This can be used for backend
473 programs that want to check ACLs themselves and will retrieve the
474 authenticated principal from the REMOTE_USER environment variable.
475 Note that ANYUSER accepts any authenticated user, including cross-
476 realm users from foreign Kerberos realms.
477
479 remctld itself uses the following environment variables when run in
480 stand-alone mode (-m):
481 LISTEN_FDS
483 LISTEN_PID
484 If these environment variables are set, remctld will expect to be
485 provided its listening sockets via the systemd socket activation
486 protocol and will not attempt to bind its own sockets. For more
487 details on the protocol, see daemon(7) and sd_listen_fds(3).
488 NOTIFY_SOCKET
490 If this environment variable is set, remctld will notify the socket
491 named in this variable when it is ready to accept incoming packets
492 using the systemd status notification protocol. For more details,
493 see daemon(7) and sd_notify(3).
494 Note that using socket activation is recommended when running under
496 systemd in stand-alone mode, and status notification is not
497 necessary or useful when using socket activation.
498 When running in stand-alone mode, these environment variables will be
500 cleared by remctld before running any commands.
501 The following environment variables will be set for any commands run
503 via remctld (annotated with the version at which they were added):
504 REMCTL_COMMAND
506 [2.16] The command string that caused this command to be run. This
507 variable will contain only the command, not the subcommand or any
508 additional arguments (which are passed as command arguments).
509 REMOTE_ADDR
511 [2.1] The IP address of the remote host. This may be IPv4 or IPv6.
512 REMOTE_EXPIRES
514 [3.10] The time (in seconds since UNIX epoch) when the
515 authenticated remote session will expire. This will normally be
516 the expiration time of the Kerberos ticket used to authenticate to
517 the server.
518 REMOTE_HOST
520 [2.1] The hostname of the remote host, if it was available. If
521 reverse name resolution failed, this environment variable will not
522 be set.
523 This is determined via a simple reverse DNS lookup and should be
525 considered under the control of the client. remctl commands should
526 treat it with skepticism and not use it for anything other than
527 logging purposes.
528 REMOTE_USER
530 REMUSER
531 [1.0 for REMUSER, 2.1 for REMOTE_USER] Set to the Kerberos
532 principal of the authenticated client.
533 If the -k flag is used, remctld will also set KRB5_KTNAME to the
535 provided keytab path. This is primarily for communication with the
536 GSS-API library, but this setting will also be inherited by any
537 commands run by remctld.
538
540 remctld is normally started in one of two ways: either as a stand-alone
541 daemon, or via some network management service (for example, systemd or
542 inetd) that handles listening for incoming connections and forking
543 remctld as needed.
544 To start remctld in stand-alone mode instead, run:
546 remctld -m
548 To start remctld in stand-alone mode in the foreground, use:
550 remctld -F -m
552 This is a typical invocation with systemd using socket activation. For
554 upstart (with "expect stop"), use:
555 remctld -F -m -Z
557 To start remctld via inetd, add this line to /etc/inetd.conf:
559 4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
561 or:
563 remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
565 if the "remctl" service is listed in your /etc/services file.
567 Example configuration file:
569 # Comments can be used like this.
571 accounts create /usr/local/bin/doaccount /etc/acl/group1 \
572 /etc/acl/group2
573 accounts delete /usr/local/bin/doaccount /etc/acl/group3
574 accounts view /usr/local/bin/doaccount ANYUSER
575 accounts passwd /usr/local/bin/dopasswd logmask=3 /etc/acl/group1
576 printing ALL /usr/local/bin/printthing /etc/acl/group2
577 The commands "accounts create", "accounts delete", and so forth will
579 all be passed to /usr/local/bin/doaccount with the first argument being
580 the specific subcommand, with the exception of "accounts passwd". That
581 command will be passed to /usr/local/bin/dopasswd instead, but it will
582 still get "passwd" as its first argument. The third argument to
583 "accounts passwd" (presumably the password) will not be logged to
584 syslog. All commands starting with "printing" will be passed to
585 /usr/local/bin/printthing.
586 Example ACL file:
588 # This is a comment.
590 deny:baduser@EXAMPLE.ORG
591 file:/etc/remctl/acl/admins
592 principal:service/admin@EXAMPLE.ORG
593 service/other@EXAMPLE.ORG
594 This ACL file will reject "baduser@EXAMPLE.ORG" even if that user would
596 have been allowed by one of the other ACL rules. It will then grant
597 access according to the ACL entries in /etc/remctl/acl/admins and the
598 specific principals "service/admin@EXAMPLE.ORG" and
599 "service/other@EXAMPLE.ORG". The last line takes advantage of the
600 default ACL method of "principal" when processing an ACL file.
601
603 The version at which various command-line and configuration options and
604 ACL methods were added to remctld are noted in their descriptions.
605 Below is the version information for more general features, in reverse
606 order of when the feature was added.
607 Support for the systemd readiness protocol and socket activation,
609 including honoring the environment variables LISTEN_FDS, LISTEN_PID,
610 and NOTIFY_SOCKET, was added in version 3.7.
611 Special handling of the "help" and "summary" commands was added in
613 version 3.2.
614 Support for the "ALL" keyword in the command field of the configuration
616 file was added in version 2.15. (It has always been supported in the
617 subcommand field.)
618 Support for the "EMPTY" keyword in the subcommand field of the
620 configuration file was added in version 2.15.
621 Support for ACL schemes and the method:data syntax was added in remctl
623 2.13. Prior versions of remctld expected only files in the main
624 remctld configuration file, and only principals or lines starting with
625 "include" in those files, without any method: prefixes.
626 The default listening port with the -m option was changed to the IANA-
628 registered port of 4373 in version 2.11.
629 Support for IPv6 addresses in the REMOTE_ADDR environment variable was
631 added in version 2.4.
632 remctld used to set the environment variable SCPRINCIPAL when running
634 commands, for (partial) backward compatibility with sysctld, but
635 stopped doing so in version 2.1.
636 "include" directives in ACL files were added in version 1.11.
638 "include" directives in configuration files were added in version 1.8.
639
641 When using Heimdal with triple-DES keys and talking to old clients that
642 only speak version one of the remctl protocol, remctld may have
643 problems with MIC verification. This doesn't affect new clients and
644 servers since the version two protocol doesn't use MICs. If you are
645 using Heimdal and run into MIC verification problems, see the
646 COMPATIBILITY section of gssapi(3).
647 remctld does not itself impose any limits on the number of child
649 processes or other system resources. You may want to set resource
650 limits in systemd, your inetd server, or the equivalent, or with ulimit
651 when running it as a standalone daemon or under tcpserver.
652 Command arguments may not contain NUL characters and must be shorter
654 than the operating system limit on the length of a command line since
655 they're passed to the command as command-line arguments. The exception
656 is an argument passed via standard input using the "stdin=" option in
657 the configuration file. At most one argument may be passed that way.
658
660 The remctl port number, 4373, was derived by tracing the diagonals of a
661 QWERTY keyboard up from the letters "remc" to the number row.
662
664 remctld was originally written by Anton Ushakov. Updates and current
665 maintenance are done by Russ Allbery <eagle@eyrie.org>.
666
668 Copyright 2015-2016, 2018, 2022 Russ Allbery <eagle@eyrie.org>
669 Copyright 2002-2012, 2014 The Board of Trustees of the Leland Stanford
671 Junior University
672 Copying and distribution of this file, with or without modification,
674 are permitted in any medium without royalty provided the copyright
675 notice and this notice are preserved. This file is offered as-is,
676 without any warranty.
677 SPDX-License-Identifier: FSFAP
679
681 remctl(1), syslog(3), tcpserver(1)
682 The current version of this program is available from its web page at
684 <https://www.eyrie.org/~eagle/software/remctl/>.
6853.18 2022-05-09 REMCTLD(8)