granicus.if.org Git - apache/blob - docs/manual/mod/mod_lua.xml.fr

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
   4 <!-- English Revision : 1351020 -->
   5 <!-- French translation : Lucien GENTIS -->
   6 <!-- Reviewed by : Vincent Deffontaines -->
   7
   8 <!--
   9  Licensed to the Apache Software Foundation (ASF) under one or more
  10  contributor license agreements.  See the NOTICE file distributed with
  11  this work for additional information regarding copyright ownership.
  12  The ASF licenses this file to You under the Apache License, Version 2.0
  13  (the "License"); you may not use this file except in compliance with
  14  the License.  You may obtain a copy of the License at
  15
  16      http://www.apache.org/licenses/LICENSE-2.0
  17
  18  Unless required by applicable law or agreed to in writing, software
  19  distributed under the License is distributed on an "AS IS" BASIS,
  20  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21  See the License for the specific language governing permissions and
  22  limitations under the License.
  23 -->
  24
  25 <modulesynopsis metafile="mod_lua.xml.meta">
  26
  27 <name>mod_lua</name>
  28
  29 <description>Fournit des points d'entr&eacute;e Lua dans diff&eacute;rentes parties du
  30 traitement des requ&ecirc;tes httpd</description>
  31 <status>Experimental</status>
  32 <sourcefile>mod_lua.c</sourcefile>
  33 <identifier>lua_module</identifier>
  34 <compatibility>versions 2.3 et sup&eacute;rieures</compatibility>
  35
  36 <summary>
  37 <p>Ce module permet d'ajouter au serveur des extensions sous forme de
  38 scripts &eacute;crits dans le langage de programmation Lua.
  39 <module>mod_lua</module> fournit de nombreuses extensions
  40 (hooks) disponibles avec les modules natifs du serveur HTTP Apache,
  41 comme les associations de requ&ecirc;tes &agrave; des fichiers, la g&eacute;n&eacute;ration de
  42 r&eacute;ponses dynamiques, le contr&ocirc;le d'acc&egrave;s, l'authentification et
  43 l'autorisation.</p>
  44
  45 <p>Vous trouverez davantage d'informations &agrave; propos du langage de
  46 programmation Lua sur <a href="http://www.lua.org/">le site web de
  47 Lua</a>.</p>
  48
  49 <note><code>mod_lua</code> est encore au stade exp&eacute;rimental. Son mode
  50 d'utilisation et son comportement pourront changer &agrave; tout moment jusqu'&agrave;
  51 ce qu'il passe au stade stable, et ce m&ecirc;me entre deux versions stables
  52 2.4.x. N'oublez pas de consulter le fichier CHANGES avant toute mise &agrave;
  53 jour.</note>
  54
  55 </summary>
  56
  57 <section id="basicconf"><title>Configuration de base</title>
  58
  59 <p>La directive de base pour le chargement du module est</p>
  60
  61 <highlight language="config">
  62     LoadModule lua_module modules/mod_lua.so
  63 </highlight>
  64
  65 <p>
  66 <code>mod_lua</code> fournit un gestionnaire nomm&eacute;
  67 <code>lua-script</code> qui peut &ecirc;tre utilis&eacute; avec une directive
  68 <code>AddHandler</code> :</p>
  69
  70 <highlight language="config">
  71 AddHandler lua-script .lua
  72 </highlight>
  73
  74 <p>
  75 Ceci aura pour effet de faire traiter les requ&ecirc;tes pour les fichiers
  76 dont l'extension est <code>.lua</code> par <code>mod_lua</code> en
  77 invoquant cette fonction de <code>gestion</code> de fichier.
  78 </p>
  79
  80 <p>Pour plus de d&eacute;tails, voir la directive
  81 <directive>LuaMapHandler</directive>.
  82  </p>
  83 </section>
  84
  85 <section id="writinghandlers"><title>Ecrire des gestionnaires</title>
  86 <p>Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de
  87 point d'accroche (hook) sp&eacute;cifique responsable de la g&eacute;n&eacute;ration de la
  88 r&eacute;ponse. <module>mod_proxy</module>, <module>mod_cgi</module> et
  89 <module>mod_status</module> sont des exemples de modules comportant un
  90 gestionnaire.</p>
  91
  92 <p><code>mod_lua</code> cherche toujours &agrave; invoquer une fonction Lua pour le
  93 gestionnaire, plut&ocirc;t que de simplement &eacute;valuer le corps d'un script dans
  94 le style de CGI. Une fonction de gestionnaire se pr&eacute;sente comme suit :</p>
  95
  96
  97 <highlight language="lua">
  98 <strong>example.lua</strong>
  99 -- exemple de gestionnaire
 100
 101 require "string"
 102
 103 --[[
 104      Il s'agit du nom de m&eacute;thode par d&eacute;faut pour les gestionnaires Lua ;
 105      voir les noms de fonctions optionnels dans la directive
 106      LuaMapHandler pour choisir un point d'entr&eacute;e diff&eacute;rent.
 107 --]]
 108 function handle(r)
 109     r.content_type = "text/plain"
 110     r:puts("Hello Lua World!\n")
 111
 112     if r.method == 'GET' then
 113         for k, v in pairs( r:parseargs() ) do
 114             r:puts( string.format("%s: %s\n", k, v) )
 115         end<!--
 116 /* Not supported yet */
 117     elseif r.method == 'POST' then
 118         for k, v in pairs( r:parsebody() ) do
 119             r:puts( string.format("%s: %s\n", k, v) )
 120         end
 121 -->
 122     else
 123         r:puts("Unsupported HTTP method " .. r.method)
 124     end
 125 end
 126 </highlight>
 127
 128 <p>
 129 Ce gestionnaire se contente d'afficher les arguments cod&eacute;s d'un uri ou
 130 d'un formulaire dans un page au format texte.
 131 </p>
 132
 133 <p>
 134 Cela signifie que vous pouvez (et &ecirc;tes encourag&eacute; &agrave;) avoir plusieurs
 135 gestionnaires (ou points d'entr&eacute;e, ou filtres) dans le m&ecirc;me script.
 136 </p>
 137
 138 </section>
 139 <section id="writingauthzproviders">
 140 <title>Ecriture de fournisseurs d'autorisation</title>
 141
 142 <p><module>mod_authz_core</module> fournit une interface d'autorisation
 143 de haut niveau bien plus facile &agrave; utiliser que dans les hooks
 144 correspondants. Le premier argument de la directive <directive
 145 module="mod_authz_core">Require</directive> permet de sp&eacute;cifier le
 146 fournisseur d'autorisation &agrave; utiliser. Pour chaque directive <directive
 147 module="mod_authz_core">Require</directive>,
 148 <module>mod_authz_core</module> appellera le fournisseur d'autorisation
 149 sp&eacute;cifi&eacute;, le reste de la ligne constituant les param&egrave;tres. Le
 150 fournisseur consid&eacute;r&eacute; va alors v&eacute;rifier les autorisations et fournir le
 151 r&eacute;sultat dans une valeur de retour.</p>
 152
 153 <p>En g&eacute;n&eacute;ral, le fournisseur authz est appel&eacute; avant l'authentification.
 154 S'il doit conna&icirc;tre le nom d'utilisateur authentifi&eacute; (ou si
 155 l'utilisateur est appel&eacute; &agrave; &ecirc;tre authentifi&eacute;), le fournisseur doit
 156 renvoyer <code>apache2.AUTHZ_DENIED_NO_USER</code>, ce qui va
 157 d&eacute;clancher le processus d'authentification et un deuxi&egrave;me appel du
 158 fournisseur authz.</p>
 159
 160 <p>La fonction du fournisseur authz ci-dessous accepte deux arguments,
 161 une adresse IP et un nom d'utilisateur. Elle autorise l'acc&egrave;s dans le
 162 cas o&ugrave; la requ&ecirc;te provient de l'adresse IP sp&eacute;cifi&eacute;e, ou si
 163 l'utilisateur authentifi&eacute; correspond au second argument :</p>
 164
 165 <highlight language="lua">
 166 <strong>authz_provider.lua</strong>
 167
 168 require 'apache2'
 169
 170 function authz_check_foo(r, ip, user)
 171     if r.useragent_ip == ip then
 172         return apache2.AUTHZ_GRANTED
 173     elseif r.user == nil then
 174         return apache2.AUTHZ_DENIED_NO_USER
 175     elseif r.user == user then
 176         return apache2.AUTHZ_GRANTED
 177     else
 178         return apache2.AUTHZ_DENIED
 179     end
 180 end
 181 </highlight>
 182
 183 <p>La configuration suivante enregistre cette fonction en tant que
 184 fournisseur <code>foo</code>, et la configure por l'URL <code>/</code> :</p>
 185 <highlight language="config">
 186 LuaAuthzProvider foo authz_provider.lua authz_check_foo
 187 &lt;Location /&gt;
 188   Require foo 10.1.2.3 john_doe
 189 &lt;/Location&gt;
 190 </highlight>
 191
 192 </section>
 193
 194 <section id="writinghooks"><title>Ecriture de fonctions d'accroche
 195 (hooks)</title>
 196
 197 <p>Les fonctions d'accroche d&eacute;terminent la mani&egrave;re dont les modules (et
 198 les scripts Lua) participent au traitement des requ&ecirc;tes. Chaque type
 199 d'accroche propos&eacute; par le serveur a un r&ocirc;le sp&eacute;cifique, comme
 200 l'association de requ&ecirc;tes au syst&egrave;me de fichiers, le contr&ocirc;le d'acc&egrave;s,
 201 ou la d&eacute;finition de types MIME. Il existe aussi des accroches &agrave; usage
 202 g&eacute;n&eacute;ral qui s'ex&eacute;cutent simplement &agrave; des moments opportuns du cycle
 203 de vie de la requ&ecirc;te.</p>
 204
 205 <p>Les fonctions d'accroche acceptent l'objet de la requ&ecirc;te comme seul
 206 et unique argument. Elles peuvent renvoyer une valeur, selon la
 207 fonction, mais il s'agit en g&eacute;n&eacute;ral d'un
 208 code d'&eacute;tat HTTP ou des valeurs OK, DONE, ou DECLINED,
 209 que vous pouvez &eacute;crire dans lua sous la forme <code>apache2.OK</code>,
 210 <code>apache2.DONE</code>, ou <code>apache2.DECLINED</code>.</p>
 211
 212 <highlight language="lua">
 213 <strong>translate_name.lua</strong>
 214 -- exemple d'accroche qui r&eacute;&eacute;crit un URI en chemin du syst&egrave;me de
 215 fichiers.
 216
 217 require 'apache2'
 218
 219 function translate_name(r)
 220     if r.uri == "/translate-name" then
 221         r.filename = r.document_root .. "/find_me.txt"
 222         return apache2.OK
 223     end
 224     -- on ne g&egrave;re pas cette URL et on donne sa chance &agrave; un autre module
 225     return apache2.DECLINED
 226 end
 227 </highlight>
 228
 229 <highlight language="lua">
 230 <strong>translate_name2.lua</strong>
 231 --[[ exemple d'accroche qui r&eacute;&eacute;crit un URI vers un autre URI. Il renvoie
 232         un apache2.DECLINED pour permettre &agrave; un autre interpr&eacute;teur d'URL de
 233         travailler sur la substitution, y compris l'accroche translate_name
 234         de base dont les tables de correspondances se basent sur DocumentRoot.
 235
 236      Note: actuellement, il est impossible de pr&eacute;voir si cette action
 237      s'ex&eacute;cute avant ou apr&egrave;s mod_alias.
 238 --]]
 239
 240 require 'apache2'
 241
 242 function translate_name(r)
 243     if r.uri == "/translate-name" then
 244         r.uri = "/find_me.txt"
 245         return apache2.DECLINED
 246     end
 247     return apache2.DECLINED
 248 end
 249 </highlight>
 250 </section>
 251
 252 <section id="datastructures"><title>Structures de donn&eacute;es</title>
 253
 254 <dl>
 255 <dt>request_rec</dt>
 256         <dd>
 257         <p>request_rec est consid&eacute;r&eacute;e en tant que donn&eacute;e utilisateur.
 258         Elle poss&egrave;de une m&eacute;tatable qui vous permet d'accomplir des
 259         choses int&eacute;ressantes. Pour la plus grande partie, elle poss&egrave;de
 260         les m&ecirc;mes champs que la structure request_rec (voir httpd.h en
 261         attendant que cette documentation soit plus compl&egrave;te), la
 262         plupart d'entre eux &eacute;tant accessibles en lecture et &eacute;criture (le
 263         contenu des champs de la table peut &ecirc;tre modifi&eacute;, mais les
 264         champs eux-m&ecirc;mes ne peuvent pas &ecirc;tre &eacute;tablis en tant que tables
 265         distinctes).</p>
 266
 267         <table border="1">
 268
 269         <tr>
 270           <th><strong>Nom</strong></th>
 271           <th><strong>Type Lua</strong></th>
 272           <th><strong>Modifiable</strong></th>
 273         </tr>
 274         <tr>
 275           <td><code>ap_auth_type</code></td>
 276           <td>string</td>
 277           <td>non</td>
 278         </tr>
 279         <tr>
 280           <td><code>args</code></td>
 281           <td>string</td>
 282           <td>oui</td>
 283         </tr>
 284         <tr>
 285           <td><code>assbackwards</code></td>
 286           <td>boolean</td>
 287           <td>non</td>
 288         </tr>
 289
 290         <tr>
 291           <td><code>canonical_filename</code></td>
 292           <td>string</td>
 293           <td>non</td>
 294         </tr>
 295         <tr>
 296           <td><code>content_encoding</code></td>
 297           <td>string</td>
 298           <td>non</td>
 299         </tr>
 300         <tr>
 301           <td><code>content_type</code></td>
 302           <td>string</td>
 303           <td>oui</td>
 304         </tr>
 305
 306         <tr>
 307           <td><code>context_prefix</code></td>
 308           <td>string</td>
 309           <td>non</td>
 310         </tr>
 311         <tr>
 312           <td><code>context_document_root</code></td>
 313           <td>string</td>
 314           <td>non</td>
 315         </tr>
 316
 317         <tr>
 318           <td><code>document_root</code></td>
 319           <td>string</td>
 320           <td>non</td>
 321         </tr>
 322         <tr>
 323           <td><code>err_headers_out</code></td>
 324           <td>table</td>
 325           <td>non</td>
 326         </tr>
 327         <tr>
 328           <td><code>filename</code></td>
 329           <td>string</td>
 330           <td>oui</td>
 331         </tr>
 332         <tr>
 333           <td><code>handler</code></td>
 334           <td>string</td>
 335           <td>oui</td>
 336         </tr>
 337         <tr>
 338           <td><code>headers_in</code></td>
 339           <td>table</td>
 340           <td>oui</td>
 341         </tr>
 342         <tr>
 343           <td><code>headers_out</code></td>
 344           <td>table</td>
 345           <td>oui</td>
 346         </tr>
 347         <tr>
 348           <td><code>hostname</code></td>
 349           <td>string</td>
 350           <td>non</td>
 351         </tr>
 352         <tr>
 353         <td><code>log_id</code></td>
 354           <td>string</td>
 355           <td>non</td>
 356         </tr>
 357         <tr>
 358           <td><code>method</code></td>
 359           <td>string</td>
 360           <td>non</td>
 361         </tr>
 362         <tr>
 363           <td><code>notes</code></td>
 364           <td>table</td>
 365           <td>oui</td>
 366         </tr>
 367         <tr>
 368           <td><code>path_info</code></td>
 369           <td>string</td>
 370           <td>non</td>
 371         </tr>
 372         <tr>
 373           <td><code>protocol</code></td>
 374           <td>string</td>
 375           <td>non</td>
 376         </tr>
 377         <tr>
 378           <td><code>proxyreq</code></td>
 379           <td>string</td>
 380           <td>oui</td>
 381         </tr>
 382         <tr>
 383           <td><code>range</code></td>
 384           <td>string</td>
 385           <td>non</td>
 386         </tr>
 387         <tr>
 388           <td><code>subprocess_env</code></td>
 389           <td>table</td>
 390           <td>oui</td>
 391         </tr>
 392         <tr>
 393           <td><code>status</code></td>
 394           <td>number</td>
 395           <td>oui</td>
 396         </tr>
 397         <tr>
 398           <td><code>the_request</code></td>
 399           <td>string</td>
 400           <td>non</td>
 401         </tr>
 402         <tr>
 403           <td><code>unparsed_uri</code></td>
 404           <td>string</td>
 405           <td>non</td>
 406         </tr>
 407         <tr>
 408           <td><code>uri</code></td>
 409           <td>string</td>
 410           <td>oui</td>
 411         </tr>
 412         <tr>
 413           <td><code>user</code></td>
 414           <td>string</td>
 415           <td>oui</td>
 416         </tr>
 417         <tr>
 418           <td><code>useragent_ip</code></td>
 419           <td>string</td>
 420           <td>non</td>
 421         </tr>
 422         </table>
 423
 424         <p>La structure request_rec poss&egrave;de (au minimum) les m&eacute;thodes
 425         suivantes :</p>
 426
 427         <highlight language="lua">
 428         r:addoutputfilter(name|function) -- ajoute un filtre en sortie
 429         </highlight>
 430
 431         <highlight language="lua">
 432         r:parseargs() -- renvoie une table lua contenant la cha&icirc;ne
 433         d'arguments de la requ&ecirc;te
 434         </highlight>
 435 <!--
 436 /* Not supported yet */
 437         <highlight language="lua">
 438         r:parsebody() &dash;- parse the request body as a POST and return  a lua table
 439         </highlight>
 440 -->
 441         <highlight language="lua">
 442         r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la r&eacute;ponse
 443         </highlight>
 444
 445         <highlight language="lua">
 446         r:write("une simple cha&icirc;ne") -- affichage dans le
 447         corps de la r&eacute;ponse
 448         </highlight>
 449         </dd>
 450     </dl>
 451
 452 </section>
 453
 454 <section id="logging"><title>Fonctions de journalisation</title>
 455
 456 <highlight language="lua">
 457         -- exemples de messages de journalisation
 458         r:trace1("Ceci est un message de journalisation de niveau
 459         trace") -- les niveaux valides vont de trace1 &agrave; trace8 <br />
 460         r:debug("Ceci est un message de journalisation de niveau debug")<br />
 461         r:info("Ceci est un message de journalisation de niveau info")<br />
 462         r:notice("Ceci est un message de journalisation de niveau notice")<br />
 463         r:warn("Ceci est un message de journalisation de niveau warn")<br />
 464         r:err("Ceci est un message de journalisation de niveau err")<br />
 465         r:alert("Ceci est un message de journalisation de niveau alert")<br />
 466         r:crit("Ceci est un message de journalisation de niveau crit")<br />
 467         r:emerg("Ceci est un message de journalisation de niveau emerg")<br />
 468 </highlight>
 469
 470 </section>
 471
 472 <section id="apache2"><title>Paquet apache2</title>
 473 <p>Le paquet nomm&eacute; <code>apache2</code> est fourni avec (au minimum) le
 474 contenu suivant :</p>
 475 <dl>
 476   <dt>apache2.OK</dt>
 477   <dd>Constante interne OK. Les gestionnaires renverront cette valeur
 478   s'ils ont trait&eacute; la requ&ecirc;te.</dd>
 479   <dt>apache2.DECLINED</dt>
 480   <dd>Constante interne DECLINED. Les gestionnaires renverront cette
 481   valeur s'ils n'ont pas l'intention de traiter la requ&ecirc;te.</dd>
 482   <dt>apache2.DONE</dt>
 483   <dd>Constante interne DONE.</dd>
 484   <dt>apache2.version</dt>
 485   <dd>Cha&icirc;ne contenant la version du serveur HTTP Apache</dd>
 486   <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
 487   <dd>Code d'&eacute;tat HTTP</dd>
 488   <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
 489   <dd>Constantes internes utilis&eacute;es par <module>mod_proxy</module></dd>
 490 </dl>
 491 <p>Les autres codes d'&eacute;tat HTTP ne sont pas encore impl&eacute;ment&eacute;s.</p>
 492 </section>
 493
 494
 495
 496 <directivesynopsis>
 497 <name>LuaRoot</name>
 498 <description>Sp&eacute;cifie le chemin de base pour la r&eacute;solution des chemins
 499 relatifs dans les directives de mod_lua</description>
 500 <syntax>LuaRoot /chemin/vers/un/r&eacute;pertoire</syntax>
 501 <contextlist><context>server config</context><context>virtual host</context>
 502 <context>directory</context><context>.htaccess</context>
 503 </contextlist>
 504 <override>All</override>
 505
 506 <usage>
 507     <p>Cette directive permet de sp&eacute;cifier le chemin de base qui sera
 508     utilis&eacute; pour &eacute;valuer tous les chemins relatifs dans mod_lua. En
 509     l'absence de cette directive, les chemins relatifs sont r&eacute;solus par
 510     rapport au r&eacute;pertoire de travail courant, ce qui ne sera pas
 511     toujours appropri&eacute; pour un serveur.</p>
 512 </usage>
 513 </directivesynopsis>
 514
 515 <directivesynopsis>
 516 <name>LuaScope</name>
 517 <description>Une valeur parmi once, request, conn, server -- la valeur
 518 par d&eacute;faut est once</description>
 519 <syntax>LuaScope once|request|conn|server [max|min max]</syntax>
 520 <default>LuaScope once</default>
 521 <contextlist><context>server config</context><context>virtual host</context>
 522 <context>directory</context><context>.htaccess</context>
 523 </contextlist>
 524 <override>All</override>
 525
 526 <usage>
 527     <p>Cette directive permet de sp&eacute;cifier la dur&eacute;e de vie de
 528     l'interpr&eacute;teur Lua qui sera utilis&eacute; dans ce "r&eacute;pertoire". La valeur
 529     par d&eacute;faut est "once".</p>
 530
 531    <dl>
 532     <dt>once:</dt> <dd>utilise l'interpr&eacute;teur une fois.</dd>
 533
 534     <dt>request:</dt> <dd>utilise l'interpr&eacute;teur pour traiter tout ce
 535     qui est bas&eacute; sur le m&ecirc;me fichier dans la requ&ecirc;te, et qui se trouve
 536     aussi dans la port&eacute;e de la requ&ecirc;te.</dd>
 537
 538     <dt>conn:</dt> <dd>idem request, mais attach&eacute; &agrave; connection_rec</dd>
 539
 540     <dt>server:</dt>  <dd>Le comportement est ici diff&eacute;rent, car la
 541     port&eacute;e du serveur pr&eacute;sente une dur&eacute;e de vie assez longue, et
 542     plusieurs threads vont partager le m&ecirc;me server_rec. Pour g&eacute;rer tout
 543     ceci, les interpr&eacute;teurs sont stock&eacute;s dans une liste de ressources
 544     apr. Les arguments min et max ont &eacute;t&eacute; pr&eacute;vus pour sp&eacute;cifier une
 545     taille de jeu, mais sont inutilis&eacute;s pour le moment.</dd>
 546    </dl>
 547 </usage>
 548 </directivesynopsis>
 549
 550 <directivesynopsis>
 551 <name>LuaMapHandler</name>
 552 <description>Met en correspondance un chemin avec un gestionnaire lua</description>
 553 <syntax>LuaMapHandler modele-uri /chemin/vers/lua/script.lua
 554 [nom-fonction]</syntax>
 555 <contextlist><context>server config</context><context>virtual host</context>
 556 <context>directory</context><context>.htaccess</context>
 557 </contextlist>
 558 <override>All</override>
 559 <usage>
 560     <p>Cette directive permet de faire correspondre un mod&egrave;le d'uri avec
 561     une fonction de gestionnaire situ&eacute;e dans un fichier sp&eacute;cifique. Elle
 562     utilise les expressions rationnelles PCRE pour mettre en
 563     correspondance l'uri, et supporte les groupes de correspondance
 564     d'interpolation dans le chemin du fichier et le nom de la fonction.
 565     Prenez garde aux probl&egrave;mes de s&eacute;curit&eacute; en &eacute;crivant vos expressions
 566     rationnelles.</p>
 567    <example><title>Exemples :</title>
 568     <highlight language="config">
 569     LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2
 570     </highlight>
 571    </example>
 572         <p>Cette directive va faire correspondre des uri comme
 573         /photos/show?id=9 au fichier /scripts/photos.lua, et invoquera la
 574         fonction de gestionnaire handle_show au niveau de la vm lua
 575         apr&egrave;s chargement de ce fichier.</p>
 576
 577 <highlight language="config">
 578     LuaMapHandler /bingo /scripts/wombat.lua
 579 </highlight>
 580         <p>Cette directive invoquera la fonction "handle" qui est la
 581         valeur par d&eacute;faut si aucun nom de fonction sp&eacute;cifique n'est
 582         sp&eacute;cifi&eacute;.</p>
 583 </usage>
 584 </directivesynopsis>
 585
 586 <directivesynopsis>
 587 <name>LuaPackagePath</name>
 588 <description>Ajoute un r&eacute;pertoire au package.path de lua</description>
 589 <syntax>LuaPackagePath /chemin/vers/include/?.lua</syntax>
 590 <contextlist><context>server config</context><context>virtual host</context>
 591 <context>directory</context><context>.htaccess</context>
 592 </contextlist>
 593 <override>All</override>
 594     <usage><p>Cette directive permet d'ajouter un chemin &agrave; la liste des
 595     chemins de recherche du module lua. Elle suit les m&ecirc;mes conventions
 596     que lua. Ceci modifie le package.path dans les vms lua.</p>
 597
 598     <example><title>Exemples :</title>
 599         <highlight language="config">
 600 LuaPackagePath /scripts/lib/?.lua
 601 LuaPackagePath /scripts/lib/?/init.lua
 602     </highlight>
 603     </example>
 604 </usage>
 605 </directivesynopsis>
 606
 607 <directivesynopsis>
 608 <name>LuaPackageCPath</name>
 609 <description>Ajoute un r&eacute;pertoire au package.cpath de lua</description>
 610 <syntax>LuaPackageCPath /chemin/vers/include/?.soa</syntax>
 611 <contextlist><context>server config</context><context>virtual host</context>
 612 <context>directory</context><context>.htaccess</context>
 613 </contextlist>
 614 <override>All</override>
 615
 616 <usage>
 617     <p>Cette directive permet d'ajouter un chemin &agrave; la liste des chemins
 618     de recherche des biblioth&egrave;ques partag&eacute;es de lua. Ceci modifie le
 619     package.cpath dans les vms lua.</p>
 620
 621 </usage>
 622 </directivesynopsis>
 623
 624 <directivesynopsis>
 625 <name>LuaCodeCache</name>
 626 <description>Configure le cache de code compil&eacute;.</description>
 627 <syntax>LuaCodeCache stat|forever|never</syntax>
 628 <default>LuaCodeCache stat</default>
 629 <contextlist><context>server config</context><context>virtual host</context>
 630 <context>directory</context><context>.htaccess</context>
 631 </contextlist>
 632 <override>All</override>
 633
 634 <usage><p>
 635     Cette directive permet de d&eacute;finir le comportement du cache de code
 636     en m&eacute;moire. La valeur par d&eacute;faut est stat ; dans ce cas, le script
 637     du niveau le plus haut (et pas les scripts inclus) est v&eacute;rifi&eacute; &agrave;
 638     chaque fois que ce fichier est n&eacute;cessaire, et est recharg&eacute; si la
 639     date de modification est plus r&eacute;cente que celle du script d&eacute;j&agrave;
 640     charg&eacute;. Les autres valeurs permettent respectivement de garder le
 641     fichier en cache perp&eacute;tuellement (forever - jamais v&eacute;rifi&eacute; ni
 642     remplac&eacute;), ou de ne jamais le mettre en cache (never).</p>
 643
 644     <p>En g&eacute;n&eacute;ral, les valeurs stat et forever sont utilis&eacute;es pour un
 645     serveur en production, et les valeurs stat ou never pour un serveur
 646     en d&eacute;veloppement.</p>
 647
 648     <example><title>Exemples :</title>
 649         <highlight language="config">
 650 LuaCodeCache stat
 651 LuaCodeCache forever
 652 LuaCodeCache never
 653     </highlight>
 654     </example>
 655
 656 </usage>
 657 </directivesynopsis>
 658
 659 <directivesynopsis>
 660 <name>LuaHookTranslateName</name>
 661 <description>Fournit un point d'entr&eacute;e &agrave; la phase du nom de
 662 traduction du traitement de la requ&ecirc;te</description>
 663 <syntax>LuaHookTranslateName  /chemin/vers/lua/script.lua  nom_fonction_hook [early|late]</syntax>
 664 <contextlist><context>server config</context><context>virtual host</context>
 665 <context>directory</context>
 666 </contextlist>
 667 <override>All</override>
 668 <compatibility>Le troisi&egrave;me argument optionnel est disponible depuis la
 669 version 2.3.15 du serveur HTTP Apache.</compatibility>
 670
 671 <usage><p>
 672     Cette directive permet d'ajouter un point d'entr&eacute;e (&agrave;
 673     APR_HOOK_MIDDLE) &agrave; la phase du nom de traduction du traitement de la
 674     requ&ecirc;te. La fonction hook accepte un seul argument, le request_rec,
 675     et doit renvoyer un code d'&eacute;tat qui est soit un code d'erreur HTTP,
 676     ou une constante d&eacute;finie dans le module apache2 :  apache2.OK,
 677     apache2.DECLINED, ou apache2.DONE.</p>
 678
 679     <p>Pour ceux qui ne sont pas familiers avec les points d'entr&eacute;e
 680     (hook), en gros, chaque hook sera invoqu&eacute; jusqu'&agrave; ce que l'un
 681     d'entre eux renvoie apache2.OK. Si un hook n'effectuer pas la
 682     traduction, il doit juste renvoyer apache2.DECLINED. Si le
 683     traitement de la requ&ecirc;te doit &ecirc;tre interrompu, la valeur renvoy&eacute;e
 684     doit &ecirc;tre apache2.DONE.</p>
 685
 686     <p>Exemple :</p>
 687
 688 <highlight language="config">
 689 # httpd.conf
 690 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
 691 </highlight>
 692
 693 <highlight language="lua">
 694 -- /scripts/conf/hooks.lua --
 695 require "apache2"
 696 function silly_mapper(r)
 697     if r.uri == "/" then
 698         r.filename = "/var/www/home.lua"
 699         return apache2.OK
 700     else
 701         return apache2.DECLINED
 702     end
 703 end
 704 </highlight>
 705
 706    <note><title>Contexte</title><p>Cette directive ne peut &ecirc;tre
 707    utilis&eacute;e ni &agrave; l'int&eacute;rieur d'une section <directive type="section"
 708    module="core">Directory</directive> ou <directive type="section"
 709    module="core">Files</directive>, ni dans un fichier htaccess.</p></note>
 710
 711    <note><title>Ordonnancement</title><p>Les arguments optionnels
 712    "early" ou "late" permettent de contr&ocirc;ler le moment auquel ce script
 713    s'ex&eacute;cute par rapport aux autres modules.</p></note>
 714 </usage>
 715 </directivesynopsis>
 716
 717 <directivesynopsis>
 718 <name>LuaHookFixups</name>
 719 <description>Fournit un point d'entr&eacute;e pour la phase de correction du
 720 traitement de la requ&ecirc;te</description>
 721 <syntax>LuaHookFixups  /chemin/vers/lua/script.lua hook_function_name</syntax>
 722 <contextlist><context>server config</context><context>virtual host</context>
 723 <context>directory</context><context>.htaccess</context>
 724 </contextlist>
 725 <override>All</override>
 726 <usage>
 727 <p>
 728     Idem LuaHookTranslateName, mais s'ex&eacute;cute durant la phase de
 729     correction.
 730 </p>
 731 </usage>
 732 </directivesynopsis>
 733
 734 <directivesynopsis>
 735 <name>LuaHookMapToStorage</name>
 736 <description>Fournit un point d'entr&eacute;e pour la phase map_to_storage du
 737 traitement de la requ&ecirc;te</description>
 738 <syntax>LuaHookMapToStorage  /chemin/vers/lua/script.lua hook_function_name</syntax>
 739 <contextlist><context>server config</context><context>virtual host</context>
 740 <context>directory</context><context>.htaccess</context>
 741 </contextlist>
 742 <override>All</override>
 743     <usage><p>...</p></usage>
 744 </directivesynopsis>
 745
 746 <directivesynopsis>
 747 <name>LuaHookCheckUserID</name>
 748 <description>Fournit un point d'entr&eacute;e pour la phase check_user_id du
 749 traitement de la requ&ecirc;te</description>
 750 <syntax>LuaHookCheckUserID  /chemin/vers/lua/script.lua hook_function_name [early|late]</syntax>
 751 <contextlist><context>server config</context><context>virtual host</context>
 752 <context>directory</context><context>.htaccess</context>
 753 </contextlist>
 754 <override>All</override>
 755 <compatibility>Le troisi&egrave;me argument optionnel est disponible depuis la
 756 version 2.3.15 du serveur HTTP Apache.</compatibility>
 757 <usage><p>...</p>
 758    <note><title>Ordonnancement</title><p>Les arguments optionnels
 759    "early" ou "late" permettent de contr&ocirc;ler le moment auquel ce script
 760    s'ex&eacute;cute par rapport aux autres modules.</p></note>
 761 </usage>
 762 </directivesynopsis>
 763
 764 <directivesynopsis>
 765 <name>LuaHookTypeChecker</name>
 766 <description>Fournit un point d'entr&eacute;e pour la phase type_checker du
 767 traitement de la requ&ecirc;te</description>
 768 <syntax>LuaHookTypeChecker  /chemin/vers/lua/script.lua hook_function_name</syntax>
 769 <contextlist><context>server config</context><context>virtual host</context>
 770 <context>directory</context><context>.htaccess</context>
 771 </contextlist>
 772 <override>All</override>
 773     <usage><p>...</p></usage>
 774 </directivesynopsis>
 775
 776 <directivesynopsis>
 777 <name>LuaHookAuthChecker</name>
 778 <description>Fournit un point d'entr&eacute;e pour la phase auth_checker du
 779 traitement de la requ&ecirc;te</description>
 780 <syntax>LuaHookAuthChecker  /chemin/vers/lua/script.lua hook_function_name [early|late]</syntax>
 781 <contextlist><context>server config</context><context>virtual host</context>
 782 <context>directory</context><context>.htaccess</context>
 783 </contextlist>
 784 <override>All</override>
 785 <compatibility>Le troisi&egrave;me argument optionnel est disponible depuis la
 786 version 2.3.15 du serveur HTTP Apache.</compatibility>
 787     <usage>
 788 <p>Invoque une fonction lua au cours de la phase auth_checker du
 789 traitement de la requ&ecirc;te. Cette directive peut s'utiliser pour
 790 impl&eacute;menter une v&eacute;rification arbitraire de l'authentification et de
 791 l'autorisation. Voici un exemple tr&egrave;s simple :
 792 </p>
 793 <highlight language="lua">
 794 require 'apache2'
 795
 796 -- fonction d'accroche authcheck fictive
 797 -- Si la requ&ecirc;te ne contient aucune donn&eacute;e d'authentification, l'en-t&ecirc;te
 798 -- de la r&eacute;ponse est d&eacute;fini et un code 401 est renvoy&eacute; afin de demander au
 799 -- navigateur d'effectuer une authentification basique. Si la requ&ecirc;te
 800 -- comporte des donn&eacute;es d'authentification, elles ne sont pas vraiment
 801 -- consult&eacute;es, mais on admet la prise en compte de l'utilisateur 'foo' et
 802 -- on la valide. On v&eacute;rifie ensuite si l'utilisateur est bien 'foo' et on
 803 -- accepte la requ&ecirc;te.
 804 function authcheck_hook(r)
 805
 806    -- recherche des informations d'authentification
 807    auth = r.headers_in['Authorization']
 808    if auth ~= nil then
 809      -- d&eacute;finition d'un utilisateur par d&eacute;faut
 810      r.user = 'foo'
 811    end
 812
 813    if r.user == nil then
 814       r:debug("authcheck: user is nil, returning 401")
 815       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
 816       return 401
 817    elseif r.user == "foo" then
 818       r:debug('user foo: OK')
 819    else
 820       r:debug("authcheck: user='" .. r.user .. "'")
 821       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
 822       return 401
 823    end
 824    return apache2.OK
 825 end
 826 </highlight>
 827 <note><title>Ordonnancement</title><p>Les arguments optionnels
 828    "early" ou "late" permettent de contr&ocirc;ler le moment auquel ce script
 829    s'ex&eacute;cute par rapport aux autres modules.</p></note>
 830 </usage>
 831 </directivesynopsis>
 832
 833 <directivesynopsis>
 834 <name>LuaHookAccessChecker</name>
 835 <description>Fournit un point d'entr&eacute;e pour la phase access_checker du
 836 traitement de la requ&ecirc;te</description>
 837 <syntax>LuaHookAccessChecker  /chemin/vers/lua/script.lua  hook_function_name [early|late]</syntax>
 838 <contextlist><context>server config</context><context>virtual host</context>
 839 <context>directory</context><context>.htaccess</context>
 840 </contextlist>
 841 <override>All</override>
 842 <compatibility>Le troisi&egrave;me argument optionnel est disponible depuis la
 843 version 2.3.15 du serveur HTTP Apache.</compatibility>
 844
 845 <usage>
 846 <p>Ajoute votre fonction d'accroche &agrave; la phase access_checker. Une
 847 fonction d'accroche access checker renvoie en g&eacute;n&eacute;ral OK, DECLINED, ou
 848 HTTP_FORBIDDEN.</p>
 849 <note><title>Ordonnancement</title><p>Les arguments optionnels
 850    "early" ou "late" permettent de contr&ocirc;ler le moment auquel ce script
 851    s'ex&eacute;cute par rapport aux autres modules.</p></note>
 852 </usage>
 853 </directivesynopsis>
 854 <directivesynopsis>
 855 <name>LuaHookInsertFilter</name>
 856 <description>Fournit un point d'entr&eacute;e pour la phase insert_filter du
 857 traitement de la requ&ecirc;te</description>
 858 <syntax>LuaHookInsertFilter  /chemin/vers/lua/script.lua hook_function_name</syntax>
 859 <contextlist><context>server config</context><context>virtual host</context>
 860 <context>directory</context><context>.htaccess</context>
 861 </contextlist>
 862 <override>All</override>
 863     <usage><p>Non encore impl&eacute;ment&eacute;</p></usage>
 864 </directivesynopsis>
 865
 866 <directivesynopsis>
 867 <name>LuaInherit</name>
 868 <description>Contr&ocirc;le la mani&egrave;re dont les sections de configuration
 869 parentes sont fusionn&eacute;es dans les enfants</description>
 870 <syntax>LuaInherit none|parent-first|parent-last</syntax>
 871 <default>LuaInherit parent-first</default>
 872 <contextlist><context>server config</context><context>virtual host</context>
 873 <context>directory</context><context>.htaccess</context>
 874 </contextlist>
 875 <override>All</override>
 876 <compatibility>Versions 2.4.0 et sup&eacute;rieures</compatibility>
 877     <usage><p>Par d&eacute;faut, si des directives LuaHook* se trouvent dans
 878     des sections de configuration Directory ou Location qui se
 879     chevauchent, les scripts
 880     d&eacute;finis dans les sections les plus sp&eacute;cifiques s'ex&eacute;cutent
 881     <em>apr&egrave;s</em> ceux d&eacute;finis dans les sections plus g&eacute;n&eacute;riques
 882     (LuaInherit parent-first). Vous pouvez inverser cet ordre, ou faire
 883     en sorte que le contexte parent ne s'applique pas du tout.</p>
 884
 885     <p>Jusqu'aux versions 2.3.x, le comportement par d&eacute;faut consistait &agrave;
 886     ignorer les directives LuaHook* situ&eacute;es dans les sections de
 887     configuration parentes.</p></usage>
 888 </directivesynopsis>
 889
 890 <directivesynopsis>
 891 <name>LuaQuickHandler</name>
 892 <description>Fournit un point d'entr&eacute;e pour la gestion rapide du
 893 traitement de la requ&ecirc;te</description>
 894 <syntax></syntax>
 895 <contextlist><context>server config</context><context>virtual host</context>
 896 <context>directory</context><context>.htaccess</context>
 897 </contextlist>
 898 <override>All</override>
 899 <usage><p>...</p>
 900    <note><title>Contexte</title><p>Cette directive ne peut &ecirc;tre
 901    utilis&eacute;e ni &agrave; l'int&eacute;rieur d'une section <directive type="section"
 902    module="core">Directory</directive> ou <directive type="section"
 903    module="core">Files</directive>, ni dans un fichier htaccess.</p></note>
 904 </usage>
 905 </directivesynopsis>
 906
 907 <directivesynopsis>
 908 <name>LuaAuthzProvider</name>
 909 <description>Branche une fonction fournisseur d'autorisation dans <module>mod_authz_core</module>
 910 </description>
 911 <syntax>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</syntax>
 912 <contextlist><context>server config</context> </contextlist>
 913 <compatibility>Disponible depuis la version 2.5.0 du serveur HTTP Apache</compatibility>
 914
 915 <usage>
 916 <p>Lorsqu'une fonction lua a &eacute;t&eacute; enregistr&eacute;e en tant que fournisseur
 917 d'autorisation, elle peut &ecirc;tre appel&eacute;e via la directive <directive
 918 module="mod_authz_core">Require</directive> :</p>
 919
 920 <example>
 921 <highlight language="config">
 922 LuaRoot /usr/local/apache2/lua
 923 LuaAuthzProvider foo authz.lua authz_check_foo
 924 &lt;Location /&gt;
 925   Require foo bar
 926 &lt;/Location&gt;
 927 </highlight>
 928 </example>
 929
 930 </usage>
 931 </directivesynopsis>
 932
 933
 934 </modulesynopsis>
 935