From 315faba747695d905ef13f899e20eaefbf55aa7c Mon Sep 17 00:00:00 2001 From: Paul Mackerras Date: Mon, 21 May 2001 08:34:33 +0000 Subject: [PATCH] Update the plugins documentation --- PLUGINS | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 93 insertions(+), 8 deletions(-) diff --git a/PLUGINS b/PLUGINS index 75c404c..2cbb427 100644 --- 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 -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 @@ -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 -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/ directory for the file, where + 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. @@ -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 -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 @@ -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. +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. @@ -89,6 +103,7 @@ int (*pap_auth_hook)(char *user, int userlen, 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 @@ -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. +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 $ ## -- 2.39.2