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 -P file
94 [2.0] When running in stand-alone mode (-m), write the PID of
95 remctld to file. This option is ignored unless -m is also given.
96 -p port
98 [1.0] When running in stand-alone mode, listen on port port rather
99 than the default. This option does nothing unless used with -m.
100 This option is ignored if remctld is passed already open sockets
102 via the systemd socket activation protocol. In that case, the
103 listening port should be controlled via the systemd configuration.
104 -S [2.3] Rather than logging to syslog, log debug and routine
106 connection messages to standard output and error messages to
107 standard error. This option is mostly useful for testing and
108 debugging.
109 -s service
111 [1.0] Specifies which principal is used as the server identity for
112 client authentication. The client must also use the same identity
113 as the server identity for authentication to succeed. By default,
114 remctld accepts any principal with a key in the default keytab file
115 (which can be changed with the -k option). This is normally the
116 most desirable behavior.
117 -v [1.10] Print the version of remctld and exit.
119 -Z [3.7] When remctld is running in stand-alone mode, after it has set
121 up its network socket and is ready to answer requests, raise
122 SIGSTOP. This signals to upstart, when using "expect stop", that
123 the daemon is ready to accept connections, and upstart will raise
124 SIGCONT to allow remctld to continue. This option is probably only
125 useful when using upstart as the init system. Only makes sense in
126 combination with -m.
127
129 The configuration file defines the allowed commands and specifies
130 access control information. The configuration file format is lines of
131 space- or tab-separated strings, where each line is:
132 command subcommand executable [option=value ...] acl [acl ...]
134 Each command consists of a command, a subcommand, and zero or more
136 arguments. Each configuration line defines an acceptable command and
137 subcommand (or, if "ALL" is used as mentioned below under command and
138 subcommand, a set of commands). The first configuration line matching
139 the received command is used, so list more specific entries before more
140 general entries.
141 Blank lines and lines beginning with "#" are ignored. Lines can be
143 continued on the next line by ending them with a backslash ("\"). Be
144 aware that comments can be continued with a backslash as well.
145 As a special case, a line like:
147 include file
149 will include file as if its contents were pasted verbatim into the
151 configuration file at that point. file may be a directory, in which
152 case all files whose names do not contain a period found in that
153 directory will be included (in no particular order). file should be a
154 fully qualified path.
155 The meaning of the fields on each configuration line are:
157 command
159 The command being issued or the special keyword "ALL". Normally,
160 related commands (such as all commands for managing a particular
161 service) are grouped together as subcommands under one command.
162 If the keyword "ALL" is used instead of a specific subcommand, this
164 line matches all commands with the given subcommand (so "ALL ALL"
165 matches any command) and can be used to dispatch all commands to
166 the same executable with the same ACLs. Since the first matching
167 entry is used, list entries for specific commands first (if any)
168 and then the "ALL" catch-all.
169 Note that while the subcommand is passed to the executable as a
171 command-line option, the command is not. The command is available
172 to the executable in the environment variable REMCTL_COMMAND (see
173 ENVIRONMENT below).
174 The command "help" is handled specially if no such command is
176 defined in the configuration file. See below under the "help" and
177 "summary" options.
178 subcommand
180 The subcommand within the command being requested, such as
181 "release" for the release function of the AFS volume backend, or
182 one of the special keywords "ALL" or "EMPTY".
183 If the keyword "ALL" is used instead of a specific subcommand, this
185 line matches all subcommands with the given command and can be used
186 to dispatch all subcommands under that command to the same
187 executable with the same ACLs. Since the first matching entry is
188 used, list entries for specific services first (if any) and then
189 the "ALL" catch-all.
190 If the keyword "EMPTY" is used instead of a specific subcommand,
192 this line matches only commands where no subcommand was given.
193 The subcommand is always passed as the first argument to the
195 executable program that is listed for that service unless no
196 subcommand was given.
197 executable
199 The full path to the command executable to run for this command and
200 subcommand combination. (See examples below.)
201 option=value
203 An option setting that applies to this command. Supported option
204 settings, annotated with the version at which that option was added
205 in its current form, are:
206 help=arg
208 [3.2] Specifies the argument for this command that will print
209 help for a particular subcommand to standard output.
210 If remctld receives the command "help" with one or two
212 arguments, and no "help" command is defined in the
213 configuration file, the server will take the command arguments
214 as a command and subcommand. It will then look through the
215 configuration for a configuration line matching that command
216 and subcommand with a "help" option set. If one is found and
217 the user is authorized to run that command, the server will run
218 the specified executable with the argument arg and second and
219 optional third arguments taken from the arguments to the "help"
220 command, sending the output back to the user.
221 This permits a standard interface to get additional help for a
223 particular remctl command. Also see the "summary" option.
224 logmask=n[,...]
226 [1.4] Limit logging of command arguments. Any argument listed
227 in the logmask list will have its value logged as "**MASKED**".
228 This is to avoid logging the arguments of commands that take
229 private information such as passwords. The logmask list should
230 contain argument numbers separated by commas, with the
231 subcommand considered argument 1. The command argument cannot
232 be masked.
233 For example, if the command is "admin passwd username
235 password", then you'd want to set logmask to 3, so the password
236 argument gets logged as "**MASKED**". If the command is "user
237 passwd username old-password new-password", you'd want to set
238 logmask to "3,4".
239 stdin=(n | "last")
241 [2.14] Specifies that the nth or last argument to the command
242 be passed on standard input instead of on the command line.
243 The value of this option must either be the number of argument
244 to pass on standard input (with the subcommand considered
245 argument 1) or the special value "last", which indicates that
246 the final argument (no matter how many there are) be passed on
247 standard input.
248 The command cannot be passed on standard input, so n must be at
250 least 1. If this option is set to "last" and no arguments are
251 given except the command and possibly the subcommand, nothing
252 will be passed on standard input.
253 This option is used primarily for passing large amounts of data
255 that may not fit on the command line or data that contains NUL
256 characters. It can also be used for arguments like passwords
257 that shouldn't be exposed on the command line. Only at most
258 one argument may be passed on standard input to the command.
259 Be aware that even if the subcommand is the designated argument
260 to pass on standard input ("stdin=1"), the subcommand may not
261 contain NUL characters.
262 sudo=(username | #uid)
264 [3.12] Run this command as the specified user using sudo. This
265 is exactly equivalent to prepending "sudo -u username --" to
266 the command before running it. The path to sudo is determined
267 when remctld is built.
268 The user option is simpler and easier if remctld is running as
270 root. However, it may be desirable in some configurations to
271 run remctld as a non-root user, and remctl-shell (which shares
272 the same configuration files) usually runs as a non-root user.
273 In those cases, this option can be used to use sudo to switch
274 users before running the command.
275 Since the argument is passed verbatim to sudo's -u option, you
277 can specify a numeric UID by prepending it with "#".
278 summary=arg
280 [3.13] Specifies the argument for this command that will print
281 a usage summary to standard output.
282 If remctld receives the command "help" with no arguments, and
284 no "help" command is defined in the configuration file, the
285 server will look through the configuration for any command with
286 a "summary" option set. If this option is set, and the user is
287 authorized to run the command, the server will run the
288 specified executable with the argument arg, sending the output
289 back to the user. It will do this for every command in the
290 configuration that meets the above criteria.
291 This allows display of a summary of available commands to the
293 user based on which commands that user is authorized to run.
294 It's a lightweight form of service discovery. Also see the
295 "help" option.
296 user=(username | uid)
298 [3.1] Run this command as the specified user, which can be
299 given as either a username or as a UID. Even if given as a
300 UID, the user must be found in the user database (searched via
301 getpwuid(3)). remctld will run the command as the specified
302 user, including that user's primary and supplemental groups.
303 acl One or more entries of the form [method:]data, where method
305 specifies an access control method to be used, and data contains
306 parameters whose meaning depends on the method. If the method is
307 omitted, the data is processed as described for the "file" method.
308 If method is omitted, acl must either begin with "/" or must not
310 contain "=". Otherwise, it will be parsed as an option instead.
311 If there is any ambiguity, prepend the method.
312 As a special exception for backward compatibility, the ACL
314 "ANYUSER" (case-sensitive) is treated as equivalent to
315 "anyuser:auth".
316 Each entry is checked in order, and access is granted as soon as an
318 entry matches. If no entry matches, access is denied. The
319 following methods may supported; however, be aware that the
320 availability of several ACL types depends on whether remctld was
321 built with that support. Each ACL type is annotated with the
322 version in which it was added.
323 anyuser
325 [3.10] Permit access to any user. This comes in two forms:
326 anyuser:auth
328 Permit any authenticated user. This means not only the
329 local Kerberos realm but also any realm with which there is
330 a cross-realm trust relationship.
331 anyuser:anonymous
333 Permit entirely anonymous users. This means no
334 authentication whatsoever is required to run the command.
335 Any client with network access to the server can run the
336 command (using anonymous PKINIT), assuming that anonymous
337 service tickets are enabled for the local Kerberos realm.
338 For backwards compatibility, the ACL "ANYUSER" is treated as
340 identical to "anyuser:auth". This was the only supported any-
341 user ACL syntax prior to remctl 3.10.
342 file
344 [2.13] The data is the full path of an ACL file or to a
345 directory containing ACL files. Directories are handled as
346 described for the include directive in configuration files. An
347 ACL file contains one entry per line, in the [method:]data form
348 described above. Entries are handled exactly as if they had
349 appeared in the configuration file except that the default
350 method is "princ" instead of "file". Blank lines and lines
351 beginning with "#" are ignored in the ACL files.
352 For backward compatibility, a line like:
354 include [<method>:]<data>
356 in an ACL file behaves exactly as if the "include" directive
358 had been omitted, except that the default method is "file".
359 Thus, writing:
360 include <path>
362 in an ACL file is the same as writing:
364 file:<path>
366 and is handled identically to the include directive in
368 configuration files.
369 princ
371 [2.13] The data is the name of a Kerberos v5 principal which is
372 to be granted access, such as "username@EXAMPLE.ORG".
373 deny
375 [2.13] This method is used to selectively deny access. The
376 data is parsed as a [method:]data and evaluated as described
377 above, with the default scheme being "princ". If it matches,
378 access is denied immediately without examining any further
379 entries. Otherwise, processing continues.
380 Remember that access is granted as soon as an entry matches.
382 For "deny" rules to be effective, they therefore must come
383 before any ACLs they are intended to override. Be careful when
384 using "deny" when including a directory of ACL files, since the
385 files in that directory are read in an undefined order (not in
386 alphabetical order by filename). It's best to explicitly
387 include the file containing "deny" ACL rules first.
388 Note that "deny" only denies access; it never grants it. Thus,
390 deny alone does not grant access to anyone, and using deny on
391 itself as in "deny:deny:foo" neither denies nor grants access
392 to anyone.
393 gput
395 [2.13] This method is used to grant access based on the CMU
396 GPUT (Global Privileged User Table -- see gput(5)). The data
397 is either a GPUT role name or a string of the form
398 group[xform], where group is a GPUT role name and xform is a
399 GPUT transform string. Access is granted if the user is a
400 member of the specified GPUT group, after applying either the
401 optional xform or the default transform.
402 This method is supported only if remctld was compiled with GPUT
404 support by using the "--with-gput" configure option.
405 localgroup
407 [3.9] This method is used to grant or deny access based on
408 membership in local UNIX groups. The data is taken to be a
409 name of a local system group. The user principal is converted
410 to a local user name with krb5_aname_to_localname(3) and then
411 compared to the members of the given group.
412 For example, to allow access to the members of group
414 "goodguys", use an ACL of "localgroup:goodguys" syntax. To
415 deny access to the members of group "badguys", use
416 "deny:localgroup:badguys".
417 krb5_aname_to_localname() follows local configuration rules to
419 determine how to convert Kerberos principal to local users. If
420 the realm of the principal is not in a local realm and is not
421 otherwise covered by one of those rules, the principal will be
422 unchanged, which will almost certainly mean that it will not be
423 a member of any local group and access will be denied.
424 This method is supported only if remctld was built with
426 Kerberos support and the getgrnam_r(3) library function was
427 supported by the C library when it was built.
428 pcre
430 [2.16] This method is used to grant or deny access based on
431 Perl-compatible regular expressions. The data is taken to be a
432 Perl-compatible regular expression and matched against the user
433 identity. To deny access, use the "deny:pcre:regex" syntax.
434 This method is supported only if remctld was compiled with PCRE
436 support by using the "--with-pcre" configure option.
437 regex
439 [2.16] This method is used to grant or deny access based on
440 POSIX extended regular expressions. The data is taken to be a
441 POSIX extended regular expression (like those used by egrep)
442 and matched against the user identity. To deny access, use the
443 "deny:regex:regex" syntax.
444 This method is supported only if a library for POSIX-compatible
446 regular expressions was found when remctld was built.
447 To see the list of ACL types supported by a particular build of
449 remctld, run "remctld -h".
450 The keyword ANYUSER may be used instead of the ACLs to allow access
452 to all users. The user still needs to authenticate to remctld;
453 this only affects authorization. This can be used for backend
454 programs that want to check ACLs themselves and will retrieve the
455 authenticated principal from the REMOTE_USER environment variable.
456 Note that ANYUSER accepts any authenticated user, including cross-
457 realm users from foreign Kerberos realms.
458
460 remctld itself uses the following environment variables when run in
461 stand-alone mode (-m):
462 LISTEN_FDS
464 LISTEN_PID
465 If these environment variables are set, remctld will expect to be
466 provided its listening sockets via the systemd socket activation
467 protocol and will not attempt to bind its own sockets. For more
468 details on the protocol, see daemon(7) and sd_listen_fds(3).
469 NOTIFY_SOCKET
471 If this environment variable is set, remctld will notify the socket
472 named in this variable when it is ready to accept incoming packets
473 using the systemd status notification protocol. For more details,
474 see daemon(7) and sd_notify(3).
475 Note that using socket activation is recommended when running under
477 systemd in stand-alone mode, and status notification is not
478 necessary or useful when using socket activation.
479 When running in stand-alone mode, these environment variables will be
481 cleared by remctld before running any commands.
482 The following environment variables will be set for any commands run
484 via remctld (annotated with the version at which they were added):
485 REMCTL_COMMAND
487 [2.16] The command string that caused this command to be run. This
488 variable will contain only the command, not the subcommand or any
489 additional arguments (which are passed as command arguments).
490 REMOTE_ADDR
492 [2.1] The IP address of the remote host. This may be IPv4 or IPv6.
493 REMOTE_EXPIRES
495 [3.10] The time (in seconds since UNIX epoch) when the
496 authenticated remote session will expire. This will normally be
497 the expiration time of the Kerberos ticket used to authenticate to
498 the server.
499 REMOTE_HOST
501 [2.1] The hostname of the remote host, if it was available. If
502 reverse name resolution failed, this environment variable will not
503 be set.
504 This is determined via a simple reverse DNS lookup and should be
506 considered under the control of the client. remctl commands should
507 treat it with skepticism and not use it for anything other than
508 logging purposes.
509 REMOTE_USER
511 REMUSER
512 [1.0 for REMUSER, 2.1 for REMOTE_USER] Set to the Kerberos
513 principal of the authenticated client.
514 If the -k flag is used, remctld will also set KRB5_KTNAME to the
516 provided keytab path. This is primarily for communication with the
517 GSS-API library, but this setting will also be inherited by any
518 commands run by remctld.
519
521 Typically remctld is to be started as follows, where "hostname" is the
522 machine where remctld will run, and 4373 is the port:
523 tcpserver hostname 4373 remctld
525 The equivalent line for /etc/inetd.conf is:
527 4373 stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
529 or:
531 remctl stream tcp nowait root /usr/sbin/tcpd /usr/sbin/remctld
533 if the "remctl" service is listed in your /etc/services file.
535 To start remctld in stand-alone mode instead, run:
537 remctld -m
539 To start remctld in stand-alone mode in the foreground, use:
541 remctld -F -m
543 This is a typical invocation with systemd using socket activation. For
545 upstart (with "expect stop"), use:
546 remctld -F -m -Z
548 Example configuration file:
550 # Comments can be used like this.
552 accounts create /usr/local/bin/doaccount /etc/acl/group1 \
553 /etc/acl/group2
554 accounts delete /usr/local/bin/doaccount /etc/acl/group3
555 accounts view /usr/local/bin/doaccount ANYUSER
556 accounts passwd /usr/local/bin/dopasswd logmask=3 /etc/acl/group1
557 printing ALL /usr/local/bin/printthing /etc/acl/group2
558 The commands "accounts create", "accounts delete", and so forth will
560 all be passed to /usr/local/bin/doaccount with the first argument being
561 the specific subcommand, with the exception of "accounts passwd". That
562 command will be passed to /usr/local/bin/dopasswd instead, but it will
563 still get "passwd" as its first argument. The third argument to
564 "accounts passwd" (presumably the password) will not be logged to
565 syslog. All commands starting with "printing" will be passed to
566 /usr/local/bin/printthing.
567 Example ACL file:
569 # This is a comment.
571 deny:baduser@EXAMPLE.ORG
572 file:/etc/remctl/acl/admins
573 principal:service/admin@EXAMPLE.ORG
574 service/other@EXAMPLE.ORG
575 This ACL file will reject "baduser@EXAMPLE.ORG" even if that user would
577 have been allowed by one of the other ACL rules. It will then grant
578 access according to the ACL entries in /etc/remctl/acl/admins and the
579 specific principals "service/admin@EXAMPLE.ORG" and
580 "service/other@EXAMPLE.ORG". The last line takes advantage of the
581 default ACL method of "principal" when processing an ACL file.
582
584 The version at which various command-line and configuration options and
585 ACL methods were added to remctld are noted in their descriptions.
586 Below is the version information for more general features, in reverse
587 order of when the feature was added.
588 Support for the systemd readiness protocol and socket activation,
590 including honoring the environment variables LISTEN_FDS, LISTEN_PID,
591 and NOTIFY_SOCKET, was added in version 3.7.
592 Special handling of the "help" and "summary" commands was added in
594 version 3.2.
595 Support for the "ALL" keyword in the command field of the configuration
597 file was added in version 2.15. (It has always been supported in the
598 subcommand field.)
599 Support for the "EMPTY" keyword in the subcommand field of the
601 configuration file was added in version 2.15.
602 Support for ACL schemes and the method:data syntax was added in remctl
604 2.13. Prior versions of remctld expected only files in the main
605 remctld configuration file, and only principals or lines starting with
606 "include" in those files, without any method: prefixes.
607 The default listening port with the -m option was changed to the IANA-
609 registered port of 4373 in version 2.11.
610 Support for IPv6 addresses in the REMOTE_ADDR environment variable was
612 added in version 2.4.
613 remctld used to set the environment variable SCPRINCIPAL when running
615 commands, for (partial) backward compatibility with sysctld, but
616 stopped doing so in version 2.1.
617 "include" directives in ACL files were added in version 1.11.
619 "include" directives in configuration files were added in version 1.8.
620
622 When using Heimdal with triple-DES keys and talking to old clients that
623 only speak version one of the remctl protocol, remctld may have
624 problems with MIC verification. This doesn't affect new clients and
625 servers since the version two protocol doesn't use MICs. If you are
626 using Heimdal and run into MIC verification problems, see the
627 COMPATIBILITY section of gssapi(3).
628 remctld does not itself impose any limits on the number of child
630 processes or other system resources. You may want to set resource
631 limits in your inetd server or with ulimit when running it as a
632 standalone daemon or under tcpserver.
633 Command arguments may not contain NUL characters and must be shorter
635 than the operating system limit on the length of a command line since
636 they're passed to the command as command-line arguments. The exception
637 is an argument passed via standard input using the "stdin=" option in
638 the configuration file. At most one argument may be passed that way.
639
641 The remctl port number, 4373, was derived by tracing the diagonals of a
642 QWERTY keyboard up from the letters "remc" to the number row.
643
645 remctld was originally written by Anton Ushakov. Updates and current
646 maintenance are done by Russ Allbery <eagle@eyrie.org>.
647
649 Copyright 2002-2012, 2014 The Board of Trustees of the Leland Stanford
650 Junior University
651 Copying and distribution of this file, with or without modification,
653 are permitted in any medium without royalty provided the copyright
654 notice and this notice are preserved. This file is offered as-is,
655 without any warranty.
656 SPDX-License-Identifier: FSFAP
658
660 remctl(1), syslog(3), tcpserver(1)
661 The current version of this program is available from its web page at
663 <https://www.eyrie.org/~eagle/software/remctl/>.
6643.15 2018-05-05 REMCTLD(8)