HowToWriteALighttpdPlugin » History » Revision 4
Revision 3 (jan, 2005-08-22 16:51) → Revision 4/23 (Anonymous, 2005-10-20 03:15)
= Writing Plugins = Before you start with writing your own plugin, you should feel comfortable with the two basic datatypes in lighttpd and the main headers: * buffer ([source:/trunk/src/buffer.c#latest buffer.c]) * array ([source:/trunk/src/array.c#latest array.c]) * global structures ([source:/trunk/src/base.h#latest base.h]) Next read the server internals: * http://www.lighttpd.net/documentation/state.html * http://www.lighttpd.net/documentation/plugins.html == The Skeleton == Make sure that * automake 1.8.x or higher * autoconf 2.57 or higher * libtool 1.5.x or higher are installed on your system. A good starting point for writing your own plugin is the shipped mod_skeleton.c which just contains a basic skeleton and a semi-working copy of the mod_access module. mod_access is really simple and should be taken as a basic guide how the modules work. To turn mod_skeleton into a usefull plugin take your favorite editor and replace all occurances of the work 'skeleton' by the name of your plugin: {{{ $ cd src/ $ cp mod_skeleton.c mod_counter.c $ vi mod_counter.c :%s/skeleton/counter/g }}} and add some lines to the src/Makefile.am to tell the build system about your new plugin: {{{ lib_LTLIBRARIES += mod_counter.la mod_counter_la_SOURCES = mod_counter.c mod_counter_la_LDFLAGS = -module -export-dynamic -avoid-version -no-undefined mod_counter_la_LIBADD = $(common_libadd) }}} By default, default the build system will assume that you are a user and only want to compile the existing code. Changes to the Makefile.am files will not result in an a update to the Makefiles. You have to tell 'configure' that you are a brave developer: {{{ $ ./configure --enable-maintainer-mode ... }}} This will automaticly result in a rebuild of the Makefile.am for you and whenever when ever you update the Makefile.am like adding new dependency libs the Makefile will be rebuilt and everything is fine. While you are developing you might use a prefix to install all files too as you don't want to interfere with the real installation: {{{ $ ./configure --enable-maintainer-mode --prefix=${HOME}/testbed/lighttpd-1.4.x/ ... }}} This also removes the burden to install everything as root. Just change your config to use a port greater than 1024 and root-privileges aren't needed to run lighttpd. == The code layout == Now take a look at your you plugin, mod_counter. You should see: * the configuration structures: plugin_config and plugin_data * the init code for the structures * set_defaults to parse the configuration * the patch-function which applies the conditionals * the real work code and finally * plugin_init function which is called call once the register the plugin is registered into the server === plugin_config === Every plugin can opt-in to handle conditionals from the global configfile and store stores the different settings in a by-condition plugin_config. This struct is in linked in the next plugin-wide struct: plugin_data === plugin_data === Each plugin has some local data which only belongs to the plugin (like like the config and some temporary buffers). buffers. === handler_ctx === If a plugin has to store connection specific information, information you need another structure with which one entry per connection. Take a look at mod_rewrite as an example. === neccesary functions === * _init * _free * _set_defaults * _plugin_init ==== _plugin_init ==== Each plugin has to have a ..._plugin_init function which is called when the plugin is called. It should only set p->name to a buffer containing the name of the plugin (human readable) and should fill the hooks (init, set_defaults, cleanup) and return with 0; ==== _init ==== The ..._init function is called to the initialize the plugin itself and returns return the plugin_data struct with some usefull defaults. ==== _free ==== ..._free is called at the end of the life of a plugin and is used to tell the plugin to release all allocated memory. Keep in mind that it is preferred not to let the program termination clean up memory for you. Free what ever you have malloced. Use valgrind or something else to verify your work. ==== _set_defaults ==== As soon as the configfile is parsed, parsed each plugin gets the chance to the fetch its config-values from the config and verify it internally. A config_values_t struct contains the config-key and the type you expect. Don't forget that the last entry of the struct should be NULL to the mark the end. If you don't care about conditionals, conditionals the set_defaults function is quite simple: * set the destinations of the config_values_t * call config_insert_values_global() ==== conditionals ==== If you are interested in conditonals, conditonals you need some more work as you have to call config_insert_values_global() once per condition. Look at See mod_access.c to see how that this works. You need a config_storage for all the conditionals and a patch function. The patch function sets set the basic defaults and applies the necessary modifications for the currently valid conditionals. Don't forget to check if the patched config makes make sense when you use it. The patch functions have to be called as soon as one of the work-handlers is called (like like _uri_handler and friends). friends. {{{ #!c mod_counter_patch_connection(srv, con, p); }}} === return values === In most cases, cases you will only work with HANDLER_GO_ON, HANDLER_FINISHED and HANDLER_ERROR. HANDLER_GO_ON is returned return in most of the cases when you want another plugin to have a chance change to touch the request too. If you know that this request is not for you, just return HANDLER_GO_ON and you are done. HANDLER_ERROR should only be called if something fatal happens happends as it terminates the current connection if called in one of the handlers or terminates lighttpd if called in _set_defaults. HANDLER_FINISHED is the final return-code used use to signal that everything is ready prepared to serve the request like * a non-200 status-code has been set * content has been generated you everything is in place HANDLER_WAIT_FOR_EVENT and HANDLER_WAIT_FOR_FD should be returned if you are not finished yet and have to the wait for an and fd-event or if you ran out of FDs. HANDLER_COMEBACK is useful if you want to re-check the request-structure. This is used in mod_rewrite to handle the rewritten URI.