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.
   7
   8 A plugin is a standard shared library object, typically with a name
   9 ending in .so.  They are loaded using the standard dlopen() library
  10 call, so plugins are only supported on systems which support shared
  11 libraries and the dlopen call.  At present pppd is compiled with
  12 plugin support only under Linux and Solaris.
  13
  14 Plugins are loaded into pppd using the `plugin' option, which takes
  15 one argument, the name of a shared object file.  The plugin option is
  16 a privileged option.  If the name given does not contain a slash, pppd
  17 will look in the /usr/lib/pppd/<version> directory for the file, where
  18 <version> is the version number of pppd, for example, 2.4.2.  I
  19 suggest that you either give the full path name of the shared object
  20 file or just the base name; if you don't, it may be possible for
  21 unscrupulous users to substitute another shared object file for the
  22 one you mean to load, e.g. by setting the LD_LIBRARY_PATH variable.
  23
  24 Plugins are usually written in C and compiled and linked to a shared
  25 object file in the appropriate manner for your platform.  Using gcc
  26 under Linux, a plugin called `xyz' could be compiled and linked with
  27 the following commands:
  28
  29         gcc -c -O xyz.c
  30         gcc -shared -o xyz.so xyz.o
  31
  32 There are some example plugins in the pppd/plugins directory in the
  33 ppp distribution.  Currently there is one example, minconn.c, which
  34 implements a `minconnect' option, which specifies a minimum connect
  35 time before the idle timeout applies.
  36
  37 Plugins can access global variables within pppd, so it is useful for
  38 them to #include "pppd.h" from the pppd source directory.
  39
  40 Every plugin must contain a global procedure called `plugin_init'.
  41 This procedure will get called (with no arguments) immediately after
  42 the plugin is loaded.  Every plugin should also contain a variable
  43 called pppd_version declared as follows:
  44
  45 char pppd_version[] = VERSION;
  46
  47 If this declaration is included, pppd will not load the module if its
  48 version number differs from that compiled into the plugin binary.
  49
  50 Plugins can affect the behaviour of pppd in at least four ways:
  51
  52 1. They can add extra options which pppd will then recognize.  This is
  53    done by calling the add_options() procedure with a pointer to an
  54    array of option_t structures.  The last entry in the array must
  55    have its name field set to NULL.
  56
  57 2. Pppd contains `hook' variables which are procedure pointers.  If a
  58    given hook is not NULL, pppd will call the procedure it points to
  59    at the appropriate point in its processing.  The plugin can set any
  60    of these hooks to point to its own procedures.  See below for a
  61    description of the hooks which are currently implemented.
  62
  63 3. Plugin code can call any global procedures and access any global
  64    variables in pppd.
  65
  66 4. Plugins can register procedures to be called when particular events
  67    occur, using the `notifier' mechanism in pppd.  The differences
  68    between hooks and notifiers are that a hook will only call one
  69    function, whereas a notifier can call an arbitrary number, and that
  70    a hook usually returns some value to pppd, whereas a notifier
  71    function returns nothing.
  72
  73 Here is a list of the currently implemented hooks in pppd.
  74
  75
  76 int (*idle_time_hook)(struct ppp_idle *idlep);
  77
  78 The idle_time_hook is called when the link first comes up (i.e. when
  79 the first network protocol comes up) and at intervals thereafter.  On
  80 the first call, the idlep parameter is NULL, and the return value is
  81 the number of seconds before pppd should check the link activity, or 0
  82 if there is to be no idle timeout.
  83
  84 On subsequent calls, idlep points to a structure giving the number of
  85 seconds since the last packets were sent and received.  If the return
  86 value is > 0, pppd will wait that many seconds before checking again.
  87 If it is <= 0, that indicates that the link should be terminated due
  88 to lack of activity.
  89
  90
  91 int (*holdoff_hook)(void);
  92
  93 The holdoff_hook is called when an attempt to bring up the link fails,
  94 or the link is terminated, and the persist or demand option was used.
  95 It returns the number of seconds that pppd should wait before trying
  96 to reestablish the link (0 means immediately).
  97
  98
  99 int (*pap_check_hook)(void);
 100 int (*pap_passwd_hook)(char *user, char *passwd);
 101 int (*pap_auth_hook)(char *user, int userlen,
 102                      char *passwd, int passlen,
 103                      char **msgp, int *msglenp,
 104                      struct wordlist **paddrs,
 105                      struct wordlist **popts);
 106 void (*pap_logout_hook)(void);
 107
 108 These hooks are designed to allow a plugin to replace the normal PAP
 109 password processing in pppd with something different (e.g. contacting
 110 an external server).
 111
 112 The pap_check_hook is called to check whether there is any possibility
 113 that the peer could authenticate itself to us.  If it returns 1, pppd
 114 will ask the peer to authenticate itself.  If it returns 0, pppd will
 115 not ask the peer to authenticate itself (but if authentication is
 116 required, pppd may exit, or terminate the link before network protocol
 117 negotiation).  If it returns -1, pppd will look in the pap-secrets
 118 file as it would normally.
 119
 120 The pap_passwd_hook is called to determine what username and password
 121 pppd should use in authenticating itself to the peer with PAP.  The
 122 user string will already be initialized, by the `user' option, the
 123 `name' option, or from the hostname, but can be changed if necessary.
 124 MAXNAMELEN bytes of space are available at *user, and MAXSECRETLEN
 125 bytes of space at *passwd.  If this hook returns 0, pppd will use the
 126 values at *user and *passwd; if it returns -1, pppd will look in the
 127 pap-secrets file, or use the value from the +ua or password option, as
 128 it would normally.
 129
 130 The pap_auth_hook is called to determine whether the username and
 131 password supplied by the peer are valid.  user and passwd point to
 132 null-terminated strings containing the username and password supplied
 133 by the peer, with non-printable characters converted to a printable
 134 form.  The pap_auth_hook function should set msg to a string to be
 135 returned to the peer and return 1 if the username/password was valid
 136 and 0 if not.  If the hook returns -1, pppd will look in the
 137 pap-secrets file as usual.
 138
 139 If the username/password was valid, the hook can set *paddrs to point
 140 to a wordlist containing the IP address(es) which the peer is
 141 permitted to use, formatted as in the pap-secrets file.  It can also
 142 set *popts to a wordlist containing any extra options for this user
 143 which pppd should apply at this point.
 144
 145 The pap_logout_hook is called when the link is terminated, instead of
 146 pppd's internal `plogout' function.  It can be used for accounting
 147 purposes.  This hook is deprecated and will be replaced by a notifier.
 148
 149
 150 int (*null_auth_hook)(struct wordlist **paddrs,
 151                       struct wordlist **popts);
 152
 153 This hook allows a plugin to determine what the policy should be if
 154 the peer refuses to authenticate when it is requested to.  If the
 155 return value is 0, the link will be terminated; if it is 1, the
 156 connection is allowed to proceed, and in this case *paddrs and *popts
 157 can be set as for pap_auth_hook, to specify what IP addresses are
 158 permitted and any extra options to be applied.  If the return value is
 159 -1, pppd will look in the pap-secrets file as usual.
 160
 161
 162 void (*ip_choose_hook)(u_int32_t *addrp);
 163
 164 This hook is called at the beginning of IPCP negotiation.  It gives a
 165 plugin the opportunity to set the IP address for the peer; the address
 166 should be stored in *addrp.  If nothing is stored in *addrp, pppd will
 167 determine the peer's address in the usual manner.
 168
 169
 170 A plugin registers itself with a notifier by declaring a procedure of
 171 the form:
 172
 173 void my_notify_proc(void *opaque, int arg);
 174
 175 and then registering the procedure with the appropriate notifier with
 176 a call of the form
 177
 178         add_notifier(&interesting_notifier, my_notify_proc, opaque);
 179
 180 The `opaque' parameter in the add_notifier call will be passed to
 181 my_notify_proc every time it is called.  The `arg' parameter to
 182 my_notify_proc depends on the notifier.
 183
 184 A notify procedure can be removed from the list for a notifier with a
 185 call of the form
 186
 187         remove_notifier(&interesting_notifier, my_notify_proc, opaque);
 188
 189 Here is a list of the currently-implemented notifiers in pppd.
 190
 191 * pidchange.  This notifier is called in the parent when pppd has
 192   forked and the child is continuing pppd's processing, i.e. when pppd
 193   detaches from its controlling terminal.  The argument is the pid of
 194   the child.
 195
 196 * phasechange.  This is called when pppd moves from one phase of
 197   operation to another.  The argument is the new phase number.
 198
 199 * exitnotify.  This is called just before pppd exits.  The argument is
 200   the status with which pppd will exit (i.e. the argument to exit()).
 201
 202 * sigreceived.  This is called when a signal is received, from within
 203   the signal handler.  The argument is the signal number.
 204
 205 * ip_up_notifier.  This is called when IPCP has come up.
 206
 207 * ip_down_notifier.  This is called when IPCP goes down.
 208
 209 * auth_up_notifier.  This is called when the peer has successfully
 210   authenticated itself.
 211
 212 * link_down_notifier.  This is called when the link goes down.
 213
 214
 215
 216 ## $Id: PLUGINS,v 1.3 2001/05/21 08:34:33 paulus Exp $ ##