Helicon Ape

mod_proxy

Overview

mod_proxy provides a set of instruments for flexible adjustment of forward or reverse proxy on your server.

Reverse proxy

Forward proxy

mod_proxy as balancer with php sticky sessions

Quick start

Sample httpd.conf configuration to enable proxying /accounts/ application to internal server

<Location /accounts/>
  ProxyPass http://internal.company.com/accounts/
  ProxyPassReverse http://internal.company.com/accounts/
  ProxyPassReverseCookieDomain internal.company.com www.company.com
</Location>

Related articles and topics

Directives

Name Context Description
BalancerMember S V D .h Add a member to a load balancing group
NoProxy S V D .h Hosts, domains, or networks that will be connected to directly
ProxyBlock S V D .h Words, hosts, or domains that are banned from being proxied
ProxyIOBufferSize S V D .h Determine size of internal data throughput buffer
ProxyMaxForwards S V D .h Maximium number of proxies that a request can be forwarded through
ProxyPass S V D .h Maps remote servers into the local server URL-space
ProxyPassReverse S V D .h Adjusts the URL in HTTP response headers sent from a reverse proxied server
ProxyPassReverseCookieDomain S V D .h Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server
ProxyPassReverseCookiePath S V D .h Adjusts the Path string in Set-Cookie headers from a reverse- proxied server
ProxyPreserveHost S V D .h Use incoming Host HTTP request header for proxy request
ProxyReceiveBufferSize S V D .h Network buffer size for proxied HTTP and FTP connections
ProxyRemoteMatch S V D .h Remote proxy used to handle requests matched by regular expressions
ProxyRequests S V D .h Enables forward (standard) proxy requests
ProxyTimeout S V D .h Network timeout for proxied requests
ProxyVia S V D .h Information provided in the Via HTTP response header for proxied requests

Handlers

Name Context Description
balancer-manager S V D .h Maps specific url to load balancer web interface

Assign balancer-manager handler to specific url to enable load balancer web interface.
Note! This url must be secured with mod_authz_host or mod_auth_basic .

<Location /balancer-manager/>
SetHandler balancer-manager
Order allow,deny
Allow from 127.0.0.7 ::1 localhost
</Location>

BalancerMemeber

Add a member to a load balancing group

Syntax

BalancerMember [balancer-url] backend-url [key=value] [...]

Description

This directive adds a member to a load balancing group. It must be used within a <Proxy balancer://...> container directive.

Adjustment

key=value are used to for adjustment of balancer member.

  • timeout — Connection timeout in seconds. If not set, will wait until the free connection is available. This directive is used for limiting the number of connections to the backend server
  • loadfactor — Worker load factor. Used with BalancerMember . It is a value between 1 and 100 that defines the normalized weighted load applied to the server (balancer member)
  • route — Route of the server (balancer member) when used inside load balancer. The route is a value appended to session id
  • redirect — Redirection Route of the server (balancer member). 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 balancer member whose route parameter equals this value.
  • statusttl — Automatic update status interval in seconds.

Example

ProxyPass / balancer://cluster/ lbmethod=byrequests stickysession=seesionid
<Proxy balancer://cluster>
	BalancerMember http://backend1.example.com/ route=b1 loadfactor=10 statusttl=60
	BalancerMember http://backend2.example.com/ route=b2 loadfactor=5  
</Proxy>

BalancerMember balancer://cluster http://backend3.example.com/ route=b3 loadfactor=1

NoProxy

Hosts, domains, or networks that will be connected to directly

Syntax

NoProxy host [host] [...]

Description

NoProxy directive is only applicable to proxy servers within intranets. NoProxy directive stores the list of subnets, IP addresses, hosts and/or domains, separated by spaces. A request to the host from the list will be processed directly without forwarding to ProxyRemote proxy server(s).

Example

ProxyRemote * http://firewall.mycompany.com:81
NoProxy .mycompany.com 192.168.112.0/21

The host arguments for NoProxy may be everything from the list:

  • 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 all end up with Domain ).
    NoProxy .com .domain.org.
    To distinguish Domains from Hostnames , Domains are always written with preceding period.
    Note! Domain name comparisons are performed regardless of case, and Domains are always supposed to be anchored to the root of DNS tree, therefore .MyDomain.com and .mydomain.com. (note the trailing period) are considered equal. As domain comparison does not involve a DNS lookup, it is much more efficient than SubNet comparison.
  • 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.)
    NoProxy 192.168 192.168.0.0
    the subnet 192.168.0.0 with an implied netmask of 16 valid bits (may be used in the netmask form 255.255.0.0)
    NoProxy 192.168.112.0/21
    the subnet 192.168.112.0/21 with a netmask of 21 valid bits (may be 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.
  • 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.
    NoProxy 192.168.123.7
    Note! An IPAddr does not need to be resolved by the DNS system, so it can result in more effective server performance.

  • Hostname — is a fully qualified DNS domain name which can be resolved to one or more IPAddrs via the domain name service (DNS). 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 ).
    NoProxy prep.ai.mit.edu www.apache.org

