Page MenuHomePhabricator
Differential D20785 Diff 49561 src/docs/user/configuration/configuring_preamble.diviner

Changeset View

Standalone View

View Options

src/docs/user/configuration/configuring_preamble.diviner

Show All 9 Lines
(usually, because it is behind a load balancer), it may not be able to detect (usually, because it is behind a load balancer), it may not be able to detect
some environmental features (like the client's IP, or the presence of SSL) some environmental features (like the client's IP, or the presence of SSL)
correctly. correctly.
You can use a special preamble script to make arbitrary adjustments to the You can use a special preamble script to make arbitrary adjustments to the
environment and some parts of Phabricator's configuration in order to fix these environment and some parts of Phabricator's configuration in order to fix these
problems and set up the environment which Phabricator expects. problems and set up the environment which Phabricator expects.
NOTE: This is an advanced feature. Most installs should not need to configure
a preamble script.
= Creating a Preamble Script = Creating a Preamble Script
==========================
To create a preamble script, write a file to: To create a preamble script, write a file to:
phabricator/support/preamble.php phabricator/support/preamble.php
(This file is in Phabricator's `.gitignore`, so you do not need to worry about (This file is in Phabricator's `.gitignore`, so you do not need to worry about
colliding with `git` or interacting with updates.) colliding with `git` or interacting with updates.)
This file should be a valid PHP script. If you aren't very familiar with PHP, This file should be a valid PHP script. If you aren't very familiar with PHP,
you can check for syntax errors with `php -l`: you can check for syntax errors with `php -l`:
phabricator/ $ php -l support/preamble.php phabricator/ $ php -l support/preamble.php
No syntax errors detected in support/preamble.php No syntax errors detected in support/preamble.php
If present, this script will be executed at the very beginning of each web If present, this script will be executed at the very beginning of each web
request, allowing you to adjust the environment. For common adjustments and request, allowing you to adjust the environment. For common adjustments and
examples, see the next sections. examples, see the next sections.
Adjusting Client IPs Adjusting Client IPs
==================== ====================
If your install is behind a load balancer, Phabricator may incorrectly detect If your install is behind a load balancer, Phabricator may incorrectly detect
all requests as originating from the load balancer, rather than from the all requests as originating from the load balancer, rather than from the
correct client IPs. correct client IPs.
If this is the case and some other header (like `X-Forwarded-For`) is known to In common cases where networks are configured like this, the `X-Forwarded-For`
be trustworthy, you can read the header and overwrite the `REMOTE_ADDR` value header will have trustworthy information about the real client IP. You
so Phabricator can figure out the client IP correctly. can use the function `preamble_trust_x_forwarded_for_header()` in your
preamble to tell Phabricator that you expect to receive requests from a
load balancer or proxy which modifies this header:
```name="Trust X-Forwarded-For Header", lang=php
preamble_trust_x_forwarded_for_header();
```
You should do this //only// if the `X-Forwarded-For` header is known to be You should do this //only// if the `X-Forwarded-For` header is known to be
trustworthy. In particular, if users can make requests to the web server trustworthy. In particular, if users can make requests to the web server
directly, they can provide an arbitrary `X-Forwarded-For` header, and thereby directly, they can provide an arbitrary `X-Forwarded-For` header, and thereby
spoof an arbitrary client IP. spoof an arbitrary client IP.
The `X-Forwarded-For` header may also contain a list of addresses if a request The `X-Forwarded-For` header may also contain a list of addresses if a request
has been forwarded through multiple loadbalancers. Using a snippet like this has been forwarded through multiple load balancers. If you know that requests
will usually handle most situations correctly: on your network are routed through `N` trustworthy devices, you can specify
that `N` to tell the function how many layers of `X-Forwarded-For` to discard:
```name="Trust X-Forwarded-For Header, Multiple Layers", lang=php
preamble_trust_x_forwarded_for_header(3);
``` ```
name=Overwrite REMOTE_ADDR with X-Forwarded-For
<?php
// Overwrite REMOTE_ADDR with the value in the "X-Forwarded-For" HTTP header. If you have an unusual network configuration (for example, the number of
trustworthy devices depends on the network path) you can also implement your
own logic.
// Only do this if you're certain the request is coming from a loadbalancer! Note that this is very odd, advanced, and easy to get wrong. If you get it
// If the request came directly from a client, doing this will allow them to wrong, users will most likely be able to spoof any client address.
// them spoof any remote address.
// The header may contain a list of IPs, like "1.2.3.4, 4.5.6.7", if the ```name="Custom X-Forwarded-For Handling", lang=php
// request the load balancer received also had this header.
if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) { if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
$forwarded_for = $_SERVER['HTTP_X_FORWARDED_FOR']; $raw_header = $_SERVER['X_FORWARDED_FOR'];
if ($forwarded_for) {
$forwarded_for = explode(',', $forwarded_for); $real_address = your_custom_parsing_function($raw_header);
$forwarded_for = end($forwarded_for);
$forwarded_for = trim($forwarded_for); $_SERVER['REMOTE_ADDR'] = $raw_header;
$_SERVER['REMOTE_ADDR'] = $forwarded_for;
}
} }
``` ```
Adjusting SSL Adjusting SSL
============= =============
If your install is behind an SSL terminating load balancer, Phabricator may If your install is behind an SSL terminating load balancer, Phabricator may
detect requests as HTTP when the client sees them as HTTPS. This can cause detect requests as HTTP when the client sees them as HTTPS. This can cause
Show All 22 Lines
Phabricator · Built by Phacility