Changeset View
Changeset View
Standalone View
Standalone View
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 | |||||