Translate a given prefix into a SCRIPT_NAME for the filtered application.
PrefixMiddleware provides a way to manually override the root prefix (SCRIPT_NAME) of your application for certain, rare situations.
When running an application under a prefix (such as '/james') in FastCGI/apache, the SCRIPT_NAME environment variable is automatically set to to the appropriate value: '/james'. Pylons' URL generating functions, such as url_for, always take the SCRIPT_NAME value into account.
One situation where PrefixMiddleware is required is when an application is accessed via a reverse proxy with a prefix. The application is accessed through the reverse proxy via the the URL prefix '/james', whereas the reverse proxy forwards those requests to the application at the prefix '/'.
The reverse proxy, being an entirely separate web server, has no way of specifying the SCRIPT_NAME variable; it must be manually set by a PrefixMiddleware instance. Without setting SCRIPT_NAME, url_for will generate URLs such as: '/purchase_orders/1', when it should be generating: '/james/purchase_orders/1'.
To filter your application through a PrefixMiddleware instance, add the following to the '[app:main]' section of your .ini file:
1 2 3 4 5
filter-with = proxy-prefix [filter:proxy-prefix] use = egg:PasteDeploy#prefix prefix = /james
The name proxy-prefix simply acts as an identifier of the filter section; feel free to rename it.
Also, unless disabled, the X-Forwarded-Server header will be translated to the Host header, for cases when that header is lost in the proxying.
If force_port is set, SERVER_PORT and HTTP_HOST will be rewritten with the given port. You can use a number, string (like '80') or the empty string (whatever is the default port for the scheme). This is useful in situations where there is port forwarding going on, and the server believes itself to be on a different port than what the outside world sees.
You can also use scheme to explicitly set the scheme (like scheme = https).
f __init__(self, app, global_conf=None, prefix='/', translate_forwarded_server=True, force_port=None, scheme=None) ...
See the source for more information.