[Summary view] [Print] [Text view]

   1  @title Configuring a Preamble Script
   2  @group config
   3  
   4  Adjust environmental settings (SSL, remote IP, rate limiting) using a preamble
   5  script.
   6  
   7  = Overview =
   8  
   9  If Phabricator is deployed in an environment where HTTP headers behave oddly
  10  (usually, because it is behind a load balancer), it may not be able to detect
  11  some environmental features (like the client's IP, or the presence of SSL)
  12  correctly.
  13  
  14  You can use a special preamble script to make arbitrary adjustments to the
  15  environment and some parts of Phabricator's configuration in order to fix these
  16  problems and set up the environment which Phabricator expects.
  17  
  18  NOTE: This is an advanced feature. Most installs should not need to configure
  19  a preamble script.
  20  
  21  = Creating a Preamble Script =
  22  
  23  To create a preamble script, write a file to:
  24  
  25    phabricator/support/preamble.php
  26  
  27  (This file is in Phabricator's `.gitignore`, so you do not need to worry about
  28  colliding with `git` or interacting with updates.)
  29  
  30  This file should be a valid PHP script. If you aren't very familiar with PHP,
  31  you can check for syntax errors with `php -l`:
  32  
  33    phabricator/ $ php -l support/preamble.php
  34    No syntax errors detected in support/preamble.php
  35  
  36  If present, this script will be executed at the very beginning of each web
  37  request, allowing you to adjust the environment. For common adjustments and
  38  examples, see the next sections.
  39  
  40  = Adjusting Client IPs =
  41  
  42  If your install is behind a load balancer, Phabricator may incorrectly detect
  43  all requests as originating from the load balancer, rather than from the correct
  44  client IPs. If this is the case and some other header (like `X-Forwarded-For`)
  45  is known to be trustworthy, you can overwrite the `REMOTE_ADDR` setting so
  46  Phabricator can figure out the client IP correctly:
  47  
  48  ```
  49  name=Overwrite REMOTE_ADDR with X-Forwarded-For
  50  <?php
  51  
  52  $_SERVER['REMOTE_ADDR'] = $_SERVER['HTTP_X_FORWARDED_FOR'];
  53  ```
  54  
  55  You should do this //only// if the `X-Forwarded-For` header is always
  56  trustworthy. In particular, if users can make requests to the web server
  57  directly, they can provide an arbitrary `X-Forwarded-For` header, and thereby
  58  spoof an arbitrary client IP.
  59  
  60  = Adjusting SSL =
  61  
  62  If your install is behind an SSL terminating load balancer, Phabricator may
  63  detect requests as HTTP when the client sees them as HTTPS. This can cause
  64  Phabricator to generate links with the wrong protocol, issue cookies without
  65  the SSL-only flag, or reject requests outright.
  66  
  67  To fix this, you can set `$_SERVER['HTTPS']` explicitly:
  68  
  69  ```
  70  name=Explicitly Configure SSL Availability
  71  <?php
  72  
  73  $_SERVER['HTTPS'] = true;
  74  ```
  75  
  76  You can also set this value to `false` to explicitly tell Phabricator that a
  77  request is not an SSL request.
  78  
  79  = Adjusting Rate Limiting =
  80  
  81  Phabricator performs coarse, IP-based rate limiting by default. In most
  82  situations the default settings should be reasonable: they are set fairly high,
  83  and intended to prevent only significantly abusive behavior.
  84  
  85  However, if legitimate traffic is being rate limited (or you want to make the
  86  limits more strict) you can adjust the limits in the preamble script.
  87  
  88  ```
  89  name=Adjust Rate Limiting Behavior
  90  <?php
  91  
  92  // The default is 1000, so a value of 2000 increases the limit by a factor
  93  // of 2: users will be able to make twice as many requests before being
  94  // rate limited.
  95  
  96  // You can set the limit to 0 to disable rate limiting.
  97  
  98  PhabricatorStartup::setMaximumRate(2000);
  99  ```
 100  
 101  By examining `$_SERVER['REMOTE_ADDR']` or similar parameters, you could also
 102  adjust the rate limit dynamically: for example, remove it for requests from an
 103  internal network, but impose a strict limit for external requests.
 104  
 105  Rate limiting needs to be configured in this way in order to make it as cheap as
 106  possible to activate after a client is rate limited. The limiting checks execute
 107  before any libraries or configuration are loaded, and can emit a response within
 108  a few milliseconds.
 109  
 110  = Next Steps =
 111  
 112  Continue by:
 113  
 114    - returning to the @{article:Configuration Guide}.