PLUGINS

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