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 DEPENDENCIES
  19 ============
  20
  21 Plugins may depend on each other in several ways.  There are six
  22 different types of dependencies. Each dependency type is represented by
  23 a list of plugin names.  The way of declaring them is different for
  24 modules and scripts but their names and meaning are the same.
  25
  26 Resolving the dependencies is done after all initially requested plugins
  27 are loaded and may fail if dependencies cannot be met.
  28
  29 The names and meaning of the dependencies are as follows:
  30
  31 requires:
  32   The plugins listed here must be loaded for the declaring plugin to
  33   work.  If any of the plugins is not loaded yet it will be loaded
  34   automatically.  Dependency resolving fails if a plugin cannot be
  35   loaded.
  36
  37 needs:
  38   The plugins listed here must be loaded for the declaring plugin to
  39   work.  Dependency resolving fails if any of the plugins listed here is
  40   not loaded.
  41
  42 depends:
  43   The plugins listed here must be loaded for the declaring plugin to
  44   work.  If any of the plugins listed here is not loaded the declaring
  45   plugin is automatically unloaded.  Dependency resolving fails if the
  46   declaring plugin is already required by some other plugin.
  47
  48 conflicts:
  49   The plugins listed here must not be loaded at the same time as the
  50   declaring plugin.  Dependency resolving fails if any of the plugins
  51   listed here is loaded.
  52
  53 The other two dependencies are used to specify the order of the plugins:
  54
  55 preceeds:
  56   The plugins listed here must come after the declaring plugin.
  57
  58 succeeds:
  59   The plugins listed here must come before the declaring plugin.
  60
  61 Sorting the plugins may fail if the "preceeds" and "succeeds"
  62 dependencies introduce circles.
  63
  64 HOOKS
  65 =====
  66
  67 There are four different hooks that plugins may declare:
  68
  69 vlock_start:
  70   This hook is called once immediately after vlock is initialized and
  71   before any authentication prompt.  If a plugin signals an error in
  72   this hook vlock aborts.
  73
  74 vlock_end:
  75   This hook is called once after successful authentication or if vlock
  76   is killed by SIGTERM.  Errors in this hook are ignored.
  77
  78 vlock_save:
  79   This hook is called after the vlock message is displayed every time
  80   the timeout expires or the escape key is pressed.  If a plugin signals
  81   an error in this hook its vlock_save_abort hook is called and both
  82   hooks are not called again afterwards.
  83
  84 vlock_save_abort:
  85   This hook is called after vlock_save was called and any key was
  86   pressed.  If a plugin signals an error in this hook both this hook and
  87   the vlock_save hook are not called again.
  88
  89 Note: Hooks should not block.  Screensavers should be executed in a
  90 background process or thread.  The only exception would be hooks that
  91 suspend the machine (though these technically do not block in the common
  92 sense).
  93
  94 MODULES
  95 =======
  96
  97 Modules are shared objects that are loaded into vlock's address space.
  98 They export hook functions and dependencies as global functions.  To
  99 ensure definitions modules should include vlock_plugin.h from the module
 100 subdirectory of the vlock source distribution.
 101
 102 dependencies
 103 ------------
 104
 105 Dependencies are declared as NULL terminated arrays of const char
 106 pointers.  Empty lists can be just left out.  Example::
 107
 108   /* From nosysrq.c */
 109   const char *preceeds[] = { "new", "all", NULL };
 110   const char *depends[] = { "all", NULL };
 111
 112 hooks
 113 -----
 114
 115 Hooks are boolean functions that take a void pointer pointer.  Their
 116 return status indicates success or failure.  The argument points to a
 117 void pointer that may be set freely.  It may be used to maintain state
 118 between the different hooks.  It is initialized to NULL.  Hook functions
 119 must not block and not terminate the program.  On error they may print
 120 the cause of the error to stderr in addition to returning false.
 121
 122 example
 123 -------
 124
 125 Please see modules/nosysrc.c for an example plugin.  It's purpose is to
 126 disable the Linux SysRQ mechanism at vlock startup and reenable it at
 127 the end.