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
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.
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
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.
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
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 $ ##
projects / ppp.git / blobdiff