Update the plugins documentation

diff --git a/PLUGINS b/PLUGINS
index 75c404c91b8064257ba22db548a92a3cb2ae7b66..2cbb427a5c1031b320fef790f451c1497fd68691 100644 (file)
--- a/PLUGINS
+++ b/PLUGINS
@@ -3,9 +3,7 @@ pieces of code which can be loaded into pppd at runtime and which can
 affect its behaviour in various ways.  The idea of plugins is to
 provide a way for people to customize the behaviour of pppd without
 having to either apply local patches to each version or get their
 affect its behaviour in various ways.  The idea of plugins is to
 provide a way for people to customize the behaviour of pppd without
 having to either apply local patches to each version or get their

-patches accepted into the standard distribution.  My aim is that
-plugins will be able to be used with successive versions of pppd
-without needing to recompile the plugins.
+patches accepted into the standard distribution.

 
 A plugin is a standard shared library object, typically with a name
 ending in .so.  They are loaded using the standard dlopen() library
 
 A plugin is a standard shared library object, typically with a name
 ending in .so.  They are loaded using the standard dlopen() library


@@ -15,8 +13,11 @@ plugin support only under Linux and Solaris.
 
 Plugins are loaded into pppd using the `plugin' option, which takes
 one argument, the name of a shared object file.  The plugin option is
 
 Plugins are loaded into pppd using the `plugin' option, which takes
 one argument, the name of a shared object file.  The plugin option is

-a privileged option.  I suggest that you give the full path name of
-the shared object file; if you don't, it may be possible for
+a privileged option.  If the name given does not contain a slash, pppd
+will look in the /usr/lib/pppd/<version> directory for the file, where
+<version> is the version number of pppd, for example, 2.4.2.  I
+suggest that you either give the full path name of the shared object
+file or just the base name; if you don't, it may be possible for

 unscrupulous users to substitute another shared object file for the
 one you mean to load, e.g. by setting the LD_LIBRARY_PATH variable.
 
 unscrupulous users to substitute another shared object file for the
 one you mean to load, e.g. by setting the LD_LIBRARY_PATH variable.
 


@@ -38,9 +39,15 @@ them to #include "pppd.h" from the pppd source directory.
 
 Every plugin must contain a global procedure called `plugin_init'.
 This procedure will get called (with no arguments) immediately after
 
 Every plugin must contain a global procedure called `plugin_init'.
 This procedure will get called (with no arguments) immediately after

-the plugin is loaded.
+the plugin is loaded.  Every plugin should also contain a variable
+called pppd_version declared as follows:

 
 

-Plugins can affect the behaviour of pppd in at least three ways:
+char pppd_version[] = VERSION;
+
+If this declaration is included, pppd will not load the module if its
+version number differs from that compiled into the plugin binary.
+
+Plugins can affect the behaviour of pppd in at least four ways:

 
 1. They can add extra options which pppd will then recognize.  This is
    done by calling the add_options() procedure with a pointer to an
 
 1. They can add extra options which pppd will then recognize.  This is
    done by calling the add_options() procedure with a pointer to an


@@ -56,6 +63,13 @@ Plugins can affect the behaviour of pppd in at least three ways:
 3. Plugin code can call any global procedures and access any global
    variables in pppd.
 
 3. Plugin code can call any global procedures and access any global
    variables in pppd.
 

+4. Plugins can register procedures to be called when particular events
+   occur, using the `notifier' mechanism in pppd.  The differences
+   between hooks and notifiers are that a hook will only call one
+   function, whereas a notifier can call an arbitrary number, and that
+   a hook usually returns some value to pppd, whereas a notifier
+   function returns nothing.
+

 Here is a list of the currently implemented hooks in pppd.
 
 
 Here is a list of the currently implemented hooks in pppd.
 
 


@@ -89,6 +103,7 @@ int (*pap_auth_hook)(char *user, int userlen,
                     char **msgp, int *msglenp,
                     struct wordlist **paddrs,
                     struct wordlist **popts);
                     char **msgp, int *msglenp,
                     struct wordlist **paddrs,
                     struct wordlist **popts);

+void (*pap_logout_hook)(void);

 
 These hooks are designed to allow a plugin to replace the normal PAP
 password processing in pppd with something different (e.g. contacting
 
 These hooks are designed to allow a plugin to replace the normal PAP
 password processing in pppd with something different (e.g. contacting


@@ -127,5 +142,75 @@ permitted to use, formatted as in the pap-secrets file.  It can also
 set *popts to a wordlist containing any extra options for this user
 which pppd should apply at this point.
 
 set *popts to a wordlist containing any extra options for this user
 which pppd should apply at this point.
 

+The pap_logout_hook is called when the link is terminated, instead of
+pppd's internal `plogout' function.  It can be used for accounting
+purposes.  This hook is deprecated and will be replaced by a notifier.
+
+
+int (*null_auth_hook)(struct wordlist **paddrs,
+                     struct wordlist **popts);
+
+This hook allows a plugin to determine what the policy should be if
+the peer refuses to authenticate when it is requested to.  If the
+return value is 0, the link will be terminated; if it is 1, the
+connection is allowed to proceed, and in this case *paddrs and *popts
+can be set as for pap_auth_hook, to specify what IP addresses are
+permitted and any extra options to be applied.  If the return value is
+-1, pppd will look in the pap-secrets file as usual.
+
+
+void (*ip_choose_hook)(u_int32_t *addrp);
+
+This hook is called at the beginning of IPCP negotiation.  It gives a
+plugin the opportunity to set the IP address for the peer; the address
+should be stored in *addrp.  If nothing is stored in *addrp, pppd will
+determine the peer's address in the usual manner.
+
+
+A plugin registers itself with a notifier by declaring a procedure of
+the form:
+
+void my_notify_proc(void *opaque, int arg);
+
+and then registering the procedure with the appropriate notifier with
+a call of the form
+
+       add_notifier(&interesting_notifier, my_notify_proc, opaque);
+
+The `opaque' parameter in the add_notifier call will be passed to
+my_notify_proc every time it is called.  The `arg' parameter to
+my_notify_proc depends on the notifier.
+
+A notify procedure can be removed from the list for a notifier with a
+call of the form
+
+       remove_notifier(&interesting_notifier, my_notify_proc, opaque);
+
+Here is a list of the currently-implemented notifiers in pppd.
+
+* pidchange.  This notifier is called in the parent when pppd has
+  forked and the child is continuing pppd's processing, i.e. when pppd
+  detaches from its controlling terminal.  The argument is the pid of
+  the child.
+
+* phasechange.  This is called when pppd moves from one phase of
+  operation to another.  The argument is the new phase number.
+
+* exitnotify.  This is called just before pppd exits.  The argument is
+  the status with which pppd will exit (i.e. the argument to exit()).
+
+* sigreceived.  This is called when a signal is received, from within
+  the signal handler.  The argument is the signal number.
+
+* ip_up_notifier.  This is called when IPCP has come up.
+
+* ip_down_notifier.  This is called when IPCP goes down.
+
+* auth_up_notifier.  This is called when the peer has successfully
+  authenticated itself.
+
+* link_down_notifier.  This is called when the link goes down.
+
+

 
 

-## $Id: PLUGINS,v 1.2 1999/09/17 06:02:45 paulus Exp $ ##
+## $Id: PLUGINS,v 1.3 2001/05/21 08:34:33 paulus Exp $ ##