configuring_preamble.diviner
No OneTemporary
Actions

Size

3 KB

Referenced Files

None

Subscribers

None

configuring_preamble.diviner
View Options

	@title Configuring a Preamble Script
	@group config

	Adjust environmental settings (SSL, remote IPs) using a preamble script.

	Overview
	========

	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
	some environmental features (like the client's IP, or the presence of SSL)
	correctly.

	You can use a special preamble script to make arbitrary adjustments to the
	environment and some parts of Phorge's configuration in order to fix these
	problems and set up the environment which Phorge expects.


	Creating a Preamble Script
	==========================

	To create a preamble script, write a file to:

	phorge/support/preamble.php

	(This file is in Phorge's `.gitignore`, so you do not need to worry about
	colliding with `git` or interacting with updates.)

	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`:

	phorge/ $ php -l 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
	request, allowing you to adjust the environment. For common adjustments and
	examples, see the next sections.


	Adjusting Client IPs
	====================

	If your install is behind a load balancer, Phorge may incorrectly detect
	all requests as originating from the load balancer, rather than from the
	correct client IPs.

	In common cases where networks are configured like this, the `X-Forwarded-For`
	header will have trustworthy information about the real client IP. You
	can use the function `preamble_trust_x_forwarded_for_header()` in your
	preamble to tell Phorge 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
	trustworthy. In particular, if users can make requests to the web server
	directly, they can provide an arbitrary `X-Forwarded-For` header, and thereby
	spoof an arbitrary client IP.

	The `X-Forwarded-For` header may also contain a list of addresses if a request
	has been forwarded through multiple load balancers. If you know that requests
	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);
	```

	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.

	Note that this is very odd, advanced, and easy to get wrong. If you get it
	wrong, users will most likely be able to spoof any client address.

	```name="Custom X-Forwarded-For Handling", lang=php

	if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
	$raw_header = $_SERVER['X_FORWARDED_FOR'];

	$real_address = your_custom_parsing_function($raw_header);

	$_SERVER['REMOTE_ADDR'] = $real_address;
	}
	```

	Adjusting SSL
	=============

	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
	Phorge to generate links with the wrong protocol, issue cookies without
	the SSL-only flag, or reject requests outright.

	To fix this, you can set `$_SERVER['HTTPS']` explicitly:

	```
	name=Explicitly Configure SSL Availability
	<?php

	$_SERVER['HTTPS'] = true;
	```

	You can also set this value to `false` to explicitly tell Phorge that a
	request is not an SSL request.


	Next Steps
	==========

	Continue by:

	- returning to the @{article:Configuration Guide}.

File Metadata

Mime Type: text/plain
Expires: Thu, Feb 6, 10:54 AM (1 d, 6 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 34005
Default Alt Text: configuring_preamble.diviner (3 KB)

configuring_preamble.divinerNo OneTemporaryActions

configuring_preamble.divinerView Options

File Metadata

Event Timeline

configuring_preamble.diviner
No OneTemporary
Actions

configuring_preamble.diviner
View Options