Writing Plugins¶

Before you start writing your own plugin, you should be able to build lighttpd (lighttpd source code and build instructions) and should feel comfortable with the basic data types and main headers in lighttpd:

• buffer (buffer.h)
• array (array.h)
• chunk (chunk.h)
• request (request.h)
• global structures (base.h)

Next read the server internals:

• The State Engine of lighttpd
• Plugin Interface

Review some simple modules, such as mod_access.c or mod_staticfile.c for a basic idea of how the modules work.

The Skeleton¶

A good starting point for writing your own plugin is the shipped mod_skeleton.c which just contains a basic skeleton. To turn mod_skeleton into a useful plugin take your favorite editor and replace all occurrences of the word '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 = $(common_module_ldflags)
mod_counter_la_LIBADD = $(common_libadd)

Call make and if all goes well, src/mod_counter.la and src/mod_counter.lo files will be in your build directory and the module will be linked in src/.libs/mod_counter.so

Aside: while you are developing you might choose to use an alternative path prefix into which to install all files, as you don't want to interfere with the real installation:

$ ./configure --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.
(lighttpd source code and build instructions)

The code layout¶

Now take a look at your 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 once the plugin is registered into the server

plugin_config¶

Every plugin can opt-in to handle conditionals from the global configfile and store the different settings in a by-condition plugin_config. This struct is linked in the next plugin-wide struct: plugin_data

plugin_data¶

Each plugin has some local data which only belongs to the plugin (like the config and some temporary buffers).

handler_ctx¶

If a plugin has to store connection specific information, you need another structure with one entry per connection. Take a look at mod_rewrite as an example.

template 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 initialize the plugin itself and returns 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 config file is parsed, each plugin gets the chance to fetch its config-values from the config and verify it internally. A config_plugin_keys_t struct contains the config-key and the type you expect. Don't forget that the last entry of the struct should contain a NULL name to mark the end.

If you don't care about conditionals, the set_defaults function is quite simple:

• set the destinations of the config_plugin_keys_t
• call config_plugin_values_init()

conditionals¶

The patch function sets the basic defaults and applies the necessary modifications for the currently valid conditionals.

Don't forget to check if the patched config makes sense when you use it.

The patch functions have to be called as soon as one of the work-handlers is called (like _uri_handler and friends).

        mod_counter_patch_config(r, p);

return values¶

In most cases, you will only work with HANDLER_GO_ON, HANDLER_FINISHED and HANDLER_ERROR.

HANDLER_GO_ON is returned in most of the cases when you want another plugin to have a chance 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 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 to signal that everything is ready to serve the request like

• HTTP status code r->http_status = xxx has been set
• content has been generated and r->resp_body_finished = 1 has been set

HANDLER_WAIT_FOR_EVENT and HANDLER_WAIT_FOR_FD should be returned if you are not finished yet and have to wait for an 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.