'\" t .\" Title: plugin-runner .\" Author: Bj\(:orn P\(oahlsson .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 2019-07-26 .\" Manual: Mandos Manual .\" Source: Mandos 1.8.16 .\" Language: English .\" .TH "PLUGIN\-RUNNER" "8mandos" "2019\-07\-26" "Mandos 1.8.16" "Mandos Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" plugin-runner \- Run Mandos plugins, pass data from first to succeed\&. .SH "SYNOPSIS" .HP \w'\fBplugin\-runner\fR\ 'u \fBplugin\-runner\fR [\fB\-\-global\-env=\fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR | \fB\-G\ \fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR\fB\ \fR...] .br [\fB\-\-env\-for=\fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR | \fB\-E\fR\fB\fI\ PLUGIN\fR\fR\fB:\fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR\fB\ \fR...] .br [\fB\-\-global\-options=\fR\fB\fIOPTIONS\fR\fR | \fB\-g\fR\fB\fI\ OPTIONS\fR\fR\fB\ \fR...] .br [\fB\-\-options\-for=\fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIOPTIONS\fR\fR | \fB\-o\fR\fB\fI\ PLUGIN\fR\fR\fB:\fR\fB\fIOPTIONS\fR\fR\fB\ \fR...] .br [\fB\-\-disable=\fR\fB\fIPLUGIN\fR\fR | \fB\-d\ \fR\fB\fIPLUGIN\fR\fR\fB\ \fR...] .br [\fB\-\-enable=\fR\fB\fIPLUGIN\fR\fR | \fB\-e\ \fR\fB\fIPLUGIN\fR\fR\fB\ \fR...] .br [\fB\-\-groupid=\fR\fB\fIID\fR\fR] .br [\fB\-\-userid=\fR\fB\fIID\fR\fR] .br [\fB\-\-plugin\-dir=\fR\fB\fIDIRECTORY\fR\fR] .br [\fB\-\-plugin\-helper\-dir=\fR\fB\fIDIRECTORY\fR\fR] .br [\fB\-\-config\-file=\fR\fB\fIFILE\fR\fR] .br [\fB\-\-debug\fR] .HP \w'\fBplugin\-runner\fR\ 'u \fBplugin\-runner\fR {\fB\-\-help\fR | \fB\-?\fR} .HP \w'\fBplugin\-runner\fR\ 'u \fBplugin\-runner\fR \fB\-\-usage\fR .HP \w'\fBplugin\-runner\fR\ 'u \fBplugin\-runner\fR {\fB\-\-version\fR | \fB\-V\fR} .SH "DESCRIPTION" .PP \fBplugin\-runner\fR is a program which is meant to be specified as a \(lqkeyscript\(rq for the root disk in \fBcrypttab\fR(5)\&. The aim of this program is therefore to output a password, which then \fBcryptsetup\fR(8) will use to unlock the root disk\&. .PP 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\&. .SH "PURPOSE" .PP The purpose of this is to enable \fIremote and unattended rebooting\fR of client host computer with an \fIencrypted root file system\fR\&. See the section called \(lqOVERVIEW\(rq for details\&. .SH "OPTIONS" .PP \fB\-\-global\-env \fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR, \fB\-G \fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR .RS 4 This option will add an environment variable setting to all plugins\&. This will override any inherited environment variable\&. .RE .PP \fB\-\-env\-for \fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR, \fB\-E \fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIENV\fR\fR\fB=\fR\fB\fIvalue\fR\fR .RS 4 This option will add an environment variable setting to the \fIPLUGIN\fR plugin\&. This will override any inherited environment variables or environment variables specified using \fB\-\-global\-env\fR\&. .RE .PP \fB\-\-global\-options \fR\fB\fIOPTIONS\fR\fR, \fB\-g \fR\fB\fIOPTIONS\fR\fR .RS 4 Pass some options to \fIall\fR plugins\&. \fIOPTIONS\fR is a comma separated list of options\&. This is not a very useful option, except for specifying the \(lq\fB\-\-debug\fR\(rq option to all plugins\&. .RE .PP \fB\-\-options\-for \fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIOPTION\fR\fR, \fB\-o \fR\fB\fIPLUGIN\fR\fR\fB:\fR\fB\fIOPTION\fR\fR .RS 4 Pass some options to a specific plugin\&. \fIPLUGIN\fR is the name (file basename) of a plugin, and \fIOPTIONS\fR is a comma separated list of options\&. .sp Note that since options are not split on whitespace, the way to pass, to the plugin \(lqfoo\(rq, the option \fB\-\-bar\fR with the option argument \(lqbaz\(rq is either \fB\-\-options\-for=foo:\-\-bar=baz\fR or \fB\-\-options\-for=foo:\-\-bar,baz\fR\&. Using \fB\-\-options\-for="foo:\-\-bar baz"\fR\&. will \fInot\fR work\&. .RE .PP \fB\-\-disable \fR\fB\fIPLUGIN\fR\fR, \fB\-d \fR\fB\fIPLUGIN\fR\fR .RS 4 Disable the plugin named \fIPLUGIN\fR\&. The plugin will not be started\&. .RE .PP \fB\-\-enable \fR\fB\fIPLUGIN\fR\fR, \fB\-e \fR\fB\fIPLUGIN\fR\fR .RS 4 Re\-enable the plugin named \fIPLUGIN\fR\&. This is only useful to undo a previous \fB\-\-disable\fR option, maybe from the configuration file\&. .RE .PP \fB\-\-groupid \fR\fB\fIID\fR\fR .RS 4 Change to group ID \fIID\fR on startup\&. The default is 65534\&. All plugins will be started using this group ID\&. \fINote:\fR This must be a number, not a name\&. .RE .PP \fB\-\-userid \fR\fB\fIID\fR\fR .RS 4 Change to user ID \fIID\fR on startup\&. The default is 65534\&. All plugins will be started using this user ID\&. \fINote:\fR This must be a number, not a name\&. .RE .PP \fB\-\-plugin\-dir \fR\fB\fIDIRECTORY\fR\fR .RS 4 Specify a different plugin directory\&. The default is /lib/mandos/plugins\&.d, which will exist in the initial RAM disk environment\&. .RE .PP \fB\-\-plugin\-helper\-dir \fR\fB\fIDIRECTORY\fR\fR .RS 4 Specify a different plugin helper directory\&. The default is /lib/mandos/plugin\-helpers, which will exist in the initial RAM disk environment\&. (This will simply be passed to all plugins via the \fBMANDOSPLUGINHELPERDIR\fR environment variable\&. See the section called \(lqWRITING PLUGINS\(rq) .RE .PP \fB\-\-config\-file \fR\fB\fIFILE\fR\fR .RS 4 Specify a different file to read additional options from\&. See the section called \(lqFILES\(rq\&. Other command line options will override options specified in the file\&. .RE .PP \fB\-\-debug\fR .RS 4 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 \fInot\fR run in debug mode\&. .sp The plugins will \fInot\fR be affected by this option\&. Use \fB\fB\-\-global\-options=\-\-debug\fR\fR if complete debugging eruption is desired\&. .RE .PP \fB\-\-help\fR, \fB\-?\fR .RS 4 Gives a help message about options and their meanings\&. .RE .PP \fB\-\-usage\fR .RS 4 Gives a short usage message\&. .RE .PP \fB\-\-version\fR, \fB\-V\fR .RS 4 Prints the program version\&. .RE .SH "OVERVIEW" .PP 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 a TLS 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 a separate OpenPGP key, and the password is then used to unlock the root file system, whereupon the computers can continue booting normally\&. .PP 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\&. .SH "PLUGINS" .PP 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 \fB\-\-plugin\-dir\fR option\&. The plugins are started in parallel, and the first plugin to output a password \fIand\fR exit with a successful exit code will make this plugin\-runner output the password from that plugin, stop any other plugins, and exit\&. .SS "WRITING PLUGINS" .PP 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\&. .PP If the password is a single\-line, manually entered passprase, a final trailing newline character should \fInot\fR be printed\&. .PP 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\&. Any helper executables required by the plugin (which are not in the \fBPATH\fR) can be placed in the plugin helper directory, the name of which will be made available to the plugin via the \fBMANDOSPLUGINHELPERDIR\fR environment variable\&. .PP 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\&. .PP The plugin must not use resources, like for instance reading from the standard input, without knowing that no other plugin is also using it\&. .PP It is useful, but not required, for the plugin to take the \fB\-\-debug\fR option\&. .SH "FALLBACK" .PP If no plugins succeed, this program will, as a fallback, ask for a password on the console using \fBgetpass\fR(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\&. .SH "EXIT STATUS" .PP Exit status of this program is zero if no errors were encountered, and otherwise not\&. The fallback (see the section called \(lqFALLBACK\(rq) may or may not have succeeded in either case\&. .SH "ENVIRONMENT" .PP 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 \fB\-\-global\-env\fR and \fB\-\-env\-for\fR options\&. Also, the \fB\-\-plugin\-helper\-dir\fR option will affect the environment variable \fBMANDOSPLUGINHELPERDIR\fR for the plugins\&. .SH "FILES" .PP .PP /conf/conf\&.d/mandos/plugin\-runner\&.conf .RS 4 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 \fIalso\fR read this file and use its contents as whitespace\-separated command line options\&. Also, everything from a \(lq#\(rq character to the end of a line is ignored\&. .sp 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\&. .sp This file will be processed \fIbefore\fR the normal command line options, so the latter can override the former, if need be\&. .sp This file name is the default; the file to read for arguments can be changed using the \fB\-\-config\-file\fR option\&. .RE .PP /lib/mandos/plugins\&.d .RS 4 The default plugin directory; can be changed by the \fB\-\-plugin\-dir\fR option\&. .RE .PP /lib/mandos/plugin\-helpers .RS 4 The default plugin helper directory; can be changed by the \fB\-\-plugin\-helper\-dir\fR option\&. .RE .SH "BUGS" .PP The \fB\-\-config\-file\fR option is ignored when specified from within a configuration file\&. .PP Please report bugs to the Mandos development mailing list: (subscription required)\&. Note that this list is public\&. The developers can be reached privately at (OpenPGP key fingerprint 153A 37F1 0BBA 0435 987F 2C4A 7223 2973 CA34 C2C4 for encrypted mail)\&. .SH "EXAMPLE" .PP Normal invocation needs no options: .PP \fBplugin\-runner\fR .PP Run the program, but not the plugins, in debug mode: .PP \fBplugin\-runner \-\-debug\fR .PP Run all plugins, but run the \(lqfoo\(rq plugin in debug mode: .PP \fBplugin\-runner \-\-options\-for=foo:\-\-debug\fR .PP Run all plugins, but not the program, in debug mode: .PP \fBplugin\-runner \-\-global\-options=\-\-debug\fR .PP Read a different configuration file, run plugins from a different directory, specify an alternate plugin helper directory and add four options to the \fBmandos-client\fR(8mandos) plugin: .PP \fBcd /etc/keys/mandos; plugin\-runner \-\-config\-file=/etc/mandos/plugin\-runner\&.conf \-\-plugin\-dir /usr/lib/x86_64\-linux\-gnu/mandos/plugins\&.d \-\-plugin\-helper\-dir /usr/lib/x86_64\-linux\-gnu/mandos/plugin\-helpers \-\-options\-for=mandos\-client:\-\-pubkey=pubkey\&.txt,\:\-\-seckey=seckey\&.txt,\:\-\-tls\-pubkey=tls\-pubkey\&.pem,\:\-\-tls\-privkey=tls\-privkey\&.pem\fR .SH "SECURITY" .PP 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 \fBexecve\fR(2))\&. .PP If this program is used as a keyscript in \fBcrypttab\fR(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 \fBpassword-prompt\fR(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 \(lqFALLBACK\(rq)\&. .SH "SEE ALSO" .PP \fBintro\fR(8mandos), \fBcryptsetup\fR(8), \fBcrypttab\fR(5), \fBexecve\fR(2), \fBmandos\fR(8), \fBpassword-prompt\fR(8mandos), \fBmandos-client\fR(8mandos) .SH "COPYRIGHT" .br Copyright \(co 2008-2019 Teddy Hogeborn, Bj\(:orn P\(oahlsson .br .PP This manual page is part of Mandos\&. .PP Mandos 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\&. .PP Mandos 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\&. .PP You should have received a copy of the GNU General Public License along with Mandos\&. If not, see \m[blue]\fBhttp://www\&.gnu\&.org/licenses/\fR\m[]\&. .sp