Serveur Apache HTTP Version 2.5
Description: | Serveur mandataire/passerelle multi-protocole |
---|---|
Statut: | Extension |
Identificateur de Module: | proxy_module |
Fichier Source: | mod_proxy.c |
N'activez pas la fonctionnalité de mandataire avec la directive
ProxyRequests
avant
d'avoir sécurisé votre serveur. Les serveurs
mandataires ouverts sont dangereux pour votre réseau,
mais aussi pour l'Internet au sens large.
mod_proxy
et ses modules associés implémentent
un mandataire/passerelle pour le serveur HTTP Apache, et supportent
de nombreux protocoles courants, ainsi que plusieurs algorithmes de
répartition de charge. Le support de protocoles et d'algorithmes de
répartition de charge supplémentaires peut être assuré par des
modules tiers.
Un jeu de modules chargés dans le serveur permet de fournir les
fonctionnalités souhaitées. Ces modules peuvent être inclus
statiquement à la compilation, ou dynamiquement via la directive
LoadModule
. Ce jeu de module
doit comporter :
mod_proxy
, qui fournit les fonctionnalités de
base d'un mandatairemod_proxy_balancer
et un ou plusieurs modules
de répartition, si la répartition de charge doit être mise en
oeuvre (Voir la documentation de
mod_proxy_balancer
pour plus de détails).Protocole | Module |
---|---|
AJP13 (Protocole Apache JServe version 1.3) | mod_proxy_ajp |
CONNECT (pour SSL) | mod_proxy_connect |
FastCGI | mod_proxy_fcgi |
ftp | mod_proxy_ftp |
HTTP/0.9, HTTP/1.0, et HTTP/1.1 | mod_proxy_http |
SCGI | mod_proxy_scgi |
WS and WSS (Web-sockets) | mod_proxy_wstunnel |
En outre, d'autres modules fournissent des fonctionnalités
étendues. mod_cache
et ses modules associés
fournissent la mise en cache. Les directives SSLProxy*
du module mod_ssl
permettent de contacter des
serveurs distants en utilisant le protocole SSL/TLS. Ces modules
additionnels devront être chargés et configurés pour pouvoir
disposer de ces fonctionnalités.
Le serveur HTTP Apache peut être configuré dans les deux modes mandataire direct et mandataire inverse (aussi nommé mode passerelle).
Un mandataire direct standard est un serveur intermédiaire qui s'intercale entre le client et le serveur demandé. Pour obtenir un contenu hébergé par le serveur demandé, le client envoie une requête au mandataire en nommant le serveur demandé comme cible, puis le mandataire extrait le contenu depuis le serveur demandé et le renvoie enfin au client. Le client doit être configuré de manière appropriée pour pouvoir utiliser le mandataire direct afin d'accéder à d'autres sites.
L'accès à Internet depuis des clients situés derrière un
pare-feu est une utilisation typique du mandataire direct. Le
mandataire direct peut aussi utiliser la mise en cache (fournie
par mod_cache
) pour réduire la charge du
réseau.
La fonctionnalité de mandataire direct est activée via la
directive ProxyRequests
.
Comme les mandataires directs permettent aux clients d'accéder à
des sites quelconques via votre serveur et de dissimuler leur
véritable origine, il est indispensable de sécuriser votre serveur de façon à ce que seuls
les clients autorisés puissent accéder à votre serveur avant
d'activer la fonctionnalité de mandataire direct.
Un mandataire inverse (ou passerelle), quant à lui, apparaît au client comme un serveur web standard. Aucune configuration particulière du client n'est nécessaire. Le client adresse ses demandes de contenus ordinaires dans l'espace de nommage du mandataire inverse. Ce dernier décide alors où envoyer ces requêtes, et renvoie le contenu au client comme s'il l'hébergeait lui-même.
L'accès d'utilisateurs depuis Internet vers un serveur situé derrière un pare-feu est une utilisation typique du mandataire inverse. On peut aussi utiliser les mandataires inverses pour mettre en oeuvre une répartition de charge entre plusieurs serveurs en arrière-plan, ou fournir un cache pour un serveur d'arrière-plan plus lent. Les mandataires inverses peuvent aussi tout simplement servir à rassembler plusieurs serveurs dans le même espace de nommage d'URLs.
La fonctionnalité de mandataire inverse est activée via la
directive ProxyPass
ou
le drapeau [P]
de la directive RewriteRule
. Il n'est
pas nécessaire de définir ProxyRequests
pour configurer
un mandataire inverse.
Les exemples ci-dessous illustrent de manière très basique la mise en oeuvre de la fonctionnalité de mandataire et ne sont là que pour vous aider à démarrer. Reportez-vous à la documentation de chaque directive.
Si en outre, vous désirez activer la mise en cache, consultez la
documentation de mod_cache
.
ProxyPass "/foo" "http://foo.example.com/bar" ProxyPassReverse "/foo" "http://foo.example.com/bar"
ProxyRequests On ProxyVia On <Proxy *> Require host internal.example.com </Proxy>
Vous pouvez aussi forcer le traitement d'une requête en tant que requête de mandataire inverse en créant un gestionnaire de transfert approprié. Dans l'exemple suivant, toutes les requêtes pour des scripts PHP seront transmises au serveur FastCGI spécifié via un mandat inverse :
<FilesMatch "\.php$"> SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/" </FilesMatch>
Cette fonctionnalité est disponible à partir de la version 2.4.10 du serveur HTTP Apache.
Le mandataire gère la configuration et les paramètres de communication des serveurs originaux au sein d'objets nommés workers. Deux types de worker sont fournis : le worker par défaut du mandataire direct et le worker par défaut du mandataire inverse. Il est aussi possible de définir explicitement des workers supplémentaires.
Les deux workers par défaut possèdent une configuration figée et seront utilisés si aucun autre worker ne correspond à la requête. Ils ne réutilisent pas les connexions et n'utilisent pas les connexions HTTP persistantes (Keep-Alive). En effet, les connexions TCP vers le serveur original sont fermées et ouvertes pour chaque requête.
Les workers définis explicitement sont identifiés par leur URL.
Ils sont en général définis via les directives ProxyPass
ou ProxyPassMatch
lorsqu'on les
utilise dans le cadre d'un mandataire inverse :
ProxyPass "/example" "http://backend.example.com" connectiontimeout=5 timeout=30
Cette directive va créer un worker associé à l'URL du serveur original
http://backend.example.com
, qui utilisera les valeurs de
timeout données. Toutes les spécifications de timeouts utilisent la
syntaxe time-interval. Lorsqu'ils
sont utilisés dans le cadre d'un mandataire direct, les workers sont en
général définis via la directive ProxySet
:
ProxySet http://backend.example.com connectiontimeout=5 timeout=30
ou encore via les directives Proxy
et ProxySet
:
<Proxy http://backend.example.com> ProxySet connectiontimeout=5 timeout=30 </Proxy>
L'utilisation de workers définis explicitement dans le mode
mandataire direct n'est pas très courante, car les mandataires
directs communiquent en général avec de nombreux serveurs
originaux. La création explicite de workers pour certains serveurs
originaux peut cependant s'avérer utile si ces serveurs sont
très souvent sollicités. A leur niveau, les workers explicitement
définis ne possèdent aucune notion de mandataire direct ou
inverse. Ils encapsulent un concept de communication commun avec
les serveurs originaux. Un worker créé via la directive ProxyPass
pour être utilisé dans le
cadre d'un mandataire inverse sera aussi utilisé dans le cadre
d'un mandataire directe chaque fois que l'URL vers le serveur
original correspondra à l'URL du worker, et vice versa.
L'URL qui identifie un worker correspond à l'URL de son serveur original, y compris un éventuel chemin donné :
ProxyPass "/examples" "http://backend.example.com/examples" ProxyPass "/docs" "http://backend.example.com/docs"
Dans cet exemple, deux workers différents sont définis, chacun d'eux utilisant des configurations et jeux de connexions séparés.
Le partage de workers intervient lorsque les URLs des workers s'entrecoupent, ce qui arrive lorsque l'URL d'un worker correspond au début de l'URL d'un autre worker défini plus loin dans le fichier de configuration. Dans l'exemple suivant,
ProxyPass "/apps" "http://backend.example.com/" timeout=60 ProxyPass "/examples" "http://backend.example.com/examples" timeout=10
le second worker n'est pas vraiment créé. C'est le premier
worker qui est en fait utilisé. L'avantage de ceci réside dans
le fait qu'il n'existe qu'un seul jeu de connexions, ces
dernières étant donc réutilisées plus souvent. Notez que tous
les attributs de configuration définis explicitement pour le
deuxième worker seront ignorés, ce qui sera journalisé en tant
qu'avertissement. Ainsi, dans l'exemple ci-dessus, la valeur de
timeout retenue pour l'URL /exemples
sera
60
, et non 10
!
Si vous voulez empêcher le partage de workers, classez vos
définitions de workers selon la longueur des URLs, de la plus
longue à la plus courte. Si au contraire vous voulez favoriser
ce partage, utilisez l'ordre de classement inverse. Voir aussi
l'avertissement à propos de l'ordre de classement des directives
ProxyPass
.
Les workers définis explicitement sont de deux sortes :
workers directs et workers de répartition (de
charge). Ils supportent de nombreux attributs de
configuration importants décrits dans la directive ProxyPass
. Ces mêmes attributs
peuvent aussi être définis via la directive ProxySet
.
Le jeu d'options disponibles pour un worker direct dépend du
protocole spécifié dans l'URL du serveur original. Les protocoles
disponibles comprennent ajp
, fcgi
,
ftp
, http
et scgi
.
Les workers de répartition sont des workers virtuels qui utilisent les workers directs, connus comme faisant partie de leurs membres, pour le traitement effectif des requêtes. Chaque répartiteur peut comporter plusieurs membres. Lorsqu'il traite une requête, il choisit un de ses membres en fonction de l'algorithme de répartition de charge défini.
Un worker de répartition est créé si son URL de worker comporte
balancer
comme indicateur de protocole. L'URL du
répartiteur permet d'identifier de manière unique le worker de
répartition. La directive BalancerMember
permet d'ajouter des
membres au répartiteur.
La résolution DNS s'effectue lorsque le socket vers le
domaine original est créé pour la première fois. Lorsque la réutilisation
des connexions est activée, chaque domaine d'arrière-plan n'est résolu qu'une
seule fois pour chaque processus enfant, et cette résolution est mise en
cache pour toutes les connexions ultérieures jusqu'à ce que le processus enfant
soit recyclé. Ce comportement doit être pris en considération lorsqu'on
planifie des tâches de maintenance du DNS impactant les domaines
d'arrière-plan. Veuillez aussi vous reporter aux paramètres de la
directive ProxyPass
pour plus de
détails à propos de la réutilisation des connexions.
Vous pouvez restreindre l'accès à votre mandataire via le bloc
de contrôle <Proxy>
comme dans
l'exemple suivant :
<Proxy *> Require ip 192.168.0 </Proxy>
Pour plus de détails sur les directives de contrôle d'accès,
voir la documentation du module
mod_authz_host
.
Restreindre l'accès de manière stricte est essentiel si vous
mettez en oeuvre un mandataire direct (en définissant la directive
ProxyRequests
à "on").
Dans le cas contraire, votre serveur pourrait être utilisé par
n'importe quel client pour accéder à des serveurs quelconques,
tout en masquant sa véritable identité. Ceci représente un danger
non seulement pour votre réseau, mais aussi pour l'Internet au
sens large. Dans le cas de la mise en oeuvre d'un mandataire
inverse (en utilisant la directive ProxyPass
avec ProxyRequests Off
), le contrôle
d'accès est moins critique car les clients ne peuvent contacter
que les serveurs que vous avez spécifiés.
Voir aussi la variable d'environnement Proxy-Chain-Auth.
Si vous utilisez la directive ProxyBlock
, les noms d'hôtes sont résolus en adresses
IP puis ces dernières mises en cache au cours du démarrage
à des fins de tests de comparaisons ultérieurs. Ce processus peut
durer plusieurs secondes (ou d'avantage) en fonction de la vitesse
à laquelle s'effectue la résolution des noms d'hôtes.
Un serveur mandataire Apache httpd situé à l'intérieur d'un Intranet
doit faire suivre les requêtes destinées à un serveur externe à
travers le pare-feu de l'entreprise (pour ce faire, définissez la
directive ProxyRemote
de
façon à ce qu'elle fasse suivre le protocole concerné
vers le mandataire du pare-feu). Cependant, lorsqu'il doit accéder
à des ressources situées dans l'Intranet, il peut se passer du
pare-feu pour accéder aux serveurs. A cet effet, la directive
NoProxy
permet de
spécifier quels hôtes appartiennent à l'Intranet et peuvent donc
être accédés directement.
Les utilisateurs d'un Intranet ont tendance à oublier le nom du
domaine local dans leurs requêtes WWW, et demandent par exemple
"http://un-serveur/" au lieu de
http://un-serveur.example.com/
. Certains serveurs
mandataires commerciaux acceptent ce genre de requête et les
traitent simplement en utilisant un nom de domaine local
implicite. Lorsque la directive ProxyDomain
est utilisée et si le
serveur est configuré comme
mandataire, Apache httpd peut renvoyer une réponse de redirection et
ainsi fournir au client l'adresse de serveur correcte,
entièrement qualifiée. C'est la méthode à privilégier car le
fichier des marque-pages de l'utilisateur contiendra alors des
noms de serveurs entièrement qualifiés.
Pour les cas où mod_proxy
envoie des requêtes
vers un serveur qui n'implémente pas correctement les connexions
persistantes ou le protocole HTTP/1.1, il existe deux variables
d'environnement qui permettent de forcer les requêtes à utiliser
le protocole HTTP/1.0 avec connexions non persistantes. Elles
peuvent être définies via la directive SetEnv
.
Il s'agit des variables force-proxy-request-1.0
et
proxy-nokeepalive
.
<Location "/buggyappserver/"> ProxyPass "http://buggyappserver:7001/foo/" SetEnv force-proxy-request-1.0 1 SetEnv proxy-nokeepalive 1 </Location>
A partir de la version 2.4.26 du serveur HTTP Apache, la définition de
la variable d'environnement "no-proxy" permet de désactiver
mod_proxy
dans le traitement de la requête courante.
Cette variable doit être définie via la directive SetEnvIf
car la directive SetEnv
n'est pas évaluée assez tôt.
Certaines méthodes de requêtes comme POST comportent un corps de
requête. Le protocole HTTP stipule que les requêtes qui comportent
un corps doivent soit utiliser un codage de transmission
fractionnée (chunked transfer encoding), soit envoyer un en-tête de requête
Content-Length
. Lorsqu'il fait suivre ce genre de
requête vers le serveur demandé, mod_proxy_http
s'efforce toujours d'envoyer l'en-tête Content-Length
.
Par contre, si la taille du corps est importante, et si la requête
originale utilise un codage à fractionnement, ce dernier peut aussi
être utilisé dans la requête montante. Ce comportement peut être
contrôlé à l'aide de variables
d'environnement. Ainsi, si elle est définie, la variable
proxy-sendcl
assure une compatibilité maximale avec les
serveurs demandés en imposant l'envoi de l'en-tête
Content-Length
, alors que
proxy-sendchunked
diminue la consommation de ressources
en imposant l'utilisation d'un codage à fractionnement.
Dans certaines circonstances, le serveur doit mettre en file d'attente sur disque les corps de requêtes afin de satisfaire le traitement demandé des corps de requêtes. Par exemple, cette mise en file d'attente se produira si le corps original a été envoyé selon un codage morcelé (et possède une taille importante), alors que l'administrateur a demandé que les requêtes du serveur d'arrière-plan soient envoyées avec l'en-tête Content-Length ou en HTTP/1.0. Cette mise en file d'attente se produira aussi si le corps de la requête contient déjà un en-tête Content-Length, alors que le serveur est configuré pour filtrer les corps des requêtes entrantes.
La directive LimitRequestBody
ne s'applique qu'aux
corps de requêtes que le serveur met en file d'attente sur disque.
Lorsqu'il est configuré en mode mandataire inverse (en utilisant
par exemple la directive ProxyPass
),
mod_proxy_http
ajoute plusieurs en-têtes de requête
afin de transmettre des informations au serveur demandé. Ces
en-têtes sont les suivants :
X-Forwarded-For
X-Forwarded-Host
Host
.X-Forwarded-Server
Ces en-têtes doivent être utilisés avec précautions sur le
serveur demandé, car ils contiendront plus d'une valeur (séparées
par des virgules) si la requête originale contenait déjà un de ces
en-têtes. Par exemple, vous pouvez utiliser
%{X-Forwarded-For}i
dans la chaîne de format du journal
du serveur demandé pour enregistrer les adresses IP des clients
originaux, mais il est possible que vous obteniez plusieurs adresses
si la requête passe à travers plusieurs mandataires.
Voir aussi les directives ProxyPreserveHost
et ProxyVia
directives, qui permettent
de contrôler d'autres en-têtes de requête.
Note : Si vous devez ajouter des en-têtes particuliers à la
requête mandatée, utilisez la directive RequestHeader
.
Description: | Number of additional Balancers that can be added Post-configuration |
---|---|
Syntaxe: | BalancerGrowth # |
Défaut: | BalancerGrowth 5 |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | BalancerGrowth is only available in Apache HTTP Server 2.3.13 and later. |
This directive allows for growth potential in the number of Balancers available for a virtualhost in addition to the number pre-configured. It only takes effect if there is at least one pre-configured Balancer.
Description: | Inherit proxy Balancers/Workers defined from the main server |
---|---|
Syntaxe: | BalancerInherit On|Off |
Défaut: | BalancerInherit On |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | BalancerInherit is only available in Apache HTTP Server 2.4.5 and later. |
This directive will cause the current server/vhost to "inherit" Balancers and Workers defined in the main server. This can cause issues and inconsistent behavior if using the Balancer Manager for dynamic changes and so should be disabled if using that feature.
The setting in the global server defines the default for all vhosts.
Disabling ProxyPassInherit
also disables BalancerInherit.
Description: | Add a member to a load balancing group |
---|---|
Syntaxe: | BalancerMember [balancerurl] url [key=value [key=value ...]] |
Contexte: | répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive adds a member to a load balancing group. It can be used
within a <Proxy balancer://...>
container
directive and can take any of the key value pair parameters available to
ProxyPass
directives.
One additional parameter is available only to BalancerMember
directives:
loadfactor. This is the member load factor - a decimal between 1.0
(default) and 100.0, which defines the weighted load to be applied to the
member in question.
The balancerurl is only needed when not within a
<Proxy balancer://...>
container directive. It corresponds to the url of a balancer defined in
ProxyPass
directive.
The path component of the balancer URL in any
<Proxy balancer://...>
container directive
is ignored.
Trailing slashes should typically be removed from the URL of a
BalancerMember
.
Description: | Attempt to persist changes made by the Balancer Manager across restarts. |
---|---|
Syntaxe: | BalancerPersist On|Off |
Défaut: | BalancerPersist Off |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | BalancerPersist is only available in Apache HTTP Server 2.4.4 and later. |
This directive will cause the shared memory storage associated with the balancers and balancer members to be persisted across restarts. This allows these local changes to not be lost during the normal restart/graceful state transitions.
Description: | Hosts, domains, or networks that will be connected to directly |
---|---|
Syntaxe: | NoProxy host [host] ... |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This directive is only useful for Apache httpd proxy servers within
intranets. The NoProxy
directive specifies a
list of subnets, IP addresses, hosts and/or domains, separated by
spaces. A request to a host which matches one or more of these is
always served directly, without forwarding to the configured
ProxyRemote
proxy server(s).
ProxyRemote * http://firewall.example.com:81 NoProxy .example.com 192.168.112.0/21
The host arguments to the NoProxy
directive are one of the following type list:
A Domain is a partially qualified DNS domain name, preceded by a period. It represents a list of hosts which logically belong to the same DNS domain or zone (i.e., the suffixes of the hostnames are all ending in Domain).
.com .example.org.
To distinguish Domains from Hostnames (both syntactically and semantically; a DNS domain can have a DNS A record, too!), Domains are always written with a leading period.
Domain name comparisons are done without regard to the case, and
Domains are always assumed to be anchored in the root of the
DNS tree; therefore, the two domains .ExAmple.com
and
.example.com.
(note the trailing period) are considered
equal. Since a domain comparison does not involve a DNS lookup, it is much
more efficient than subnet comparison.
A SubNet is a partially qualified internet address in numeric (dotted quad) form, optionally followed by a slash and the netmask, specified as the number of significant bits in the SubNet. It is used to represent a subnet of hosts which can be reached over a common network interface. In the absence of the explicit net mask it is assumed that omitted (or zero valued) trailing digits specify the mask. (In this case, the netmask can only be multiples of 8 bits wide.) Examples:
192.168
or 192.168.0.0
255.255.0.0
)192.168.112.0/21
192.168.112.0/21
with a netmask of 21
valid bits (also used in the form 255.255.248.0
)As a degenerate case, a SubNet with 32 valid bits is the equivalent to an IPAddr, while a SubNet with zero valid bits (e.g., 0.0.0.0/0) is the same as the constant _Default_, matching any IP address.
A IPAddr represents a fully qualified internet address in numeric (dotted quad) form. Usually, this address represents a host, but there need not necessarily be a DNS domain name connected with the address.
192.168.123.7
An IPAddr does not need to be resolved by the DNS system, so it can result in more effective apache performance.
A Hostname is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the DNS domain name service. It represents a logical host (in contrast to Domains, see above) and must be resolvable to at least one IPAddr (or often to a list of hosts with different IPAddrs).
prep.ai.example.edu
www.example.org
In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Name resolution in Apache httpd can take a remarkable deal of time when the connection to the name server uses a slow PPP link.
Hostname comparisons are done without regard to the case,
and Hostnames are always assumed to be anchored in the root
of the DNS tree; therefore, the two hosts WWW.ExAmple.com
and www.example.com.
(note the trailing period) are
considered equal.
Description: | Container for directives applied to proxied resources |
---|---|
Syntaxe: | <Proxy wildcard-url> ...</Proxy> |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Directives placed in <Proxy>
sections apply only to matching proxied content. Shell-style wildcards are
allowed.
For example, the following will allow only hosts in
yournetwork.example.com
to access content via your proxy
server:
<Proxy *> Require host yournetwork.example.com </Proxy>
The following example will process all files in the foo
directory of example.com
through the INCLUDES
filter when they are sent through the proxy server:
<Proxy http://example.com/foo/*> SetOutputFilter INCLUDES </Proxy>
The next example will allow web clients from the specified IP
addresses to issue CONNECT
requests to access the
https://www.example.com/
SSL server if
mod_proxy_connect
is enabled.
<Proxy www.example.com:443> Require ip 192.168.0.0/16 </Proxy>
A backend URL matches the configuration section if it begins with the
the wildcard-url string, even if the last path segment in the
directive only matches a prefix of the backend URL. For example,
<Proxy http://example.com/foo> matches all of
http://example.com/foo, http://example.com/foo/bar, and
http://example.com/foobar. The matching of the final URL differs
from the behavior of the <Location>
section, which for purposes of this note
treats the final path component as if it ended in a slash.
For more control over the matching, see <ProxyMatch>
.
Description: | Add proxy information in X-Forwarded-* headers |
---|---|
Syntaxe: | ProxyAddHeaders Off|On |
Défaut: | ProxyAddHeaders On |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | Available in version 2.3.10 and later |
This directive determines whether or not proxy related information should be passed to the backend server through X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server HTTP headers.
This option is of use only for HTTP proxying, as handled by mod_proxy_http
.
Description: | Determines how to handle bad header lines in a response |
---|---|
Syntaxe: | ProxyBadHeader IsError|Ignore|StartBody |
Défaut: | ProxyBadHeader IsError |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyBadHeader
directive determines the
behavior of mod_proxy
if it receives syntactically invalid
response header lines (i.e. containing no colon) from the origin
server. The following arguments are possible:
IsError
Ignore
StartBody
Description: | Disallow proxy requests to certain hosts |
---|---|
Syntaxe: | ProxyBlock *|hostname|partial-hostname [hostname|partial-hostname]... |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyBlock
directive can be used to
block FTP or HTTP access to certain hosts via the proxy, based on
a full or partial hostname match, or, if applicable, an IP address
comparison.
Each of the arguments to the ProxyBlock
directive can be either *
or a alphanumeric string.
At startup, the module will attempt to resolve every alphanumeric
string from a DNS name to a set of IP addresses, but any DNS errors
are ignored.
If an asterisk "*
" argument is specified,
mod_proxy
will deny access to all FTP or HTTP
sites.
Otherwise, for any request for an HTTP or FTP resource via the
proxy, mod_proxy
will check the hostname of the
request URI against each specified string. If a partial string
match is found, access is denied. If no matches against hostnames
are found, and a remote (forward) proxy is configured using
ProxyRemote
or
ProxyRemoteMatch
, access is allowed. If no
remote (forward) proxy is configured, the IP address of the
hostname from the URI is compared against all resolved IP
addresses determined at startup. Access is denied if any match is
found.
Note that the DNS lookups may slow down the startup time of the server.
ProxyBlock news.example.com auctions.example.com friends.example.com
Note that example
would also be sufficient to match any
of these sites.
Hosts would also be matched if referenced by IP address.
Note also that
ProxyBlock *
blocks connections to all sites.
Description: | Default domain name for proxied requests |
---|---|
Syntaxe: | ProxyDomain Domain |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This directive is only useful for Apache httpd proxy servers within
intranets. The ProxyDomain
directive specifies
the default domain which the apache proxy server will belong to. If a
request to a host without a domain name is encountered, a redirection
response to the same host with the configured Domain appended
will be generated.
ProxyRemote "*" "http://firewall.example.com:81" NoProxy ".example.com" "192.168.112.0/21" ProxyDomain ".example.com"
Description: | Override error pages for proxied content |
---|---|
Syntaxe: | ProxyErrorOverride On|Off |
Défaut: | ProxyErrorOverride Off |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive is useful for reverse-proxy setups where you want to
have a common look and feel on the error pages seen by the end user.
This also allows for included files (via
mod_include
's SSI) to get
the error code and act accordingly. (Default behavior would display
the error page of the proxied server. Turning this on shows the SSI
Error message.)
This directive does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses.
Description: | Determine size of internal data throughput buffer |
---|---|
Syntaxe: | ProxyIOBufferSize bytes |
Défaut: | ProxyIOBufferSize 8192 |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyIOBufferSize
directive adjusts the size
of the internal buffer which is used as a scratchpad for the data between
input and output. The size must be at least 512
.
In almost every case, there's no reason to change that value.
If used with AJP, this directive sets the maximum AJP packet size in
bytes. Values larger than 65536 are set to 65536. If you change it from
the default, you must also change the packetSize
attribute of
your AJP connector on the Tomcat side! The attribute
packetSize
is only available in Tomcat 5.5.20+
and 6.0.2+
Normally it is not necessary to change the maximum packet size. Problems with the default value have been reported when sending certificates or certificate chains.
Description: | Container for directives applied to regular-expression-matched proxied resources |
---|---|
Syntaxe: | <ProxyMatch regex> ...</ProxyMatch> |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The <ProxyMatch>
directive is
identical to the <Proxy>
directive, except that it matches URLs
using regular expressions.
From 2.4.8 onwards, named groups and backreferences are captured and
written to the environment with the corresponding name prefixed with
"MATCH_" and in upper case. This allows elements of URLs to be referenced
from within expressions and modules like
mod_rewrite
. In order to prevent confusion, numbered
(unnamed) backreferences are ignored. Use named groups instead.
<ProxyMatch ^http://(?<sitename>[^/]+)> require ldap-group cn=%{env:MATCH_SITENAME},ou=combined,o=Example </ProxyMatch>
Description: | Maximium number of proxies that a request can be forwarded through |
---|---|
Syntaxe: | ProxyMaxForwards number |
Défaut: | ProxyMaxForwards -1 |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyMaxForwards
directive specifies the
maximum number of proxies through which a request may pass if there's no
Max-Forwards
header supplied with the request. This may
be set to prevent infinite proxy loops or a DoS attack.
ProxyMaxForwards 15
Note that setting ProxyMaxForwards
is a
violation of the HTTP/1.1 protocol (RFC2616), which forbids a Proxy
setting Max-Forwards
if the Client didn't set it.
Earlier Apache httpd versions would always set it. A negative
ProxyMaxForwards
value, including the
default -1, gives you protocol-compliant behavior but may
leave you open to loops.
Description: | Maps remote servers into the local server URL-space |
---|---|
Syntaxe: | ProxyPass [path] !|url [key=value
[key=value ...]] [nocanon] [interpolate] [noquery] |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | Unix Domain Socket (UDS) support added in 2.4.7 |
This directive allows remote servers to be mapped into the space of the local server. The local server does not act as a proxy in the conventional sense but appears to be a mirror of the remote server. The local server is often called a reverse proxy or gateway. The path is the name of a local virtual path; url is a partial URL for the remote server and cannot include a query string.
<Directory>
and
<Files>
containers.ProxyRequests
directive should
usually be set off when using
ProxyPass
.In 2.4.7 and later, support for using a Unix Domain Socket is available by using a target
which prepends unix:/path/lis.sock|
. For example, to proxy
HTTP and target the UDS at /home/www/socket, you would use
unix:/home/www.socket|http://localhost/whatever/
. Since
the socket is local, the hostname used (in this case localhost
)
is moot, but it is passed as the Host: header value of the request.
unix:
URL is DefaultRuntimeDir
aware.RewriteRule
requires
the [P,NE]
option to prevent the '|'
character
from being escaped.When used inside a <Location>
section, the first argument is omitted and the local
directory is obtained from the <Location>
. The same will occur inside a
<LocationMatch>
section;
however, ProxyPass does not interpret the regexp as such, so it is necessary
to use ProxyPassMatch
in this situation instead.
Suppose the local server has address http://example.com/
;
then
<Location "/mirror/foo/"> ProxyPass "http://backend.example.com/" </Location>
will cause a local request for
http://example.com/mirror/foo/bar
to be internally converted
into a proxy request to http://backend.example.com/bar
.
If you require a more flexible reverse-proxy configuration, see the
RewriteRule
directive with the
[P]
flag.
The following alternative syntax is possible; however, it can carry a performance penalty when present in very large numbers. The advantage of the below syntax is that it allows for dynamic control via the Balancer Manager interface:
ProxyPass "/mirror/foo/" "http://backend.example.com/"
If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results.
The !
directive is useful in situations where you don't want
to reverse-proxy a subdirectory, e.g.
<Location "/mirror/foo/"> ProxyPass "http://backend.example.com/" </Location> <Location "/mirror/foo/i"> ProxyPass "!" </Location>
ProxyPass "/mirror/foo/i" "!" ProxyPass "/mirror/foo" "http://backend.example.com"
will proxy all requests to /mirror/foo
to
backend.example.com
except requests made to
/mirror/foo/i
.
The configured ProxyPass
and ProxyPassMatch
rules are checked in the order of configuration. The first rule that
matches wins. So usually you should sort conflicting
ProxyPass
rules starting with the
longest URLs first. Otherwise, later rules for longer URLS will be hidden
by any earlier rule which uses a leading substring of the URL. Note that
there is some relation with worker sharing. In contrast, only one
ProxyPass
directive can be placed
in a Location
block, and the most
specific location will take precedence.
For the same reasons, exclusions must come before the
general ProxyPass
directives. In 2.4.26 and later, the "no-proxy"
environment variable is an alternative to exclusions, and is the only
way to configure an exclusion of a ProxyPass
directive in Location
context.
This variable should be set with SetEnvIf
, as SetEnv
is not evaluated early enough.
ProxyPass key=value
Parameters
In Apache HTTP Server 2.1 and later, mod_proxy supports pooled
connections to a backend server. Connections created on demand
can be retained in a pool for future use. Limits on the pool size
and other settings can be coded on
the ProxyPass
directive
using key=value
parameters, described in the tables
below.
By default, mod_proxy will allow and retain the maximum number of
connections that could be used simultaneously by that web server child
process. Use the max
parameter to reduce the number from
the default. The pool of connections is maintained per web server child
process, and max
and other settings are not coordinated
among all child processes, except when only one child process is allowed
by configuration or MPM design.
Use the ttl
parameter to set an optional
time to live; connections which have been unused for at least
ttl
seconds will be closed. ttl
can be used
to avoid using a connection which is subject to closing because of the
backend server's keep-alive timeout.
ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
Worker|BalancerMember parameters |
---|
Parameter | Default | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
min | 0 | Minimum number of connection pool entries, unrelated to the actual number of connections. This only needs to be modified from the default for special circumstances where heap memory associated with the backend connections should be preallocated or retained. | ||||||||||||
max | 1...n | Maximum number of connections that will be allowed to the
backend server. The default for this limit is the number of threads
per process in the active MPM. In the Prefork MPM, this is always 1;
while with other MPMs, it is controlled by the
ThreadsPerChild directive. | ||||||||||||
smax | max | Retained connection pool entries above this limit are freed
during certain operations if they have been unused for longer than
the time to live, controlled by the ttl parameter. If
the connection pool entry has an associated connection, it will be
closed. This only needs to be modified from the default for special
circumstances where connection pool entries and any associated
connections which have exceeded the time to live need to be freed or
closed more aggressively. | ||||||||||||
acquire | - | If set, this will be the maximum time to wait for a free
connection in the connection pool, in milliseconds. If there are no free
connections in the pool, the Apache httpd will return SERVER_BUSY
status to the client.
| ||||||||||||
connectiontimeout | timeout | Connect timeout in seconds. The number of seconds Apache httpd waits for the creation of a connection to the backend to complete. By adding a postfix of ms, the timeout can be also set in milliseconds. Uses the time-interval directive syntax | ||||||||||||
disablereuse | Off | This parameter should be used when you want to force mod_proxy
to immediately close a connection to the backend after being used, and
thus, disable its persistent connection and pool for that backend.
This helps in various situations where a firewall between Apache
httpd and
the backend server (regardless of protocol) tends to silently
drop connections or when backends themselves may be under round-
robin DNS.
When connection reuse is enabled each backend domain is resolved
(with a DNS query) only once per child process and cached for all further
connections until the child is recycled. To disable connection reuse,
set this property value to On .
| ||||||||||||
enablereuse | On | This is the inverse of 'disablereuse' above, provided as a
convenience for scheme handlers that require opt-in for connection
reuse (such as mod_proxy_fcgi ).
| ||||||||||||
flushpackets | off | Determines whether the proxy module will auto-flush the output brigade after each "chunk" of data. 'off' means that it will flush only when needed; 'on' means after each chunk is sent; and 'auto' means poll/wait for a period of time and flush if no input has been received for 'flushwait' milliseconds. Currently, this is in effect only for mod_proxy_ajp and mod_proxy_fcgi. | ||||||||||||
flushwait | 10 | The time to wait for additional input, in milliseconds, before flushing the output brigade if 'flushpackets' is 'auto'. Uses time-interval directive syntax. | ||||||||||||
iobuffersize | 8192 | Adjusts the size of the internal scratchpad IO buffer. This allows you
to override the ProxyIOBufferSize for a specific worker.
This must be at least 512 or set to 0 for the system default of 8192.
| ||||||||||||
keepalive | Off | This parameter should be used when you have a firewall between your
Apache httpd and the backend server, which tends to drop inactive connections.
This flag will tell the Operating System to send The frequency of initial and subsequent TCP keepalive probes depends on global OS settings, and may be as high as 2 hours. To be useful, the frequency configured in the OS must be smaller than the threshold used by the firewall. Uses the time-interval directive syntax. | ||||||||||||
lbset | 0 | Sets the load balancer cluster set that the worker is a member of. The load balancer will try all members of a lower numbered lbset before trying higher numbered ones. | ||||||||||||
ping | 0 | Ping property tells the webserver to "test" the connection to
the backend before forwarding the request. For negative values,
the test is a simple socket check; for positive values, it's
a more functional check, dependent upon the protocol. For AJP, it causes
mod_proxy_ajp to send a CPING
request on the ajp13 connection (implemented on Tomcat 3.3.2+, 4.1.28+
and 5.0.13+). For HTTP, it causes mod_proxy_http
to send a 100-Continue to the backend (only valid for
HTTP/1.1 - for non HTTP/1.1 backends, this property has no
effect). In both cases, the parameter is the delay in seconds to wait
for the reply.
This feature has been added to avoid problems with hung and
busy backends.
This will increase the network traffic during the normal operation
which could be an issue, but it will lower the
traffic in case some of the cluster nodes are down or busy.
By adding a postfix of ms, the delay can be also set in
milliseconds. Uses the time-interval directive syntax.
| ||||||||||||
receivebuffersize | 0 | Adjusts the size of the explicit (TCP/IP) network buffer size for
proxied connections. This allows you to override the
ProxyReceiveBufferSize for a specific worker.
This must be at least 512 or set to 0 for the system default.
| ||||||||||||
redirect | - | Redirection Route of the worker. This value is usually set dynamically to enable safe removal of the node from the cluster. If set, all requests without session id will be redirected to the BalancerMember that has route parameter equal to this value. | ||||||||||||
retry | 60 | Connection pool worker retry timeout in seconds. If the connection pool worker to the backend server is in the error state, Apache httpd will not forward any requests to that server until the timeout expires. This enables to shut down the backend server for maintenance and bring it back online later. A value of 0 means always retry workers in an error state with no timeout. Uses the time-interval directive syntax. | ||||||||||||
route | - | Route of the worker when used inside load balancer. The route is a value appended to session id. | ||||||||||||
status | - | Single letter value defining the initial status of
this worker.
| ||||||||||||
timeout | ProxyTimeout |
Connection timeout in seconds. The number of seconds Apache httpd waits for data sent by / to the backend. Uses the time-interval directive syntax. | ||||||||||||
ttl | - | Time to live for inactive connections and associated connection pool entries, in seconds. Once reaching this limit, a connection will not be used again; it will be closed at some later time. Uses the time-interval directive syntax. | ||||||||||||
flusher | flush | Name of the provider used by | ||||||||||||
secret | - | Value of secret used by | ||||||||||||
upgrade | WebSocket | Protocol accepted in the Upgrade header by |
If the Proxy directive scheme starts with the
balancer://
(eg: balancer://cluster
,
any path information is ignored), then a virtual worker that does not really
communicate with the backend server will be created. Instead, it is responsible
for the management of several "real" workers. In that case, the special set of
parameters can be added to this virtual worker. See mod_proxy_balancer
for more information about how the balancer works.
Balancer parameters |
---|
Parameter | Default | Description |
---|---|---|
lbmethod | byrequests | Balancer load-balance method. Select the load-balancing scheduler
method to use. Either byrequests , to perform weighted
request counting; bytraffic , to perform weighted
traffic byte count balancing; or bybusyness , to perform
pending request balancing. The default is byrequests .
|
maxattempts | One less than the number of workers, or 1 with a single worker. | Maximum number of failover attempts before giving up. |
nofailover | Off | If set to On , the session will break if the worker is in
error state or disabled. Set this value to On if backend
servers do not support session replication.
|
stickysession | - | Balancer sticky session name. The value is usually set to something
like JSESSIONID or PHPSESSIONID ,
and it depends on the backend application server that support sessions.
If the backend application server uses different names for cookies
and url encoded id (like servlet containers), use | to separate them.
The first part is for the cookie; the second is for the path.Available in Apache HTTP Server 2.4.4 and later. |
stickysessionsep | "." | Sets the separation symbol in the session cookie. Some backend application servers do not use the '.' as the symbol. For example, the Oracle Weblogic server uses '!'. The correct symbol can be set using this option. The setting of 'Off' signifies that no symbol is used. |
scolonpathdelim | Off | If set to On , the semi-colon character ';' will be
used as an additional sticky session path delimiter/separator. This
is mainly used to emulate mod_jk's behavior when dealing with paths such
as JSESSIONID=6736bcf34;foo=aabfa
|
timeout | 0 | Balancer timeout in seconds. If set, this will be the maximum time to wait for a free worker. The default is to not wait. Uses the time-interval directive syntax. |
failonstatus | - | A single or comma-separated list of HTTP status codes. If set, this will force the worker into error state when the backend returns any status code in the list. Worker recovery behaves the same as other worker errors. |
failontimeout | Off | If set, an IO read timeout after a request is sent to the backend will
force the worker into error state. Worker recovery behaves the same as other
worker errors. Available in Apache HTTP Server 2.4.5 and later. |
nonce | <auto> | The protective nonce used in the balancer-manager application page.
The default is to use an automatically determined UUID-based
nonce, to provide for further protection for the page. If set,
then the nonce is set to that value. A setting of None
disables all nonce checking.
NoteIn addition to the nonce, the |
growth | 0 | Number of additional BalancerMembers to allow to be added to this balancer in addition to those defined at configuration. |
forcerecovery | On | Force the immediate recovery of all workers without considering the
retry parameter of the workers if all workers of a balancer are
in error state. There might be cases where an already overloaded backend
can get into deeper trouble if the recovery of all workers is enforced
without considering the retry parameter of each worker. In this case,
set to Off .Available in Apache HTTP Server 2.4.2 and later. |
A sample balancer setup:
ProxyPass "/special-area" "http://special.example.com" smax=5 max=10 ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofailover=On <Proxy balancer://mycluster> BalancerMember ajp://1.2.3.4:8009 BalancerMember ajp://1.2.3.5:8009 loadfactor=20 # Less powerful server, don't send as many requests there, BalancerMember ajp://1.2.3.6:8009 loadfactor=5 </Proxy>
Setting up a hot-standby that will only be used if no other members are available:
ProxyPass "/" "balancer://hotcluster/" <Proxy balancer://hotcluster> BalancerMember ajp://1.2.3.4:8009 loadfactor=1 BalancerMember ajp://1.2.3.5:8009 loadfactor=2.25 # The server below is on hot standby BalancerMember ajp://1.2.3.6:8009 status=+H ProxySet lbmethod=bytraffic </Proxy>
Additional ProxyPass Keywords
Normally, mod_proxy will canonicalise ProxyPassed URLs. But this may be incompatible with some backends, particularly those that make use of PATH_INFO. The optional nocanon keyword suppresses this and passes the URL path "raw" to the backend. Note that this keyword may affect the security of your backend, as it removes the normal limited protection against URL-based attacks provided by the proxy.
Normally, mod_proxy will include the query string when generating the SCRIPT_FILENAME environment variable. The optional noquery keyword (available in httpd 2.4.1 and later) prevents this.
The optional interpolate keyword, in combination with
ProxyPassInterpolateEnv
, causes the ProxyPass
to interpolate environment variables, using the syntax
${VARNAME}. Note that many of the standard CGI-derived
environment variables will not exist when this interpolation happens,
so you may still have to resort to mod_rewrite
for complex rules. Also note that interpolation is not supported
within the scheme portion of a URL. Dynamic determination of the
scheme can be accomplished with mod_rewrite
as in the
following example.
RewriteEngine On RewriteCond %{HTTPS} =off RewriteRule . - [E=protocol:http] RewriteCond %{HTTPS} =on RewriteRule . - [E=protocol:https] RewriteRule ^/mirror/foo/(.*) %{ENV:protocol}://backend.example.com/$1 [P] ProxyPassReverse "/mirror/foo/" "http://backend.example.com/" ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"
Description: | Inherit ProxyPass directives defined from the main server |
---|---|
Syntaxe: | ProxyPassInherit On|Off |
Défaut: | ProxyPassInherit On |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | ProxyPassInherit is only available in Apache HTTP Server 2.4.5 and later. |
This directive will cause the current server/vhost to "inherit"
ProxyPass
directives defined in the main server. This can cause issues and
inconsistent behavior if using the Balancer Manager for dynamic changes
and so should be disabled if using that feature.
The setting in the global server defines the default for all vhosts.
Disabling ProxyPassInherit also disables BalancerInherit
.
Description: | Enable Environment Variable interpolation in Reverse Proxy configurations |
---|---|
Syntaxe: | ProxyPassInterpolateEnv On|Off |
Défaut: | ProxyPassInterpolateEnv Off |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive, together with the interpolate argument to
ProxyPass
, ProxyPassReverse
,
ProxyPassReverseCookieDomain
, and
ProxyPassReverseCookiePath
,
enables reverse proxies to be dynamically
configured using environment variables which may be set by
another module such as mod_rewrite
.
It affects the ProxyPass
,
ProxyPassReverse
,
ProxyPassReverseCookieDomain
, and
ProxyPassReverseCookiePath
directives
and causes them to substitute the value of an environment
variable varname
for the string ${varname}
in configuration directives if the interpolate option is set.
Keep this turned off (for server performance) unless you need it!
Description: | Maps remote servers into the local server URL-space using regular expressions |
---|---|
Syntaxe: | ProxyPassMatch [regex] !|url [key=value
[key=value ...]] |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive is equivalent to ProxyPass
but makes use of regular expressions instead of simple prefix matching. The
supplied regular expression is matched against the url, and if it
matches, the server will substitute any parenthesized matches into the given
string and use it as a new url.
<Directory>
context.Suppose the local server has address http://example.com/
;
then
ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com/$1"
will cause a local request for
http://example.com/foo/bar.gif
to be internally converted
into a proxy request to http://backend.example.com/foo/bar.gif
.
The URL argument must be parsable as a URL before regexp substitutions (as well as after). This limits the matches you can use. For instance, if we had used
ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"
in our previous example, it would fail with a syntax error at server startup. This is a bug (PR 46665 in the ASF bugzilla), and the workaround is to reformulate the match:
ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"
The !
directive is useful in situations where you don't want
to reverse-proxy a subdirectory.
When used inside a <LocationMatch>
section, the first argument is omitted and the
regexp is obtained from the <LocationMatch>
.
If you require a more flexible reverse-proxy configuration, see the
RewriteRule
directive with the
[P]
flag.
When the URL parameter doesn't use any backreferences into the regular expression, the original URL will be appended to the URL parameter.
Take care when constructing the target URL of the rule, considering the security impact from allowing the client influence over the set of URLs to which your server will act as a proxy. Ensure that the scheme and hostname part of the URL is either fixed or does not allow the client undue influence.
Description: | Adjusts the URL in HTTP response headers sent from a reverse proxied server |
---|---|
Syntaxe: | ProxyPassReverse [path] url
[interpolate] |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive lets Apache httpd adjust the URL in the Location
,
Content-Location
and URI
headers on HTTP
redirect responses. This is essential when Apache httpd is used as a
reverse proxy (or gateway) to avoid bypassing the reverse proxy
because of HTTP redirects on the backend servers which stay behind
the reverse proxy.
Only the HTTP response headers specifically mentioned above
will be rewritten. Apache httpd will not rewrite other response
headers, nor will it by default rewrite URL references inside HTML pages.
This means that if the proxied content contains absolute URL
references, they will bypass the proxy. To rewrite HTML content to
match the proxy, you must load and enable mod_proxy_html
.
path is the name of a local virtual path; url is a
partial URL for the remote server. These parameters are used the same way as
for the ProxyPass
directive.
For example, suppose the local server has address
http://example.com/
; then
ProxyPass "/mirror/foo/" "http://backend.example.com/" ProxyPassReverse "/mirror/foo/" "http://backend.example.com/" ProxyPassReverseCookieDomain backend.example.com public.example.com ProxyPassReverseCookiePath "/" "/mirror/foo/"
will not only cause a local request for the
http://example.com/mirror/foo/bar
to be internally converted
into a proxy request to http://backend.example.com/bar
(the functionality which ProxyPass
provides here).
It also takes care of redirects which the server backend.example.com
sends
when redirecting http://backend.example.com/bar
to
http://backend.example.com/quux
. Apache httpd adjusts this to
http://example.com/mirror/foo/quux
before forwarding the HTTP
redirect response to the client. Note that the hostname used for
constructing the URL is chosen in respect to the setting of the UseCanonicalName
directive.
Note that this ProxyPassReverse
directive can
also be used in conjunction with the proxy feature
(RewriteRule ... [P]
) from mod_rewrite
because it doesn't depend on a corresponding ProxyPass
directive.
The optional interpolate keyword, used together with
ProxyPassInterpolateEnv
, enables interpolation
of environment variables specified using the format ${VARNAME}.
Note that interpolation is not supported within the scheme portion of a
URL.
When used inside a <Location>
section, the first argument is omitted and the local
directory is obtained from the <Location>
. The same occurs inside a <LocationMatch>
section, but will probably not work as
intended, as ProxyPassReverse will interpret the regexp literally as a
path; if needed in this situation, specify the ProxyPassReverse outside
the section or in a separate <Location>
section.
This directive is not supported in <Directory>
or <Files>
sections.
Description: | Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server |
---|---|
Syntaxe: | ProxyPassReverseCookieDomain internal-domain
public-domain [interpolate] |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
Usage is basically similar to
ProxyPassReverse
, but instead of
rewriting headers that are a URL, this rewrites the domain
string in Set-Cookie
headers.
Description: | Adjusts the Path string in Set-Cookie headers from a reverse- proxied server |
---|---|
Syntaxe: | ProxyPassReverseCookiePath internal-path
public-path [interpolate] |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
Useful in conjunction with
ProxyPassReverse
in situations where backend URL paths are mapped to public paths on the
reverse proxy. This directive rewrites the path
string in
Set-Cookie
headers. If the beginning of the cookie path matches
internal-path, the cookie path will be replaced with
public-path.
In the example given with
ProxyPassReverse
, the directive:
ProxyPassReverseCookiePath "/" "/mirror/foo/"
will rewrite a cookie with backend path /
(or
/example
or, in fact, anything) to /mirror/foo/
.
Description: | Use incoming Host HTTP request header for proxy request |
---|---|
Syntaxe: | ProxyPreserveHost On|Off |
Défaut: | ProxyPreserveHost Off |
Contexte: | configuration du serveur, serveur virtuel, répertoire |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | Usable in directory context in 2.3.3 and later. |
When enabled, this option will pass the Host: line from the incoming
request to the proxied host, instead of the hostname specified in the
ProxyPass
line.
This option should normally be turned Off
. It is mostly
useful in special configurations like proxied mass name-based virtual
hosting, where the original Host header needs to be evaluated by the
backend server.
Description: | Network buffer size for proxied HTTP and FTP connections |
---|---|
Syntaxe: | ProxyReceiveBufferSize bytes |
Défaut: | ProxyReceiveBufferSize 0 |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyReceiveBufferSize
directive specifies an
explicit (TCP/IP) network buffer size for proxied HTTP and FTP connections,
for increased throughput. It has to be greater than 512
or set
to 0
to indicate that the system's default buffer size should
be used.
ProxyReceiveBufferSize 2048
Description: | Remote proxy used to handle certain requests |
---|---|
Syntaxe: | ProxyRemote match remote-server |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This defines remote proxies to this proxy. match is either the
name of a URL-scheme that the remote server supports, or a partial URL
for which the remote server should be used, or *
to indicate
the server should be contacted for all requests. remote-server is
a partial URL for the remote server. Syntax:
remote-server =
scheme://hostname[:port]
scheme is effectively the protocol that should be used to
communicate with the remote server; only http
and https
are supported by this module. When using https
, the requests
are forwarded through the remote proxy using the HTTP CONNECT method.
ProxyRemote http://goodguys.example.com/ http://mirrorguys.example.com:8000 ProxyRemote * http://cleverproxy.localdomain ProxyRemote ftp http://ftpproxy.mydomain:8080
In the last example, the proxy will forward FTP requests, encapsulated as yet another HTTP proxy request, to another proxy which can handle them.
This option also supports reverse proxy configuration; a backend webserver can be embedded within a virtualhost URL space even if that server is hidden by another forward proxy.
Description: | Remote proxy used to handle requests matched by regular expressions |
---|---|
Syntaxe: | ProxyRemoteMatch regex remote-server |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
The ProxyRemoteMatch
is identical to the
ProxyRemote
directive, except that
the first argument is a regular expression
match against the requested URL.
Description: | Enables forward (standard) proxy requests |
---|---|
Syntaxe: | ProxyRequests On|Off |
Défaut: | ProxyRequests Off |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This allows or prevents Apache httpd from functioning as a forward proxy
server. (Setting ProxyRequests to Off
does not disable use of
the ProxyPass
directive.)
In a typical reverse proxy or gateway configuration, this
option should be set to
Off
.
In order to get the functionality of proxying HTTP or FTP sites, you
need also mod_proxy_http
or mod_proxy_ftp
(or both) present in the server.
In order to get the functionality of (forward) proxying HTTPS sites, you
need mod_proxy_connect
enabled in the server.
Do not enable proxying with ProxyRequests
until you have secured your server. Open proxy servers are dangerous
both to your network and to the Internet at large.
Description: | Set various Proxy balancer or member parameters |
---|---|
Syntaxe: | ProxySet url key=value [key=value ...] |
Contexte: | répertoire |
Statut: | Extension |
Module: | mod_proxy |
This directive is used as an alternate method of setting any of the
parameters available to Proxy balancers and workers normally done via the
ProxyPass
directive. If used
within a <Proxy balancer url|worker url>
container directive, the url argument is not required. As a side
effect the respective balancer or worker gets created. This can be useful
when doing reverse proxying via a
RewriteRule
instead of a
ProxyPass
directive.
<Proxy balancer://hotcluster> BalancerMember http://www2.example.com:8080 loadfactor=1 BalancerMember http://www3.example.com:8080 loadfactor=2 ProxySet lbmethod=bytraffic </Proxy>
<Proxy http://backend> ProxySet keepalive=On </Proxy>
ProxySet balancer://foo lbmethod=bytraffic timeout=15
ProxySet ajp://backend:7001 timeout=15
Keep in mind that the same parameter key can have a different meaning depending whether it is applied to a balancer or a worker, as shown by the two examples above regarding timeout.
Description: | Set local IP address for outgoing proxy connections |
---|---|
Syntaxe: | ProxySourceAddress address |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
Compatibilité: | Available in version 2.3.9 and later |
This directive allows to set a specific local address to bind to when connecting to a backend server.
Description: | Show Proxy LoadBalancer status in mod_status |
---|---|
Syntaxe: | ProxyStatus Off|On|Full |
Défaut: | ProxyStatus Off |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This directive determines whether or not proxy
loadbalancer status data is displayed via the mod_status
server-status page.
Full is synonymous with On
Description: | Network timeout for proxied requests |
---|---|
Syntaxe: | ProxyTimeout time-interval[s] |
Défaut: | Value of |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This directive allows a user to specifiy a timeout on proxy requests. This is useful when you have a slow/buggy appserver which hangs, and you would rather just return a timeout and fail gracefully instead of waiting however long it takes the server to return.
Description: | Information provided in the Via HTTP response
header for proxied requests |
---|---|
Syntaxe: | ProxyVia On|Off|Full|Block |
Défaut: | ProxyVia Off |
Contexte: | configuration du serveur, serveur virtuel |
Statut: | Extension |
Module: | mod_proxy |
This directive controls the use of the Via:
HTTP
header by the proxy. Its intended use is to control the flow of
proxy requests along a chain of proxy servers. See RFC 2616 (HTTP/1.1), section
14.45 for an explanation of Via:
header lines.
Off
, which is the default, no special processing
is performed. If a request or reply contains a Via:
header,
it is passed through unchanged.On
, each request and reply will get a
Via:
header line added for the current host.Full
, each generated Via:
header
line will additionally have the Apache httpd server version shown as a
Via:
comment field.Block
, every proxy request will have all its
Via:
header lines removed. No new Via:
header will
be generated.