WRITING PLUGINS

=== modified file 'TODO' --- TODO 2008-09-02 10:27:08 +0000 +++ TODO 2008-09-02 13:04:42 +0000 @@ -7,15 +7,6 @@ ** [#B] Add more if(debug) calls ** [#B] Seperate more code to function for more readability ** [#A] Man page: man8/plugin-runner.8mandos -*** EXAMPLE - Examples of normal usage, debug usage, debugging single or all - plugins, etc. -*** SECURITY - Note the danger of using this program, since you might lock - yourself out of your system without any means of entering the root - file system password. This is, however, very unlikely considering - the fallback to getpass(3). -*** BUGS *** SEE ALSO Explaining text on what you can read === modified file 'plugin-runner.xml' --- plugin-runner.xml 2008-09-02 10:27:08 +0000 +++ plugin-runner.xml 2008-09-02 13:04:42 +0000 @@ -145,8 +145,8 @@ 5 for the root disk. The aim of this program is therefore to output a password, which then cryptsetup - 8 will use to try and - unlock the root disk. + 8 will use to unlock the + root disk. This program is not meant to be invoked directly, but can be in @@ -172,7 +172,7 @@ - - @@ -241,9 +241,9 @@ with the option argument baz is either --options-for=foo:--bar=baz or - --options-for=foo:--bar,baz, but - not - --options-for="foo:--bar baz". + --options-for=foo:--bar,baz. Using + --options-for="foo:--bar baz". will + not work. @@ -403,6 +403,39 @@ 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. + + + 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 plugins + are also using it. + + + It is useful, but not required, for the plugin to take the + option. + + @@ -477,21 +510,98 @@ - - BUGS - - - + + + + + EXAMPLE - - + + + Normal invocation needs no options: + + + &COMMANDNAME; + + + + + Run the program, but not the plugins, in debug mode: + + + + + &COMMANDNAME; --debug + + + + + + Run all plugins, but run the foo plugin in + debug mode: + + + + + &COMMANDNAME; --options-for=foo:--debug + + + + + + Run all plugins, but not the program, in debug mode: + + + + + &COMMANDNAME; --global-options=--debug + + + + + + Run plugins from a different directory and add a special + option to the password-request + 8mandos plugin: + + + + +&COMMANDNAME; --plugin-dir=plugins.d --options-for=password-request:--keydir=keydir + + + - 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 files (see + execve2 + ). + + + If this program is used as a keyscript in crypttab5 + , there is a 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-prompt8mandos + 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 ). @@ -500,6 +610,10 @@ cryptsetup 8, + crypttab + 5, + execve + 2, mandos 8, password-prompt