mod_core (lua)

mod_core.lua provides some useful helpers written in lua

Install

By default distributions (and make install) should provide the necessary files; but you can always find them in the contrib folder:

core.lua
core__cached_html.lua
core__xsendfile.lua

That way you can modify them for your own needs if you have to (although it is recommended to change the names of the files and the actions, so you don’t get conflicts).

lighttpd should search for core.lua in the correct (install) locations, so you don’t need the absolute path here.

core.wsgi (action)

Splits the url into SCRIPT_NAME (the subdirectory a web application is mounted at) and PATH_INFO (the path the web application should route)

core.wsgi (prefix, action);

prefix: URL prefix ("subdirectory") the web application is mounted at
action: action block connecting to the wsgi backend

See Howto WSGI for an example.

WSGI applications expect the url to be split into SCRIPT_NAME and PATH_INFO (CGI environment variables); SCRIPT_NAME is their “application root”, and PATH_INFO the requested resource in the application.
By default, lighttpd uses an empty PATH_INFO (unless you used the “pathinfo;” action, but this doesn’t help as we’re not dealing with static files here).

Important: WSGI is an “extension” of CGI; it doesn’t specify a transport protocol, you can use it with plain CGI, FastCGI or SCGI (or anything else that supports the basic CGI protocol)

Example

Example: Trac in /trac, listening via FastCGI on unix:/var/run/lighttpd/trac.socket.

setup {
	module_load ("mod_lua", "mod_fastcgi");
	lua.plugin "core.lua";
}
core.wsgi ( "/trac", { fastcgi "unix:/var/run/lighttpd/trac.socket"; } );

core.cached_html (action)

try to find a file for the current url with ".html" suffix, if we couldn't find a static file for the url yet and the url doesn't already have the ".html" suffix.

core.cached_html;

Example

setup {
	module_load "mod_lua";
	lua.plugin "core.lua";
}
docroot "/some/dynamic/app/public";
core.cached_html;
if physical.is_file {
	header.add ("X-cleanurl", "hit");
} else {
	header.add ("X-cleanurl", "miss");
	fastcgi "/var/run/lighttpd/dynamic-app.sock";
}

core.xsendfile (action)

provides a simple X-Sendfile feature; send a "X-Sendfile: /path/to/file" response header from your backend

core.xsendfile docroot;

docroot: (optional) doc-root the files has be in

Example

setup {
	module_load ("mod_lua", "mod_fastcgi");
	lua.plugin "core.lua";
}
fastcgi "/var/run/lighttpd/dynamic-app.sock";
core.xsendfile "/some/dynamic/app/";

auth.require_user (action)

require a specific authenticated user

auth.require_user userlist;

userlist: list of usernames to allow

This helper constructs a regular expression to match against request.environment[“REMOTE_USER”], so the example below is the same as:

auth.plain [ "method" => "basic", "realm" => "test", "file" => "/etc/lighttpd2/test.plain" ]; if req.env["REMOTE_USER"] !~ "^(foo1|foo2)$" { auth.deny; }

This action uses lua only to create the action, no lua is executed to handle requests in this case.

Be careful: the empty username matches unauthenticated users.

Example

setup {
	module_load "mod_lua";
	lua.plugin "core.lua";
}
auth.plain [ "method" => "basic", "realm" => "test", "file" => "/etc/lighttpd2/test.plain" ];
auth.require_user ("foo1", "foo2");