Note! In many situations, it is more effective to specify an IPAddr in place of a Hostname since a DNS lookup can be avoided. Hostname comparisons are done regardless of case, and Hostnames are always assumed anchored to the root of the DNS tree, therefore two hosts WWW.MyDomain.com and www.mydomain.com. (note the trailing period) are considered equal.

ProxyBlock

Words, hosts, or domains that are banned from being proxied

Syntax

ProxyBlock *|word|host|domain [word|host|domain] [...]

Description

ProxyBlock directive specifies a list of words, hosts and/or domains, separated by spaces. HTTP, HTTPS, and FTP access to the sites whose names contain specified words, hosts or domains will be blocked by proxy server. The proxy module will also attempt to determine IP addresses of list items and cache them for match against as well. That may slow down the server startup time.

Example

ProxyBlock somesite.com some-host.ru sub.domain.gov

sub.domain.gov will also be matched if requested by IP address.

Note also that

ProxyBlock * 

blocks connections to all sites.

ProxyIOBufferSize

Determine size of internal data throughput buffer

Syntax

ProxyIOBufferSize bytes

Default

ProxyIOBufferSize 8192

Description

ProxyIOBufferSize directive allows o set internal buffer size, which acts as a temporary buffer for the data between input and output. The size must be less or equal to 8192.

Note! There are hardly any cases when you need to change that value.

ProxyMaxForwards

Maximium number of proxies that a request can be forwarded through

Syntax

ProxyMaxForwards number

Default

ProxyMaxForwards 10

Description

ProxyMaxForwards directive specifies the maximum number of proxies through which a request may walk, if no Max-Forwards header exists in the request. This directive allows to avoid infinite proxy.

Example

ProxyMaxForwards 15 

ProxyPass

Maps remote servers into the local server URL-space

Syntax

ProxyPass [path] !|backend-url [key=value key=value ...]]

Description

ProxyPass 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. path is the name of a local virtual path; backend-url is a partial URL for the remote server and cannot include a query string.

Note! If you put ProxyPass directive into httpd.conf file, it's necessary to explicitly specify path parameter; BUT when using this directive inside <Location> section or .htaccess , this parameter shall be omitted (mod_proxy will automatically apply path specified in <Location> section or path to .htaccess file as a ProxyPass path). So

ProxyPass /app/ http://backend.domain.com/

equals to

<Location /app/>
ProxyPass http://backend.domain.com/
</Location>

ProxyRequests directive should usually be set off when using ProxyPass .

Say you have a local server http://domain.com/ then

ProxyPass /mirror/foo/ http://backend.domain.com/

will cause a local request to http://domain.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.domain.com/bar .

The ! directive is used when you don't want to reverse proxy some subdirectory.

Example:

ProxyPass /mirror/foo/i !
ProxyPass /mirror/foo http://backend.domain.com

will proxy all requests to /mirror/foo backend.domain.com except requests to /mirror/foo/i .

Note! Order is important. you need to put the exclusions before the general ProxyPass directive.

Adjustment of load balancing

And here is the list of parameters used when proxy acts as load balancer:

  • lbmethod = byrequests | bytraffic | random | byresponsetime — Balancer load-balance method. Possible values:
    • byrequests to perform weighted request counting;
    • bytraffic to perform weighted traffic byte count balancing;
    • random to perform weighted random balancing;
    • byresponsetime to perform weighted response time balancing;
  • stickysession — Balancer sticky session name. Common values are JSESSIONID or PHPSESSIONID, they depend on the backend application server that supports sessions.
  • routeregex — Regular expression to grab the balancer route from sticky session cookie. For example: routeregex=[\.!](.*)$ .
  • nofailover =off — If set to on , the session will break if the balancer member is in error state or disabled. Set this value to on if backend servers do not support session replication.
  • timeout — Balancer timeout in seconds. If set, this will be the maximum time to wait for a free balancer member.
  • maxattempts — Maximum number of failover attempts before giving up

Examples

ProxyPass /folder/proxy/balancer/fake/ balancer://cluster1/
<Proxy balancer://cluster1>
BalancerMember http://localhost:80/folder/proxy/balancer/real/ loadfactor=1
BalancerMember http://localhost:81/folder/proxy/balancer/real/ loadfactor=1
</Proxy>
ProxyPass /ape/proxy/balancer/faketraff/ balancer://cluster2/ lbmethod=bytraffic
<Proxy balancer://clustersession>
BalancerMember http://localhost:80/ape/proxy/balancer/real/ loadfactor=100 route=p80
BalancerMember http://localhost:81/ape/proxy/balancer/real/ loadfactor=1 route=p81
BalancerMember http://localhost:82/ape/proxy/balancer/real/ loadfactor=1 route=p82
BalancerMember http://localhost:83/ape/proxy/balancer/real/ loadfactor=1 route=p83 redirect=p82 status=+d </Proxy>

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location> .

If you need more flexible reverse proxy configuration, consider using RewriteRule directive with [P] flag.

ProxyPassReverse

Adjusts the URL in HTTP response headers sent from a reverse proxied server

Syntax

ProxyPassReverse [path] url

Description

