NAME
plugin-runner - Run Mandos plugins, pass data from first to succeed.
SYNOPSIS
plugin-runner [--global-env=ENV=value | -G ENV=value ...]
[--env-for=PLUGIN:ENV=value | -E PLUGIN:ENV=value ...]
[--global-options=OPTIONS | -g OPTIONS ...]
[--options-for=PLUGIN:OPTIONS | -o PLUGIN:OPTIONS ...]
[--disable=PLUGIN | -d PLUGIN ...]
[--enable=PLUGIN | -e PLUGIN ...]
[--groupid=ID]
[--userid=ID]
[--plugin-dir=DIRECTORY]
[--config-file=FILE]
[--debug]
plugin-runner {--help | -?}
plugin-runner --usage
plugin-runner {--version | -V}
DESCRIPTION
plugin-runner is a program which is meant to be specified as a
"keyscript" for the root disk in crypttab(5). The aim of this program
is therefore to output a password, which then cryptsetup(8) will use to
unlock the root disk.
This program is not meant to be invoked directly, but can be in order
to test it. Note that any password obtained will simply be output on
standard output.
PURPOSE
The purpose of this is to enable remote and unattended rebooting of
client host computer with an encrypted root file system. See the
section called "OVERVIEW" for details.
OPTIONS
--global-env ENV=value, -G ENV=value
This option will add an environment variable setting to all
plugins. This will override any inherited environment variable.
--env-for PLUGIN:ENV=value, -E PLUGIN:ENV=value
This option will add an environment variable setting to the PLUGIN
plugin. This will override any inherited environment variables or
environment variables specified using --global-env.
--global-options OPTIONS, -g OPTIONS
Pass some options to all plugins. OPTIONS is a comma separated
list of options. This is not a very useful option, except for
specifying the "--debug" option to all plugins.
--options-for PLUGIN:OPTION, -o PLUGIN:OPTION
Pass some options to a specific plugin. PLUGIN is the name (file
basename) of a plugin, and OPTIONS is a comma separated list of
options.
Note that since options are not split on whitespace, the way to
pass, to the plugin "foo", the option --bar with the option
argument "baz" is either --options-for=foo:--bar=baz or
--options-for=foo:--bar,baz. Using --options-for="foo:--bar baz".
will not work.
--disable PLUGIN, -d PLUGIN
Disable the plugin named PLUGIN. The plugin will not be started.
--enable PLUGIN, -e PLUGIN
Re-enable the plugin named PLUGIN. This is only useful to undo a
previous --disable option, maybe from the configuration file.
--groupid ID
Change to group ID ID on startup. The default is 65534. All plugins
will be started using this group ID. Note: This must be a number,
not a name.
--userid ID
Change to user ID ID on startup. The default is 65534. All plugins
will be started using this user ID. Note: This must be a number,
not a name.
--plugin-dir DIRECTORY
Specify a different plugin directory. The default is
/lib/mandos/plugins.d, which will exist in the initial RAM disk
environment.
--config-file FILE
Specify a different file to read additional options from. See the
section called "FILES". Other command line options will override
options specified in the file.
--debug
Enable debug mode. This will enable a lot of output to standard
error about what the program is doing. The program will still
perform all other functions normally. The default is to not run in
debug mode.
The plugins will not be affected by this option. Use
--global-options=--debug if complete debugging eruption is desired.
--help, -?
Gives a help message about options and their meanings.
--usage
Gives a short usage message.
--version, -V
Prints the program version.
OVERVIEW
This is part of the Mandos system for allowing computers to have
encrypted root file systems and at the same time be capable of remote
and/or unattended reboots. The computers run a small client program in
the initial RAM disk environment which will communicate with a server
over a network. All network communication is encrypted using TLS. The
clients are identified by the server using an OpenPGP key; each client
has one unique to it. The server sends the clients an encrypted
password. The encrypted password is decrypted by the clients using the
same OpenPGP key, and the password is then used to unlock the root file
system, whereupon the computers can continue booting normally.
This program will run on the client side in the initial RAM disk
environment, and is responsible for getting a password. It does this by
running plugins, one of which will normally be the actual client
program communicating with the server.
PLUGINS
This program will get a password by running a number of plugins, which
are simply executable programs in a directory in the initial RAM disk
environment. The default directory is /lib/mandos/plugins.d, but this
can be changed with the --plugin-dir option. The plugins are started in
parallel, and the first plugin to output a password and exit with a
successful exit code will make this plugin-runner output the password
from that plugin, stop any other plugins, and exit.
WRITING PLUGINS
A plugin is simply a program which prints a password to its standard
output and then exits with a successful (zero) exit status. If the exit
status is not zero, any output on standard output will be ignored by
the plugin runner. Any output on its standard error channel will simply
be passed to the standard error of the plugin runner, usually the
system console.
If the password is a single-line, manually entered passprase, a final
trailing newline character should not be printed.
The plugin will run in the initial RAM disk environment, so care must
be taken not to depend on any files or running services not available
there.
The plugin must exit cleanly and free all allocated resources upon
getting the TERM signal, since this is what the plugin runner uses to
stop all other plugins when one plugin has output a password and exited
cleanly.
The plugin must not use resources, like for instance reading from the
standard input, without knowing that no other plugin is also using it.
It is useful, but not required, for the plugin to take the --debug
option.
FALLBACK
If no plugins succeed, this program will, as a fallback, ask for a
password on the console using getpass(3), and output it. This is not
meant to be the normal mode of operation, as there is a separate plugin
for getting a password from the console.
EXIT STATUS
Exit status of this program is zero if no errors were encountered, and
otherwise not. The fallback (see the section called "FALLBACK") may or
may not have succeeded in either case.
ENVIRONMENT
This program does not use any environment variables itself, it only
passes on its environment to all the plugins. The environment passed to
plugins can be modified using the --global-env and --env-for options.
FILES
/conf/conf.d/mandos/plugin-runner.conf
Since this program will be run as a keyscript, there is little to
no opportunity to pass command line arguments to it. Therefore, it
will also read this file and use its contents as
whitespace-separated command line options. Also, everything from a
"#" character to the end of a line is ignored.
This program is meant to run in the initial RAM disk environment,
so that is where this file is assumed to exist. The file does not
need to exist in the normal file system.
This file will be processed before the normal command line options,
so the latter can override the former, if need be.
This file name is the default; the file to read for arguments can
be changed using the --config-file option.
BUGS
The --config-file option is ignored when specified from within a
configuration file.
EXAMPLE
Normal invocation needs no options:
plugin-runner
Run the program, but not the plugins, in debug mode:
plugin-runner --debug
Run all plugins, but run the "foo" plugin in debug mode:
plugin-runner --options-for=foo:--debug
Run all plugins, but not the program, in debug mode:
plugin-runner --global-options=--debug
Run plugins from a different directory, read a different configuration
file, and add two options to the mandos-client(8mandos) plugin:
cd /etc/keys/mandos; plugin-runner
--config-file=/etc/mandos/plugin-runner.conf --plugin-dir
/usr/lib/mandos/plugins.d
--options-for=mandos-client:--pubkey=pubkey.txt,--seckey=seckey.txt
SECURITY
This program will, when starting, try to switch to another user. If it
is started as root, it will succeed, and will by default switch to user
and group 65534, which are assumed to be non-privileged. This user and
group is then what all plugins will be started as. Therefore, the only
way to run a plugin as a privileged user is to have the set-user-ID or
set-group-ID bit set on the plugin executable file (see execve(2)).
If this program is used as a keyscript in crypttab(5), there is a
slight risk that if this program fails to work, there might be no way
to boot the system except for booting from another media and editing
the initial RAM disk image to not run this program. This is, however,
unlikely, since the password-prompt(8mandos) plugin will read a
password from the console in case of failure of the other plugins, and
this plugin runner will also, in case of catastrophic failure, itself
fall back to asking and outputting a password on the console (see the
section called "FALLBACK").
SEE ALSO
cryptsetup(8), crypttab(5), execve(2), mandos(8), password-
prompt(8mandos), mandos-client(8mandos)
COPYRIGHT
Copyright (C) 2008-2009 Teddy Hogeborn, Bjorn Pahlsson
This manual page is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This manual page is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program. If not, see http://www.gnu.org/licenses/.