PLUGINS

   1 Starting with version 2.3.10, pppd includes support for `plugins' -
   2 pieces of code which can be loaded into pppd at runtime and which can
   3 affect its behaviour in various ways.  The idea of plugins is to
   4 provide a way for people to customize the behaviour of pppd without
   5 having to either apply local patches to each version or get their
   6 patches accepted into the standard distribution.  My aim is that
   7 plugins will be able to be used with successive versions of pppd
   8 without needing to recompile the plugins.
   9
  10 A plugin is a standard shared library object, typically with a name
  11 ending in .so.  They are loaded using the standard dlopen() library
  12 call, so plugins are only supported on systems which support shared
  13 libraries and the dlopen call.  At present pppd is compiled with
  14 plugin support only under Linux and Solaris.
  15
  16 Plugins are loaded into pppd using the `plugin' option, which takes
  17 one argument, the name of a shared object file.  The plugin option is
  18 a privileged option.  I suggest that you give the full path name of
  19 the shared object file; if you don't, it may be possible for
  20 unscrupulous users to substitute another shared object file for the
  21 one you mean to load, e.g. by setting the LD_LIBRARY_PATH variable.
  22
  23 Plugins are usually written in C and compiled and linked to a shared
  24 object file in the appropriate manner for your platform.  Using gcc
  25 under Linux, a plugin called `xyz' could be compiled and linked with
  26 the following commands:
  27
  28         gcc -c -O xyz.c
  29         gcc -shared -o xyz.so xyz.o
  30
  31 There are some example plugins in the pppd/plugins directory in the
  32 ppp distribution.  Currently there is one example, minconn.c, which
  33 implements a `minconnect' option, which specifies a minimum connect
  34 time before the idle timeout applies.
  35
  36 Plugins can access global variables within pppd, so it is useful for
  37 them to #include "pppd.h" from the pppd source directory.
  38
  39 Every plugin must contain a global procedure called `plugin_init'.
  40 This procedure will get called (with no arguments) immediately after
  41 the plugin is loaded.
  42
  43 Plugins can affect the behaviour of pppd in at least three ways:
  44
  45 1. They can add extra options which pppd will then recognize.  This is
  46    done by calling the add_options() procedure with a pointer to an
  47    array of option_t structures.  The last entry in the array must
  48    have its name field set to NULL.
  49
  50 2. Pppd contains `hook' variables which are procedure pointers.  If a
  51    given hook is not NULL, pppd will call the procedure it points to
  52    at the appropriate point in its processing.  The plugin can set any
  53    of these hooks to point to its own procedures.  See below for a
  54    description of the hooks which are currently implemented.
  55
  56 3. Plugin code can call any global procedures and access any global
  57    variables in pppd.
  58
  59 Here is a list of the currently implemented hooks in pppd.
  60
  61
  62 int (*idle_time_hook)(struct ppp_idle *idlep);
  63
  64 The idle_time_hook is called when the link first comes up (i.e. when
  65 the first network protocol comes up) and at intervals thereafter.  On
  66 the first call, the idlep parameter is NULL, and the return value is
  67 the number of seconds before pppd should check the link activity, or 0
  68 if there is to be no idle timeout.
  69
  70 On subsequent calls, idlep points to a structure giving the number of
  71 seconds since the last packets were sent and received.  If the return
  72 value is > 0, pppd will wait that many seconds before checking again.
  73 If it is <= 0, that indicates that the link should be terminated due
  74 to lack of activity.
  75
  76
  77 int (*holdoff_hook)(void);
  78
  79 The holdoff_hook is called when an attempt to bring up the link fails,
  80 or the link is terminated, and the persist or demand option was used.
  81 It returns the number of seconds that pppd should wait before trying
  82 to reestablish the link (0 means immediately).
  83
  84
  85 int (*pap_check_hook)(void);
  86 int (*pap_passwd_hook)(char *user, char *passwd);
  87 int (*pap_auth_hook)(char *user, int userlen,
  88                      char *passwd, int passlen,
  89                      char **msgp, int *msglenp,
  90                      struct wordlist **paddrs,
  91                      struct wordlist **popts);
  92
  93 These hooks are designed to allow a plugin to replace the normal PAP
  94 password processing in pppd with something different (e.g. contacting
  95 an external server).
  96
  97 The pap_check_hook is called to check whether there is any possibility
  98 that the peer could authenticate itself to us.  If it returns 1, pppd
  99 will ask the peer to authenticate itself.  If it returns 0, pppd will
 100 not ask the peer to authenticate itself (but if authentication is
 101 required, pppd may exit, or terminate the link before network protocol
 102 negotiation).  If it returns -1, pppd will look in the pap-secrets
 103 file as it would normally.
 104
 105 The pap_passwd_hook is called to determine what username and password
 106 pppd should use in authenticating itself to the peer with PAP.  The
 107 user string will already be initialized, by the `user' option, the
 108 `name' option, or from the hostname, but can be changed if necessary.
 109 MAXNAMELEN bytes of space are available at *user, and MAXSECRETLEN
 110 bytes of space at *passwd.  If this hook returns 0, pppd will use the
 111 values at *user and *passwd; if it returns -1, pppd will look in the
 112 pap-secrets file, or use the value from the +ua or password option, as
 113 it would normally.
 114
 115 The pap_auth_hook is called to determine whether the username and
 116 password supplied by the peer are valid.  user and passwd point to
 117 null-terminated strings containing the username and password supplied
 118 by the peer, with non-printable characters converted to a printable
 119 form.  The pap_auth_hook function should set msg to a string to be
 120 returned to the peer and return 1 if the username/password was valid
 121 and 0 if not.  If the hook returns -1, pppd will look in the
 122 pap-secrets file as usual.
 123
 124 If the username/password was valid, the hook can set *paddrs to point
 125 to a wordlist containing the IP address(es) which the peer is
 126 permitted to use, formatted as in the pap-secrets file.  It can also
 127 set *popts to a wordlist containing any extra options for this user
 128 which pppd should apply at this point.
 129
 130
 131 ## $Id: PLUGINS,v 1.2 1999/09/17 06:02:45 paulus Exp $ ##