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 Plugins are separated into two groups:  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 a list of plugin names.  The way
  23 of declaring them is different for modules and scripts but their names
  24 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 are automatically loaded after the declaring
  33   plugin is loaded.
  34
  35 needs:
  36   Dependency resolving fails if any of the plugins listed here is not
  37   loaded.
  38
  39 depends:
  40   If any of the plugins listed here is not loaded the declaring plugin
  41   is automatically unloaded.  This may fail if the plugin is already
  42   required by some other plugin.
  43
  44 conflicts:
  45   Dependency resolving fails if any of the plugins listed here is
  46   loaded.
  47
  48 The last two dependencies are used to specify the order of the plugins:
  49
  50 preceeds:
  51   The declaring plugin must come before the plugins listed here.
  52
  53 succeeds:
  54   The declaring plugin must come after the plugins listed here.
  55
  56 Sorting the plugins may fail if the "preceeds" and "succeeds"
  57 dependencies introduce circles.
  58
  59 HOOKS
  60 =====
  61
  62 There are four different hooks that plugins may declare:
  63
  64 vlock_start:
  65   This hook is called once immediately after vlock is initialized and
  66   before any authentication prompt.  If a plugin signals an error in
  67   this hook vlock aborts.
  68
  69 vlock_end:
  70   This hook is called once after successful authentication or if vlock
  71   is killed by SIGTERM.  Errors in this hook are ignored.
  72
  73 vlock_save:
  74   This hook is called after the vlock message is displayed every time
  75   the timeout expires or the escape key is pressed.  If a plugin signals
  76   an error in this hook its vlock_save_abort hook is called and both
  77   hooks are not called again afterwards.
  78
  79 vlock_save_abort:
  80   This hook is called after vlock_save was called and any key was
  81   pressed.  If a plugin signals an error in this hook both this hook and
  82   the vlock_save hook are not called again.
  83
  84 Note: Hooks should not block.  Screensavers should be executed in a
  85 background process or thread.  The only exception would be hooks that
  86 suspend the machine (though these technically do not block either).