Project

General

Profile

Plugin Interface

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

Connectionwide hooks

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

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 qlib@ 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

connection_reset

called at the end of each request

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error

handle_trigger

called once a second

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error

handle_sighup

called if a SIGHUP is received (cycling logfiles, ...)

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error

handle_uri_raw

called after uri_raw is set

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_uri_clean

called after uri.path is set

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_docroot

called when a docroot is needed

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_subrequest_start

called after physical.path is set

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_subrequest

called if subrequest_start requested a COMEBACK or a WAIT_FOR_EVENT

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_physical_path

called after physical.path is set

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_FINISHED if the final output is prepared
  • HANDLER_ERROR on error

handle_request_done

called at the end of the request (logging, statistics, ...)

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error

handle_connection_close

called if the connection is terminated

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error

handle_joblist

called if the state of the connection has changed

returns:
  • HANDLER_GO_ON if ok
  • HANDLER_ERROR on error