Module Apache mod_lua

Langues Disponibles: en | + fr

Cette traduction peut être périmée. Vérifiez la version + anglaise pour les changements récents.

+ + + + +

Description:	Fournit des points d'entrée Lua dans différentes parties du +traitement des requêtes httpd
Statut:	Expérimental
Identificateur de Module:	lua_module
Fichier Source:	mod_lua.c
Compatibilité:	versions 2.3 et supérieures

Sommaire

+ +

Ce module permet d'ajouter au serveur des extensions sous forme de +scripts écrits dans le langage de programmation Lua. +mod_lua fournit de nombreuses extensions +(hooks) disponibles avec les modules natifs du serveur HTTP Apache, +comme les associations de requêtes à des fichiers, la génération de +réponses dynamiques, le contrôle d'accès, l'authentification et +l'autorisation.

+ +

Vous trouverez davantage d'informations à propos du langage de +programmation Lua sur le site web de +Lua.

+ +

mod_lua est encore au stade expérimental. Son mode +d'utilisation et son comportement pourront changer à tout moment jusqu'à +ce qu'il passe au stade stable, et ce même entre deux versions stables +2.4.x. N'oublez pas de consulter le fichier CHANGES avant toute mise à +jour.

+ +

Configuration de base

+ +

La directive de base pour le chargement du module est

+ +

+ LoadModule lua_module modules/mod_lua.so +

+ +

+mod_lua fournit un gestionnaire nommé +lua-script qui peut être utilisé avec une directive +AddHandler :

+ +

+AddHandler lua-script .lua +

+ +

+Ceci aura pour effet de faire traiter les requêtes pour les fichiers +dont l'extension est .lua par mod_lua en +invoquant cette fonction de gestion de fichier. +

+ +

Pour plus de détails, voir la directive +LuaMapHandler. +

Ecrire des gestionnaires

Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de +point d'accroche (hook) spécifique responsable de la génération de la +réponse. mod_proxy, mod_cgi et +mod_status sont des exemples de modules comportant un +gestionnaire.

+ +

mod_lua cherche toujours à invoquer une fonction Lua pour le +gestionnaire, plutôt que de simplement évaluer le corps d'un script dans +le style de CGI. Une fonction de gestionnaire se présente comme suit :

+ +

example.lua

+-- exemple de gestionnaire
+
+require "string"
+
+--[[
+     Il s'agit du nom de méthode par défaut pour les gestionnaires Lua ;
+     voir les noms de fonctions optionnels dans la directive
+     LuaMapHandler pour choisir un point d'entrée différent.
+--]]
+function handle(r)
+    r.content_type = "text/plain"
+    r:puts("Hello Lua World!\n")
+
+    if r.method == 'GET' then
+        for k, v in pairs( r:parseargs() ) do
+            r:puts( string.format("%s: %s", k, v) )
+        end
+    elseif r.method == 'POST' then
+        for k, v in pairs( r:parsebody() ) do
+            r:puts( string.format("%s: %s", k, v) )
+        end
+    else
+        r:puts("unknown HTTP method " .. r.method)
+    end
+end
+

+ +

+Ce gestionnaire se contente d'afficher les arguments codés d'un uri ou +d'un formulaire dans un page au format texte. +

+ +

