Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_preamble.diviner
@title Configuring a Preamble Script | @title Configuring a Preamble Script | ||||
@group config | @group config | ||||
Adjust environmental settings (SSL, remote IPs) using a preamble script. | Adjust environmental settings (SSL, remote IPs) using a preamble script. | ||||
Overview | Overview | ||||
======== | ======== | ||||
If Phabricator is deployed in an environment where HTTP headers behave oddly | If Phorge is deployed in an environment where HTTP headers behave oddly | ||||
(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 Phorge's configuration in order to fix these | ||||
problems and set up the environment which Phabricator expects. | problems and set up the environment which Phorge expects. | ||||
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 | phorge/support/preamble.php | ||||
(This file is in Phabricator's `.gitignore`, so you do not need to worry about | (This file is in Phorge'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 | phorge/ $ 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, Phorge 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. | ||||
In common cases where networks are configured like this, the `X-Forwarded-For` | In common cases where networks are configured like this, the `X-Forwarded-For` | ||||
header will have trustworthy information about the real client IP. You | header will have trustworthy information about the real client IP. You | ||||
can use the function `preamble_trust_x_forwarded_for_header()` in your | can use the function `preamble_trust_x_forwarded_for_header()` in your | ||||
preamble to tell Phabricator that you expect to receive requests from a | preamble to tell Phorge that you expect to receive requests from a | ||||
load balancer or proxy which modifies this header: | load balancer or proxy which modifies this header: | ||||
```name="Trust X-Forwarded-For Header", lang=php | ```name="Trust X-Forwarded-For Header", lang=php | ||||
preamble_trust_x_forwarded_for_header(); | 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 | ||||
Show All 25 Lines | if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) { | ||||
$_SERVER['REMOTE_ADDR'] = $real_address; | $_SERVER['REMOTE_ADDR'] = $real_address; | ||||
} | } | ||||
``` | ``` | ||||
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, Phorge 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 | ||||
Phabricator to generate links with the wrong protocol, issue cookies without | Phorge to generate links with the wrong protocol, issue cookies without | ||||
the SSL-only flag, or reject requests outright. | the SSL-only flag, or reject requests outright. | ||||
To fix this, you can set `$_SERVER['HTTPS']` explicitly: | To fix this, you can set `$_SERVER['HTTPS']` explicitly: | ||||
``` | ``` | ||||
name=Explicitly Configure SSL Availability | name=Explicitly Configure SSL Availability | ||||
<?php | <?php | ||||
$_SERVER['HTTPS'] = true; | $_SERVER['HTTPS'] = true; | ||||
``` | ``` | ||||
You can also set this value to `false` to explicitly tell Phabricator that a | You can also set this value to `false` to explicitly tell Phorge that a | ||||
request is not an SSL request. | request is not an SSL request. | ||||
Next Steps | Next Steps | ||||
========== | ========== | ||||
Continue by: | Continue by: | ||||
- returning to the @{article:Configuration Guide}. | - returning to the @{article:Configuration Guide}. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0