Wiki Navigation

Error: Failed to load processor TracNav

No macro or processor named 'TracNav' found

Plugin Interface

Module: core

Table of Contents

Description

Plugins allow you to enhance the functionality of lighttpd without changing the core of the webserver. They can be loaded at startup time and can change virtually any aspect of the behaviour of the webserver.

Plugin Entry Points

lighttpd has 16 hooks which are used in different states of the execution of the request:

Serverwide hooks

init:	called when the plugin is loaded
cleanup:	called when the plugin is unloaded
set_defaults:	called when the configuration has to be processed
handle_trigger:	called once a second
handle_sighup:	called when the server received a SIGHUP

Connectionwide hooks

Most of these hooks are called in http_response_prepare() after some fields in the connection structure are set.

handle_uri_raw:

called after uri.path_raw, uri.authority and uri.scheme are set

handle_uri_clean:

called after uri.path (a clean URI without .. and %20) is set

handle_docroot:

called at the end of the logical path handle to get a docroot

handle_subrequest_start:

called if the physical path is set up and checked

handle_subrequest:

called at the end of http_response_prepare()

handle_physical_path:

called after the physical path is created and no other handler is found for this request

handle_request_done:

called when the request is done

handle_connection_close:

called if the connection has to be closed

handle_joblist:

called after the connection_state_engine is left again and plugin internal handles have to be called

connection_reset:

called if the connection structure has to be cleaned up

Plugin Interface

*_plugin_init

Every plugin has a uniquely-named function which is called after the plugin is loaded. It is used to set up the plugin structure with some useful data:

name of the plugin name
all hooks

The field data and lib should not be touched in the init function. lib is the library handler from dlopen and data will be the storage of the internal plugin data.

returns:	0 (not handled)

init

The first real call of a plugin function is the init hook which is used to set up the internal plugin data. The internal plugin is assigned the data field mentioned in the *_plugin_init description.

returns:	a pointer to the internal plugin data.

cleanup

The cleanup hook is called just before the plugin is unloaded. It is meant to free all buffers allocated in init or somewhere else in the plugin which are still not freed and to close all handles which were opened and are not closed yet.

returns:	HANDLER_GO_ON if ok (not handled)

set_defaults

set_defaults is your entry point into the configfile parsing. It should pass a list of options to config_insert_values and check if the plugin configuration is valid. If it is not valid yet, it should set useful defaults or return with HANDLER_ERROR and an error message.

returns:

HANDLER_GO_ON if ok

HANDLER_ERROR will terminate lighttpd