+Cela signifie que vous pouvez (et êtes encouragé à) avoir plusieurs +gestionnaires (ou points d'entrée, ou filtres) dans le même script. +

+ +

Ecriture de fonctions d'accroche +(hooks)

+ +

Les fonctions d'accroche déterminent la manière dont les modules (et +les scripts Lua) participent au traitement des requêtes. Chaque type +d'accroche proposé par le serveur a un rôle spécifique, comme +l'association de requêtes au système de fichiers, le contrôle d'accès, +ou la définition de types MIME. Il existe aussi des accroches à usage +général qui s'exécutent simplement à des moments opportuns du cycle +de vie de la requête.

+ +

Les fonctions d'accroche acceptent l'objet de la requête comme seul +et unique argument. Elles peuvent renvoyer une valeur, selon la +fonction, mais il s'agit en général d'un +code d'état HTTP ou des valeurs OK, DONE, ou DECLINED, +que vous pouvez écrire dans lua sous la forme apache2.OK, +apache2.DONE, ou apache2.DECLINED.

+ +

translate_name.lua

+-- exemple d'accroche qui réécrit un URI en chemin du système de
+fichiers.
+
+require 'apache2'
+
+function translate_name(r)
+    if r.uri == "/translate-name" then
+        r.filename = r.document_root .. "/find_me.txt"
+        return apache2.OK
+    end
+    -- on ne gère pas cette URL et on donne sa chance à un autre module
+    return apache2.DECLINED
+end
+

+ +

translate_name2.lua

+--[[ exemple d'accroche qui réécrit un URI vers un autre URI. Il renvoie
+	un apache2.DECLINED pour permettre à un autre interpréteur d'URL de
+	travailler sur la substitution, y compris l'accroche translate_name
+	de base dont les tables de correspondances se basent sur DocumentRoot.
+
+     Note: actuellement, il est impossible de prévoir si cette action
+     s'exécute avant ou après mod_alias.
+--]]
+
+require 'apache2'
+
+function translate_name(r)
+    if r.uri == "/translate-name" then
+        r.uri = "/find_me.txt"
+        return apache2.DECLINED
+    end
+    return apache2.DECLINED
+end
+

Structures de données

+ +

request_rec

request_rec est considérée en tant que donnée utilisateur. + Elle possède une métatable qui vous permet d'accomplir des + choses intéressantes. Pour la plus grande partie, elle possède + les mêmes champs que la structure request_rec (voir httpd.h en + attendant que cette documentation soit plus complète), la + plupart d'entre eux étant accessibles en lecture et écriture (le + contenu des champs de la table peut être modifié, mais les + champs eux-mêmes ne peuvent pas être établis en tant que tables + distinctes).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Nom	Type Lua	Modifiable
`ap_auth_type`	string	non
`args`	string	oui
`assbackwards`	boolean	non
`canonical_filename`	string	non
`content_encoding`	string	non
`content_type`	string	oui
`document_root`	string	non
`err_headers_out`	table	non
`filename`	string	oui
`handler`	string	oui
`headers_in`	table	oui
`headers_out`	table	oui
`hostname`	string	non
`method`	string	non
`notes`	table	oui
`path_info`	string	non
`protocol`	string	non
`proxyreq`	string	oui
`range`	string	non
`subprocess_env`	table	oui
`status`	number	oui
`the_request`	string	non
`unparsed_uri`	string	non
`uri`	string	oui
`user`	string	oui

+ +

La structure request_rec possède (au minimum) les méthodes + suivantes :

+ +

+ r:addoutputfilter(name|function) -- ajoute un filtre en sortie +

+ +

+ r:parseargs() -- renvoie une table lua contenant les arguments + de la chaîne de paramètres de la requête +

+ +

+ r:parsebody() -- interprète le corps de la requête en tant que + méthode POST et renvoie une table lua +

+ +

+ r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la réponse +

+ +

+ r:write("une simple chaîne") -- affichage dans le + corps de la réponse +

+ +

Fonctions de journalisation

+ +

+ -- exemples de messages de journalisation + r:trace1("Ceci est un message de journalisation de niveau + trace") -- les niveaux valides vont de trace1 à trace8 + r:debug("Ceci est un message de journalisation de niveau debug") + r:info("Ceci est un message de journalisation de niveau info") + r:notice("Ceci est un message de journalisation de niveau notice") + r:warn("Ceci est un message de journalisation de niveau warn") + r:err("Ceci est un message de journalisation de niveau err") + r:alert("Ceci est un message de journalisation de niveau alert") + r:crit("Ceci est un message de journalisation de niveau crit") + r:emerg("Ceci est un message de journalisation de niveau emerg") +

+ +

Paquet apache2

Le paquet nommé apache2 est fourni avec (au minimum) le +contenu suivant :

apache2.OK: Constante interne OK. Les gestionnaires renverront cette valeur + s'ils ont traité la requête.
apache2.DECLINED: Constante interne DECLINED. Les gestionnaires renverront cette + valeur s'ils n'ont pas l'intention de traiter la requête.
apache2.DONE: Constante interne DONE.
apache2.version: Chaîne contenant la version du serveur HTTP Apache
apache2.HTTP_MOVED_TEMPORARILY: Code d'état HTTP
apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE: Constantes internes utilisées par mod_proxy

Les autres codes d'état HTTP ne sont pas encore implémentés.

LuaCodeCache Directive

+ + + + + + + + +

Description:	Configure le cache de code compilé.
Syntaxe:	`LuaCodeCache stat\|forever\|never`
Défaut:	`LuaCodeCache stat`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

+ Cette directive permet de définir le comportement du cache de code + en mémoire. La valeur par défaut est stat ; dans ce cas, le script + du niveau le plus haut (et pas les scripts inclus) est vérifié à + chaque fois que ce fichier est nécessaire, et est rechargé si la + date de modification est plus récente que celle du script déjà + chargé. Les autres valeurs permettent respectivement de garder le + fichier en cache perpétuellement (forever - jamais vérifié ni + remplacé), ou de ne jamais le mettre en cache (never).

+ +

En général, les valeurs stat et forever sont utilisées pour un + serveur en production, et les valeurs stat ou never pour un serveur + en développement.

+ +

Exemples :

+ LuaCodeCache stat + LuaCodeCache forever + LuaCodeCache never +

+ + +

LuaHookAccessChecker Directive

+ + + + + + + + +

Description:	Fournit un point d'entrée pour la phase access_checker du +traitement de la requête
Syntaxe:	`LuaHookAccessChecker /chemin/vers/lua/script.lua hook_function_name [early\|late]`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua
Compatibilité:	Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.

LuaHookAuthChecker Directive

+ + + + + + + + +

Description:	Fournit un point d'entrée pour la phase auth_checker du +traitement de la requête
Syntaxe:	`LuaHookAuthChecker /chemin/vers/lua/script.lua hook_function_name [early\|late]`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua
Compatibilité:	Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.

Invoque une fonction lua au cours de la phase auth_checker du +traitement de la requête. Cette directive peut s'utiliser pour +implémenter une vérification arbitraire de l'authentification et de +l'autorisation. Voici un exemple très simple : +

+require 'apache2'
+
+-- fonction d'accroche authcheck fictive
+-- Si la requête ne contient aucune donnée d'authentification, l'en-tête
+-- de la réponse est défini et un code 401 est renvoyé afin de demander au
+-- navigateur d'effectuer une authentification basique. Si la requête
+-- comporte des données d'authentification, elles ne sont pas vraiment
+-- consultées, mais on admet la prise en compte de l'utilisateur 'foo' et
+-- on la valide. On vérifie ensuite si l'utilisateur est bien 'foo' et on
+-- accepte la requête.
+function authcheck_hook(r)
+
+   -- recherche des informations d'authentification
+   auth = r.headers_in['Authorization']
+   if auth ~= nil then
+     -- définition d'un utilisateur par défaut
+     r.user = 'foo'
+   end
+
+   if r.user == nil then
+      r:debug("authcheck: user is nil, returning 401")
+      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+      return 401
+   elseif r.user == "foo" then
+      r:debug('user foo: OK')
+   else
+      r:debug("authcheck: user='" .. r.user .. "'")
+      r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
+      return 401
+   end
+   return apache2.OK
+end
+

Ordonnancement

Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.

+ +

LuaHookCheckUserID Directive

+ + + + + + + + +

Description:	Fournit un point d'entrée pour la phase check_user_id du +traitement de la requête
Syntaxe:	`LuaHookCheckUserID /chemin/vers/lua/script.lua hook_function_name [early\|late]`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua
Compatibilité:	Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.

...

Ordonnancement

Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.

+ +

LuaHookFixups Directive

+ + + + + + + +

Description:	Fournit un point d'entrée pour la phase de correction du +traitement de la requête
Syntaxe:	`LuaHookFixups /chemin/vers/lua/script.lua hook_function_name`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

+ Idem LuaHookTranslateName, mais s'exécute durant la phase de + correction. +

+ +

LuaHookInsertFilter Directive

+ + + + + + + +

Description:	Fournit un point d'entrée pour la phase insert_filter du +traitement de la requête
Syntaxe:	`LuaHookInsertFilter /chemin/vers/lua/script.lua hook_function_name`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Non encore implémenté

LuaHookMapToStorage Directive

+ + + + + + + +

Description:	Fournit un point d'entrée pour la phase map_to_storage du +traitement de la requête
Syntaxe:	`LuaHookMapToStorage /chemin/vers/lua/script.lua hook_function_name`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

...

LuaHookTranslateName Directive

+ + + + + + + + +

Description:	Fournit un point d'entrée à la phase du nom de +traduction du traitement de la requête
Syntaxe:	`LuaHookTranslateName /chemin/vers/lua/script.lua nom_fonction_hook [early\|late]`
Contexte:	configuration du serveur, serveur virtuel, répertoire
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua
Compatibilité:	Le troisième argument optionnel est disponible depuis la +version 2.3.15 du serveur HTTP Apache.

+ Cette directive permet d'ajouter un point d'entrée (à + APR_HOOK_MIDDLE) à la phase du nom de traduction du traitement de la + requête. La fonction hook accepte un seul argument, le request_rec, + et doit renvoyer un code d'état qui est soit un code d'erreur HTTP, + ou une constante définie dans le module apache2 : apache2.OK, + apache2.DECLINED, ou apache2.DONE.

+ +

Pour ceux qui ne sont pas familiers avec les points d'entrée + (hook), en gros, chaque hook sera invoqué jusqu'à ce que l'un + d'entre eux renvoie apache2.OK. Si un hook n'effectuer pas la + traduction, il doit juste renvoyer apache2.DECLINED. Si le + traitement de la requête doit être interrompu, la valeur renvoyée + doit être apache2.DONE.

+ +

Exemple :

+ +

+# httpd.conf
+LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
+
+-- /scripts/conf/hooks.lua --
+require "apache2"
+function silly_mapper(r)
+    if r.uri == "/" then
+        r.filename = "/var/www/home.lua"
+        return apache2.OK
+    else
+        return apache2.DECLINED
+    end
+end
+

+ +

Contexte

Cette directive ne peut être + utilisée ni à l'intérieur d'une section <Directory> ou <Files>, ni dans un fichier htaccess.

+ +

Ordonnancement

Les arguments optionnels + "early" ou "late" permettent de contrôler le moment auquel ce script + s'exécute par rapport aux autres modules.

+ +

LuaHookTypeChecker Directive

+ + + + + + + +

Description:	Fournit un point d'entrée pour la phase type_checker du +traitement de la requête
Syntaxe:	`LuaHookTypeChecker /chemin/vers/lua/script.lua hook_function_name`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

...

LuaInherit Directive

+ + + + + + + + + +

Description:	Contrôle la manière dont les sections de configuration +parentes sont fusionnées dans les enfants
Syntaxe:	`LuaInherit none\|parent-first\|parent-last`
Défaut:	`LuaInherit parent-first`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua
Compatibilité:	Versions 2.4.0 et supérieures

Par défaut, si des directives LuaHook* se trouvent dans + des sections de configuration Directory ou Location qui se + chevauchent, les scripts + définis dans les sections les plus spécifiques s'exécutent + après ceux définis dans les sections plus génériques + (LuaInherit parent-first). Vous pouvez inverser cet ordre, ou faire + en sorte que le contexte parent ne s'applique pas du tout.

+ +

Jusqu'aux versions 2.3.x, le comportement par défaut consistait à + ignorer les directives LuaHook* situées dans les sections de + configuration parentes.

LuaMapHandler Directive

+ + + + + + + +

Description:	Met en correspondance un chemin avec un gestionnaire lua
Syntaxe:	`LuaMapHandler modele-uri /chemin/vers/lua/script.lua +[nom-fonction]`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Cette directive permet de faire correspondre un modèle d'uri avec + une fonction de gestionnaire située dans un fichier spécifique. Elle + utilise les expressions rationnelles PCRE pour mettre en + correspondance l'uri, et supporte les groupes de correspondance + d'interpolation dans le chemin du fichier et le nom de la fonction. + Prenez garde aux problèmes de sécurité en écrivant vos expressions + rationnelles.

Exemples :

+ LuaMapHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2 +

Cette directive va faire correspondre des uri comme + /photos/show?id=9 au fichier /scripts/photos.lua, et invoquera la + fonction de gestionnaire handle_show au niveau de la vm lua + après chargement de ce fichier.

+ +

+ LuaMapHandler /bingo /scripts/wombat.lua +

Cette directive invoquera la fonction "handle" qui est la + valeur par défaut si aucun nom de fonction spécifique n'est + spécifié.

+ +

LuaPackageCPath Directive

+ + + + + + + +

Description:	Ajoute un répertoire au package.cpath de lua
Syntaxe:	`LuaPackageCPath /chemin/vers/include/?.soa`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Cette directive permet d'ajouter un chemin à la liste des chemins + de recherche des bibliothèques partagées de lua. Ceci modifie le + package.cpath dans les vms lua.

+ + +

LuaPackagePath Directive

+ + + + + + + +

Description:	Ajoute un répertoire au package.path de lua
Syntaxe:	`LuaPackagePath /chemin/vers/include/?.lua`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Cette directive permet d'ajouter un chemin à la liste des + chemins de recherche du module lua. Elle suit les mêmes conventions + que lua. Ceci modifie le package.path dans les vms lua.

+ +

Exemples :

+ LuaPackagePath /scripts/lib/?.lua + LuaPackagePath /scripts/lib/?/init.lua +

+ +

LuaQuickHandler Directive

+ + + + + + + +

Description:	Fournit un point d'entrée pour la gestion rapide du +traitement de la requête
Syntaxe:
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

...

Contexte

Cette directive ne peut être + utilisée ni à l'intérieur d'une section <Directory> ou <Files>, ni dans un fichier htaccess.

+ +

LuaRoot Directive

+ + + + + + + +

Description:	Spécifie le chemin de base pour la résolution des chemins +relatifs dans les directives de mod_lua
Syntaxe:	`LuaRoot /chemin/vers/un/répertoire`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Cette directive permet de spécifier le chemin de base qui sera + utilisé pour évaluer tous les chemins relatifs dans mod_lua. En + l'absence de cette directive, les chemins relatifs sont résolus par + rapport au répertoire de travail courant, ce qui ne sera pas + toujours approprié pour un serveur.

+ +

LuaScope Directive

+ + + + + + + + +

Description:	Une valeur parmi once, request, conn, server -- la valeur +par défaut est once
Syntaxe:	`LuaScope once\|request\|conn\|server [max\|min max]`
Défaut:	`LuaScope once`
Contexte:	configuration du serveur, serveur virtuel, répertoire, .htaccess
AllowOverride:	All
Statut:	Expérimental
Module:	mod_lua

Cette directive permet de spécifier la durée de vie de + l'interpréteur Lua qui sera utilisé dans ce "répertoire". La valeur + par défaut est "once".

+ +

once:: utilise l'interpréteur une fois.
request:: utilise l'interpréteur pour traiter tout ce + qui est basé sur le même fichier dans la requête, et qui se trouve + aussi dans la portée de la requête.
conn:: idem request, mais attaché à connection_rec
server:: Le comportement est ici différent, car la + portée du serveur présente une durée de vie assez longue, et + plusieurs threads vont partager le même server_rec. Pour gérer tout + ceci, les interpréteurs sont stockés dans une liste de ressources + apr. Les arguments min et max ont été prévus pour spécifier une + taille de jeu, mais sont inutilisés pour le moment.

+ +

Module Apache mod_lua

Sommaire

Directives

Sujets

Configuration de base

Ecrire des gestionnaires

example.lua

Ecriture de fonctions d'accroche +(hooks)

translate_name.lua

translate_name2.lua

Structures de données

Fonctions de journalisation

Paquet apache2

LuaCodeCache Directive

Exemples :

LuaHookAccessChecker Directive

LuaHookAuthChecker Directive

Ordonnancement

LuaHookCheckUserID Directive

Ordonnancement

LuaHookFixups Directive

LuaHookInsertFilter Directive

LuaHookMapToStorage Directive

LuaHookTranslateName Directive

Contexte

Ordonnancement

LuaHookTypeChecker Directive

LuaInherit Directive

LuaMapHandler Directive

Exemples :

LuaPackageCPath Directive

LuaPackagePath Directive

Exemples :

LuaQuickHandler Directive

Contexte

LuaRoot Directive

LuaScope Directive