1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1817908 -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- $LastChangedRevision: 2017062501 $ -->
10 Licensed to the Apache Software Foundation (ASF) under one or more
11 contributor license agreements. See the NOTICE file distributed with
12 this work for additional information regarding copyright ownership.
13 The ASF licenses this file to You under the Apache License, Version 2.0
14 (the "License"); you may not use this file except in compliance with
15 the License. You may obtain a copy of the License at
17 http://www.apache.org/licenses/LICENSE-2.0
19 Unless required by applicable law or agreed to in writing, software
20 distributed under the License is distributed on an "AS IS" BASIS,
21 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 See the License for the specific language governing permissions and
23 limitations under the License.
26 <modulesynopsis metafile="mod_proxy_hcheck.xml.meta">
28 <name>mod_proxy_hcheck</name>
29 <description>Check up dynamique des membres du groupe de répartition de charge
30 (équipiers) pour <module>mod_proxy</module></description>
31 <status>Extension</status>
32 <sourcefile>mod_proxy_hcheck.c</sourcefile>
33 <identifier>proxy_hcheck_module</identifier>
34 <compatibility>Disponible à partir de la version 2.4.21 du serveur HTTP Apache</compatibility>
37 <p>Ce module permet d'effectuer un check up dynamique des membres du groupe
38 de répartition de charge (équipiers). Ce check up peut être activé pour un
39 ou plusieurs équipiers et il est indépendant des requêtes de mandataire
40 inverse proprement dites.</p>
42 <p>Pour fonctionner, ce module <em>nécessite</em> le chargement préalable de
43 <module>mod_watchdog</module>.</p>
45 <note><title>Paramètres</title>
46 <p>Le mécanisme de check up est activé via l'utilisation de paramètres
47 supplémentaires de BalancerMember configurés de manière standard via la
48 directive <directive module="mod_proxy">ProxyPass</directive> :</p>
50 <p>Ce module définit un nouveau drapeau d'état pour BalancerMember :
51 "<code>C</code>". Lorsque l'équipier est mis hors service suite à un
52 disfonctionnement déterminé par le module de check up, ce drapeau est activé
53 et peut être lu (et modifié) via le <code>balancer-manager</code>.</p>
56 <tr><th>Paramètre</th>
57 <th>Défaut</th>
58 <th>Description</th></tr>
61 <td>Aucun check up dynamique n'est effectué. Les choix possibles sont :
63 <tr><th>Method</th><th>Description</th><th>Note</th></tr>
64 <tr><td>None</td><td>Aucun check up dynamique effectué</td><td></td></tr>
65 <tr><td>TCP</td><td>Vérifie qu'un socket vers le serveur
66 d'arrière-plan peut être créé ; par exemple "es-tu en
67 état de fonctionner"</td><td></td></tr>
68 <tr><td>OPTIONS</td><td>Envoie une requête <code>HTTP
69 OPTIONS</code> au serveur d'arrière-plan</td><td>*</td></tr>
70 <tr><td>HEAD</td><td>Envoie une requête <code>HTTP
71 HEAD</code> au serveur d'arrière-plan</td><td>*</td></tr>
72 <tr><td>GET</td><td>Envoie une requête <code>HTTP
73 GET</code> au serveur d'arrière-plan</td><td>*</td></tr>
75 <tr><td>CPING</td><td><strong>AJP only</strong> Do <code>CPING/CPONG</code> check</td><td></td></tr>
76 <tr><td>PROVIDER</td><td>Name of <code>provider</code> to be used to check health</td><td></td></tr>
78 <tr><td colspan="3"></td></tr>
79 <tr><td colspan="3">*: si hcexpr n'est pas
80 utilisé, un retour HTTP 2xx ou 3xx sera
81 interprété comme un passage avec succès du check
87 <td>Nombre de check up à passer avec succès avant de remettre en service
88 l'équipier</td></tr>
91 <td>Nombre de check up échoués avant mettre hors service l'équipier</td></tr>
92 <tr><td>hcinterval</td>
94 <td>Intervalle entre deux check up en secondes (par défaut effectué
95 toutes les 30 secondes). Utilise la syntaxe <a
96 href="directive-dict.html#Syntax">time-interval</a>.</td></tr>
99 <td>URI supplémentaire à ajouter à l'URL de l'équipier pour le check up.</td></tr>
100 <tr><td>hctemplate</td>
102 <td>Nom du modèle créé via <directive>ProxyHCTemplate</directive> à
103 utiliser pour définir les paramètres de check up de cet équipier</td></tr>
106 <td>Nom de l'expression créée via <directive>ProxyHCExpr</directive>
107 utilisée pour analyser les en-têtes de la réponse du check up.<br/>
108 <em>Si ce paramètre est absent, un état HTTP de 2xx à 3xx est
109 interprété comme un check up réussi.</em></td></tr>
114 <seealso><module>mod_proxy</module></seealso>
116 <section id="examples">
118 <title>Exemples d'utilisation</title>
119 <p>L'exemple suivant montre comment configurer le check up pour différents
120 serveurs d'arrière-plan :</p>
122 <!-- This section should probably be extended with more, useful examples -->
123 <highlight language="config">
124 ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
125 ProxyHCExpr gdown {%{REQUEST_STATUS} =~ /^[5]/}
126 ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
128 <Proxy balancer://foo>
129 BalancerMember http://www.example.com/ hcmethod=GET hcexpr=in_maint hcuri=/status.php
130 BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10
131 BalancerMember http://www3.example.com/ hcmethod=TCP hcinterval=5 hcpasses=2 hcfails=3
132 BalancerMember http://www4.example.com/
135 ProxyPass "/" "balancer://foo"
136 ProxyPassReverse "/" "balancer://foo"
139 <p>Dans ce scénario, on teste l'équipier <code>http://www.example.com/</code> en lui
140 envoyant une requête <code>GET /status.php</code> et en regardant si la réponse
141 contient la chaîne <em>Under maintenance</em>. Si c'est le cas, le check up est
142 considéré comme ayant échoué et l'équipier est mis hors service. Ce check up
143 dynamique est effectué toutes les 30 secondes, ce qui correspond à la valeur par
146 <p>On teste l'équipier <code>http://www2.example.com/</code> en lui envoyant
147 simplement une requête <code>HEAD</code> toutes les 10 secondes et en vérifiant
148 que la réponse HTTP est bien un code d'état de 2xx, 3xx ou 4xx. On teste
149 l'équipier <code>http://www3.example.com/</code> en vérifiant simplement toutes
150 les 5 secondes que le socket vers ce serveur est bien opérationnel. Si ce
151 serveur est marqué "hors service", il lui faudra 2 check up réussis pour être
152 réactivé et participer à nouveau à la répartition de charge. Si à ce moment-là
153 il échoue à 3 check up successifs, il sera à nouveau mis hors service. Enfin,
154 l'équipier <code>http://www4.example.com/</code> ne fait l'objet d'aucun check
160 <name>ProxyHCExpr</name>
161 <description>Crée et nomme une expression conditionnelle à utiliser pour
162 déterminer la santé d'un serveur d'arrière-plan en fonction de sa valeur.</description>
163 <syntax>ProxyHCExpr name {ap_expr expression}</syntax>
164 <contextlist><context>server config</context><context>virtual host</context>
166 <override>FileInfo</override>
169 <p>La directive <directive>ProxyHCExpr</directive> permet de créer et nommer
170 une expression conditionnelle dont la valeur calculée en fonction des
171 en-têtes de la réponse du serveur d'arrière-plan permettra d'évaluer la
172 santé de ce dernier. Cette expression nommée peut alors être assignée aux
173 serveurs d'arrière-plan via le paramètre <code>hcexpr</code>.</p>
175 <example><title>ProxyHCExpr: interprète les réponses 2xx/3xx/4xx comme des
176 check up réussis</title>
177 <highlight language="config">
178 ProxyHCExpr ok234 {%{REQUEST_STATUS} =~ /^[234]/}
179 ProxyPass "/apps" "balancer://foo"
181 <Proxy balancer://foo>
182 BalancerMember http://www2.example.com/ hcmethod=HEAD hcexpr=ok234 hcinterval=10
188 L'<a href="../expr.html">expression</a> peut utiliser des accolades ("{}")
189 comme délimiteurs en plus des guillemets normaux.
192 <p>Si l'on utilise une méthode de check up (par exemple <code>GET</code>)
193 qui génère un corps de réponse, ce corps peut lui-même être ausculté via
194 <code>ap_expr</code> en utilisant la fonction associée aux expressions
195 <code>hc()</code> spécifique à ce module.</p>
197 <p>Dans l'exemple suivant, on envoie une requête <code>GET</code> au serveur
198 d'arrière-plan, et si le corps de la réponse contient la chaîne <em>Under
199 maintenance</em>, ce serveur d'arrière-plan est mis hors service.</p>
201 <example><title>ProxyHCExpr: auscultation du corps de la réponse</title>
202 <highlight language="config">
203 ProxyHCExpr in_maint {hc('body') !~ /Under maintenance/}
204 ProxyPass "/apps" "balancer://foo"
206 <Proxy balancer://foo>
207 BalancerMember http://www.example.com/ hcexpr=in_maint hcmethod=get hcuri=/status.php
212 <p><em>NOTE:</em> Comme le corps de la réponse peut être assez grand, il est
213 recommandé de privilégier un check up basé sur les codes d'état.</p>
219 <name>ProxyHCTemplate</name>
220 <description>Crée et nomme un modèle permettant de définir différents
221 paramètres de check up</description>
222 <syntax>ProxyHCTemplate name parameter=setting <...></syntax>
223 <contextlist><context>server config</context><context>virtual host</context>
225 <override>FileInfo</override>
228 <p>La directive <directive>ProxyHCTemplate</directive> permet de créer et
229 nommer un modèle de paramètres de check up qui peut alors être assigné aux
230 équipiers via le paramètre <code>hctemplate</code></p>
232 <example><title>ProxyHCTemplate</title>
233 <highlight language="config">
234 ProxyHCTemplate tcp5 hcmethod=tcp hcinterval=5
235 ProxyPass "/apps" "balancer://foo"
237 <Proxy balancer://foo>
238 BalancerMember http://www2.example.com/ hctemplate=tcp5
247 <name>ProxyHCTPsize</name>
248 <description>Définit la taille totale, pour l'ensemble du
249 serveur, du jeu de threads utilisé pour le check up des
250 équipiers.</description>
251 <syntax>ProxyHCTPsize <size></syntax>
252 <contextlist><context>server config</context>
256 <p>Si Apache httpd et APR ont été compilés avec le support des threads, le
257 module de check up peut confier ce travail à un jeu de threads associé au
258 processus Watchdog, ce qui permet l'exécution des check up en parallèle. La
259 directive <directive>ProxyHCTPsize</directive> permet de déterminer la
260 taille de ce jeu de threads. Une valeur de <code>0</code> signifie qu'aucun
261 jeu de threads ne sera utilisé, et le check up des différents équipiers sera
262 alors effectué séquentiellement. La taille par défaut du jeu de threads est
265 <example><title>ProxyHCTPsize</title>
266 <highlight language="config">
projects / apache / blob