ProxyPassReverse directive allows to adjust the URL in the Location , Content-Location and URI headers of HTTP redirect responses. This is necessary when using reverse proxy to avoid by-passing reverse proxy because of HTTP redirects on the backend servers which stay behind reverse proxy.

Only aforementioned HTTP response headers will be rewritten. This means that if the proxied content contains absolute URL references, they will by-pass the proxy.

path is the name of a local virtual path; url is a partial URL for the remote server - they are used the same way as in ProxyPass directive.

Example

Say the local server has address http://domain.com/ .

ProxyPass /mirror/foo/ http://backend.domain.com/
ProxyPassReverse /mirror/foo/ http://backend.domain.com/
ProxyPassReverseCookieDomain backend.domain.com public.domain.com
ProxyPassReverseCookiePath / /mirror/foo/ 

The above code will cause a local request to http://domain.com/mirror/foo/bar to be internally treated as a proxy request to http://backend.domain.com/bar (ProxyPass functionality). It will also take care of redirects sent by backend.domain.com server: when it redirects http://backend.domain.com/bar to http://backend.domain.com/quux , *** adjusts this to http://domain.com/mirror/foo/quux before forwarding the HTTP redirect response to the client.

Note that ProxyPassReverse directive can also be used in conjunction with proxy pass-through feature ( RewriteRule ... [P] ) from mod_rewrite because it doesn't depend on a corresponding ProxyPass directive.

When used inside a <Location> section, the first argument is omitted and the local directory is obtained from the <Location> .

ProxyPassReverseCookieDomain

Adjusts the Domain string in Set-Cookie headers from a reverse-proxied server.

Syntax

ProxyPassReverseCookieDomain internal-domain public-domain

ProxyPassReverseCookieDomain is used similarly to ProxyPassReverse , but it rewrites domain string in Set-Cookie headers.

ProxyPassReverseCookiePath

Adjusts the Path string in Set-Cookie headers from a reverse- proxied server.

Syntax

ProxyPassReverseCookiePath internal-path public-path

ProxyPassReverseCookiePath is used similarly to ProxyPassReverse , but it rewrites the path string in Set-Cookie headers.

ProxyPreserveHost

Use incoming Host HTTP request header for proxy request

Syntax

ProxyPreserveHost On|Off 

Default

ProxyPreserveHost Off

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.

Warning! ProxyPreserveHost works only for the web-sites that use Application pool with .NET 4.0 and higher.

ProxyReceiveBufferSize

Network buffer size for proxied HTTP and FTP connections.

Syntax

ProxyReceiveBufferSize bytes

Default

ProxyReceiveBufferSize 0

ProxyReceiveBufferSize directive specifies an explicit TCP/IP network buffer size for proxied HTTP and FTP connections to provide increased throughput. It has to be greater than 512 or set to 0 to specify that system's default buffer size should be used.

Example

ProxyReceiveBufferSize 2048

ProxyRemote

Remote proxy used to handle certain requests

Syntax

ProxyRemote match remote-server 

ProxyRemote specifies remote proxies for this proxy. match is either the name of a URL-scheme supported by remote server, or a partial URL for which remote server should be used, or * to indicate the server should be addressed for all requests. remote-server is a partial URL for the remote server (only http protocol is supported.

Example

ProxyRemote http://thissite.com/ http://thatsite.com:8000
ProxyRemote * http://othersite.com
ProxyRemote ftp http://ftpproxy.domain.com:8080

ProxyRemote directive also supports reverse proxy configuration - a backend webserver can be embedded into a virtualhost URL space even if that server is hidden behind another forward proxy.

ProxyRemoteMatch

Remote proxy used to handle requests matched by regular expressions

Syntax

ProxyRemoteMatch regex remote-server

ProxyRemoteMatch is identical to the ProxyRemote directive, except that the first argument is a regular expression that is matched against the requested URL.

ProxyRequests

Enables forward (standard) proxy requests

Syntax

ProxyRequests On|Off 

Default

ProxyRequests Off

ProxyRequests directive enables or disables forward proxy functionality.

If you are implementing reverse proxy configuration, this option should be set to off .

Warning! Do not enable ProxyRequests feature until your server is secured. Open proxy servers are dangerous for your network as well as for the Internet as a whole.

ProxyTimeout

Network timeout for proxied requests

Syntax

ProxyTimeout seconds

Default

ProxyTimeout 300

ProxyTimeout directive allows you to specify a timeout for proxy requests. This is useful when you have a slow application server, and rather than wait unlimited time, it's better to return a timeout response.

ProxyVia

Information provided in the Via HTTP response header for proxied requests

Syntax

ProxyVia On|Off|Full|Block

Default

ProxyVia Off

Description

ProxyVia directive controls the use of the Via: HTTP header by the proxy. It is destined to control the flow of proxy requests through the chain of proxy servers.

The following values may be assigned to this directive:

  • Off (default) — no special processing is performed. If a request or reply contains Via: header, it is passed through unchanged.
  • On — each request and reply will get Via: header line added for the current host.
  • Full — each generated Via: header line will be appended by Helicon Ape 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.