1OVERVIEW 2======== 3 4Plugins are a way to extend vlock's functionality. They can define 5hooks that are called at certain points in a vlock session. 6 7There are two separate types of plugins: modules and scripts. Modules 8are shared objects that are loaded into vlock's address space. They run 9with the same privileges as vlock and thus are very powerful but also 10dangerous. Scripts may be any kind of executables located in vlock's 11script directory. They are run in separate processes with lowered 12privileges, i.e. the same as the user who started vlock. 13 14For simple tasks scripts should be preferred over modules. They are 15easier to develop and test and have a lower impact on security and 16stability. 17 18NB: The following interface is not yet declared stable. It is not guaranteed 19that plugins (modules or scripts) that work with vlock 2.2 will work with 20future versions. 21 22DEPENDENCIES 23============ 24 25Plugins may depend on each other in several ways. There are six 26different types of dependencies. Each dependency type is represented by 27a list of plugin names. The way of declaring them is different for 28modules and scripts but their names and meaning are the same. 29 30Resolving the dependencies is done after all initially requested plugins 31are loaded and may fail if dependencies cannot be met. 32 33The names and meaning of the dependencies are as follows: 34 35requires: 36 The plugins listed here must be loaded for the declaring plugin to 37 work. If any of the plugins is not loaded yet it will be loaded 38 automatically. Dependency resolving fails if a plugin cannot be 39 loaded. 40 41needs: 42 The plugins listed here must be loaded for the declaring plugin to 43 work. Dependency resolving fails if any of the plugins listed here is 44 not loaded. 45 46depends: 47 The plugins listed here must be loaded for the declaring plugin to 48 work. If any of the plugins listed here is not loaded the declaring 49 plugin is automatically unloaded. Dependency resolving fails if the 50 declaring plugin is already required by some other plugin. 51 52conflicts: 53 The plugins listed here must not be loaded at the same time as the 54 declaring plugin. Dependency resolving fails if any of the plugins 55 listed here is loaded. 56 57The other two dependencies are used to specify the order of the plugins: 58 59preceeds: 60 The plugins listed here must come after the declaring plugin. 61 62succeeds: 63 The plugins listed here must come before the declaring plugin. 64 65Sorting the plugins may fail if the "preceeds" and "succeeds" 66dependencies introduce circles. 67 68HOOKS 69===== 70 71There are four different hooks that plugins may declare: 72 73vlock_start: 74 This hook is called once immediately after vlock is initialized and 75 before any authentication prompt. If a plugin signals an error in 76 this hook vlock aborts and calls the vlock_end hooks of all previously 77 called modules. 78 79vlock_end: 80 This hook is called once after successful authentication or if vlock 81 is killed by SIGTERM. Errors in this hook are ignored. 82 83vlock_save: 84 This hook is called after the vlock message is displayed every time 85 the timeout expires or the escape key is pressed. If a plugin signals 86 an error in this hook its vlock_save_abort hook is called and both 87 hooks are not called again afterwards. 88 89vlock_save_abort: 90 This hook is called after vlock_save was called and any key was 91 pressed. If a plugin signals an error in this hook both this hook and 92 the vlock_save hook are not called again. 93 94Note: Hooks should not block. Screensavers should be executed in a 95background process or thread. The only exception would be hooks that 96suspend the machine (though these technically do not block in the common 97sense). 98 99MODULES 100======= 101 102Modules are shared objects that are loaded into vlock's address space. 103They export hook functions and dependencies as global functions. To 104ensure definitions modules should include vlock_plugin.h from the module 105subdirectory of the vlock source distribution. 106 107dependencies 108------------ 109 110Dependencies are declared as NULL terminated arrays of const char 111pointers. Empty lists can be just left out. Example:: 112 113 /* From nosysrq.c */ 114 const char *preceeds[] = { "new", "all", NULL }; 115 const char *depends[] = { "all", NULL }; 116 117hooks 118----- 119 120Hooks are boolean functions that take a void pointer pointer. Their 121return status indicates success or failure. The argument points to a 122void pointer that may be set freely. It may be used to maintain state 123between the different hooks. It is initialized to NULL. Hook functions 124must not block and not terminate the program. On error they may print 125the cause of the error to stderr in addition to returning false. 126 127example 128------- 129 130Please see modules/example_module.c in the vlock source distribution. 131 132SCRIPTS 133======= 134 135Scripts are executables that are started as child processes of vlock. 136They run with the same privileges as the user starting vlock instead of 137the privileges of the vlock process. They communicate with vlock 138through command line arguments and pipes. 139 140dependencies 141------------ 142 143To get the dependencies of a script it is run once for each dependency 144item with the dependency name as the single command line argument. Its 145standard output is redirected to a pipe that is read by vlock. The 146plugin should print the dependency items, if any, separated by arbitrary 147white space (carriage return, space or newline) and then exit. No 148errors are detected in this process. 149 150hooks 151----- 152 153After the dependencies are read the script is run one last time this 154time with the string "hooks" as the single command line argument. Its 155standard input is redirected from a pipe that is written to by vlock. 156Whenever a hook should be executed its name followed by a new line 157character are written to the pipe. The script's standard output and 158standard error are redirected to /dev/null. The script should only exit 159if end-of-file is detected on standard in even in cases where no 160subsequent hooks need to be executed. Error detection is limited to 161detecting if the script exits prematurely. There is currently no way 162for a script what kind of error happened. 163 164example 165------- 166 167Please see scripts/example_script.sh in the vlock source distribution. 168