@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Configuring a Preamble Script
2@group config
3
4Adjust environmental settings (SSL, remote IPs) using a preamble script.
5
6Overview
7========
8
9If Phorge 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
11some environmental features (like the client's IP, or the presence of SSL)
12correctly.
13
14You can use a special preamble script to make arbitrary adjustments to the
15environment and some parts of Phorge's configuration in order to fix these
16problems and set up the environment which Phorge expects.
17
18
19Creating a Preamble Script
20==========================
21
22To create a preamble script, write a file to:
23
24 phorge/support/preamble.php
25
26(This file is in Phorge's `.gitignore`, so you do not need to worry about
27colliding with `git` or interacting with updates.)
28
29This file should be a valid PHP script. If you aren't very familiar with PHP,
30you can check for syntax errors with `php -l`:
31
32 phorge/ $ php -l support/preamble.php
33 No syntax errors detected in support/preamble.php
34
35If present, this script will be executed at the very beginning of each web
36request, allowing you to adjust the environment. For common adjustments and
37examples, see the next sections.
38
39
40Adjusting Client IPs
41====================
42
43If your install is behind a load balancer, Phorge may incorrectly detect
44all requests as originating from the load balancer, rather than from the
45correct client IPs.
46
47In common cases where networks are configured like this, the `X-Forwarded-For`
48header will have trustworthy information about the real client IP. You
49can use the function `preamble_trust_x_forwarded_for_header()` in your
50preamble to tell Phorge that you expect to receive requests from a
51load balancer or proxy which modifies this header:
52
53```name="Trust X-Forwarded-For Header", lang=php
54preamble_trust_x_forwarded_for_header();
55```
56
57You should do this //only// if the `X-Forwarded-For` header is known to be
58trustworthy. In particular, if users can make requests to the web server
59directly, they can provide an arbitrary `X-Forwarded-For` header, and thereby
60spoof an arbitrary client IP.
61
62The `X-Forwarded-For` header may also contain a list of addresses if a request
63has been forwarded through multiple load balancers. If you know that requests
64on your network are routed through `N` trustworthy devices, you can specify
65that `N` to tell the function how many layers of `X-Forwarded-For` to discard:
66
67```name="Trust X-Forwarded-For Header, Multiple Layers", lang=php
68preamble_trust_x_forwarded_for_header(3);
69```
70
71If you have an unusual network configuration (for example, the number of
72trustworthy devices depends on the network path) you can also implement your
73own logic.
74
75Note that this is very odd, advanced, and easy to get wrong. If you get it
76wrong, users will most likely be able to spoof any client address.
77
78```name="Custom X-Forwarded-For Handling", lang=php
79
80if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
81 $raw_header = $_SERVER['X_FORWARDED_FOR'];
82
83 $real_address = your_custom_parsing_function($raw_header);
84
85 $_SERVER['REMOTE_ADDR'] = $real_address;
86}
87```
88
89Adjusting SSL
90=============
91
92If your install is behind an SSL terminating load balancer, Phorge may
93detect requests as HTTP when the client sees them as HTTPS. This can cause
94Phorge to generate links with the wrong protocol, issue cookies without
95the SSL-only flag, or reject requests outright.
96
97To fix this, you can set `$_SERVER['HTTPS']` explicitly:
98
99```
100name=Explicitly Configure SSL Availability
101<?php
102
103$_SERVER['HTTPS'] = true;
104```
105
106You can also set this value to `false` to explicitly tell Phorge that a
107request is not an SSL request.
108
109
110Next Steps
111==========
112
113Continue by:
114
115 - returning to the @{article:Configuration Guide}.