Origin & Edge Configuration

Settings for origins and how the service communicates with them – the address of the origin servers, if GNA is or isn't used, SSL settings, network settings, etc. – are contained in origin blocks.

Likewise, settings for the Instart proxy servers – cache rules, SSL settings, etc. – are contained in edge blocks.

Origin configuration

The origin block specifies configuration for a origin. Here's a typical example:

"origin" : {
   "host" : "192.33.29.22",
   "network" : {
      "keepalive" : true,
      "keepalive_timeout_secs" : 600,
      "first_byte_response_timeout_secs" : 300,
      "request_timeout_secs" : 120,
      "response_timeout_secs" : 300
   },
   "failure_handling" : {
      "max_retry_attempts" : 3
    }
}

The following fields and blocks can be present in the origin block:

FieldDescription
hostOrigin server hostname. Valid values are
  • FQDN of the origin
  • IP of the origin
  • Host header value specified in the end user request
host_headerOrigin request host header. Valid values are
  • EDGE_DOMAIN: the host header value specified in the end user request
  • ORIGIN_DOMAIN: fully-qualified domain name of the origin
  • CUSTOM: a custom value in specified in the field custom_host_header

The default is EDGE_DOMAIN.

custom_host_headerString for the origin host header when host_header is set to CUSTOM.
http_port or https_port

Port number of the origin. This number is an integer in the range 0 to 65535.
The defaults are 80 for http_port, 443 for https_port

IMPORTANT: Instart needs to perform a security review for any request to use custom port numbers for your origin configuration. Please contact support if you would like to enable this feature.

first_mile_protocolProtocol to use when communicating with the origin server. This can be either HTTP or HTTPS.
set_forwarded_for

Boolean flag to control injection of a X-Forwarded-For header with the value of the Nginx variable $proxy_add_x_forwarded_for. This is shorthand for adding the header in the request_headers field

The default value is true.

forwarded_for_headers

a list of header names to use instead of X-Forwarded-For headers. For example:

"forwarded_for_headers" : ["True-Client-IP", "Host"]

will send two headers, True-Client-IP and Host, with values $proxy_add_x_forwarded_for. This does NOT take effect if set_forwarded_for is set to false.

Another example:

"forwarded_for_headers" :  ["True-Client-IP", "X-Forwarded-For"]

will add True-Client-IP and X-Forwarded-For headers.

set_true_client_ip

Boolean value to control injection of a True-Client-IP header with the value of the $client_ip Nginx variable, which is the value of the first address in the X-Forwarded-For value if present, or, if this is the first proxy and X-Forwarded-For is not present, the $remote_addr Nginx variable. This is shorthand for adding the header in the request_headers field as described below.

See the section on "Controlling headers sent to the origin" below.

The default value is false.

overwrite_true_client_ip_headers

When set to true, any headers configured to hold the true client IP will be overwritten in the request if they are already present. Normally we want to pass those headers upstream.

As an example, to set the true client IP value in the X-Forwarded-For header:

"overwrite_true_client_ip_headers" : true,
"set_true_client_ip" : true,
"true_client_ip_headers" : ["X-Forwarded-For"]

The default value is false.

lowercase_request_headers

Boolean flag to enable whether request headers are lowercased before being sent upstream. To lowercase all the headers (except Host and Connection) before they are sent upstream has been the default behavior. This behavior is RFC-valid since headers are not case-sensitive; however, some origins want the case to be maintained – for example, X-Forwarded-For.

The default value is true

true_client_ip_headers

List of header names to use in the True-Client-IP headers. See the section on "Controlling headers sent to the origin" below.

For example:

"true_client_ip_headers" : ["X-True-Client-IP"]

will send one header, X-True-Client-IP, with the value of the $client_ip Nginx variable. This does NOT take effect if set_true_client_ip is set to false.

request_headers_to_origin

This block is used to add, set, or remove any upstream request headers that you want.

See the section on "Controlling headers sent to the origin" below.

response_headers_from_origin

This block is used to add, set or remove any upstream response headers that you want. These headers are treated as if they are from the origin (so they are cached, for example).

See the section on "Controlling headers sent to the origin" below.

The origin block can contain the following blocks:

gna

This block configures the Global Network Accelerator (GNA) for the origin server. The Global Network Accelerator improves performance for dynamic data by using a new purpose-built binary protocol, called IPTP, invented specifically for inter-proxy transmissions to overcome the inefficiencies of TCP, HTTP, and HTTPS over global distances.

The fields that can be used in a gna block are:

FieldDescription
enabledBoolean value to specify whether GNA is enabled
gna_hostGNA host name. Valid values are
  • FQDN of the GNA node
  • IP of the GNA node
gna_cache

Boolean value to specify whether to perform cache lookup/store at the GNA host or not.

The default is false.

secure_middle_mile

Boolean value to specify whether communication over the middle mile be secure.

The default is true.

ssl

This block configures SSL for the origin server.

The fields that can be used in a ssl block are:

FieldDescription
protocol

SSL protocols configuration. Protocol selection starts with more secure TLS (TLSv1.2, then TLSv1.1, then TLSv1) and then uses SSLv3, if enabled.

check_cert

If set to true, the service will check that the certificate of the upstream server is signed by a trusted CA. This does not validate the DN of the host.

The default is true.

check_cert_name

If set to true, validate that the certificate commonName or subjectAlternateName matches the hostname given by the host configuration block.

The default is true.

allow_wildcard_cert

If set to true, allow for SSL wildcard certificate from the upstream server.

The default is true.

whitelisted_cert_cn

A list of other FQDN or IP addresses that we allow for certificate verification in addition to host.

By default this list is empty if you do not need to override matching for host.

use_legacy_first_mile_ssl

Use legacy SSL stack for upstream communication. This will be removed when the new SSL code replaces the old code completely.

The default value is false.

ssl_ciphers

Specifies the ciphers enabled on the first mile. The ciphers are specified in the format understood by the OpenSSL library, for example:

- ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

The full list can be viewed using the the openssl ciphers command.

The default is "" and implies using the default specified by the OpenSSL library.

use_sni

If true, use SNI for establishing upstream SSL connections. Some origin servers don't like SNI in the SSL handshake; this should be set to false for such origins.

The default value is true.

network

This block configures the network configuration when communicating with the origin server.

The fields that can be used in a network block are:

FieldDescription
keepalive

Boolean flag specifying if keepalive to the origin server is enabled.

The default is true.

keepalive_timeout_secs

Timeout period for persistent connections, in seconds. This can be an integer in the range from 1 to 1500.

The default is 300.

connect_timeout_secs

Timeout period within which connection with the origin is expected to be successfully established, in seconds. For HTTPS connections, the SSL handshake time is also included within this timeout period. This can be an integer in the range from 1 to 300.

The default is 30.

first_byte_response_timeout_secs

Timeout period within which the first byte of the response is expected to be received, in seconds. if we do not get the response first byte within this time, we'll mark this connection as bad, close it, and retry. The retry itself is based on the configuration parameter max_retry_attempts in the failure_handling block. This can be an integer in the range from 1 to 9000.

The default is 30.

inter_response_timeout_secs

Timeout period within which the Origin Fetch service is expected to receive the next response chunk from the origin, in seconds. (The Origin Fetch service makes necessary requests to the origin – for content that has not yet been cached, or has expired, and for dynamic content.) This field helps to close requests in case an origin server sends a few response chunks fast and is very slow in sending the next ones. This can be an integer in the range from 1 to 600.

The default is 30.

inter_request_timeout_secs

Timeout period within which a request chunk is expected to be sent to lower layers by the Origin Fetch service, in seconds. A request can be split over multiple chunks depending on its size and/or whether lower layers are ready to receive data or not. Within this timeout, a request chunk must be sent to lower layers. Note that it doesn't mean that within this timeout request is received by origin server; also this is NOT the time within which the complete request will be sent by the Origin Fetch service.This timeout is NOT an end-to-end timeout. The downstream has no role to play in this timeout. This timeout is applicable only when the proxy has full data, but it is not able to send it to lower layers. This can be an integer in the range from 1 to 300.

The default is 10.

monitoring

This block configures monitoring of the different paths from the service proxies to the origin. We pull a small object on a frequent basis from the origin to make sure the various paths through the Internet are clear. This allows the service to fail proactively around bad paths.

The fields that can be used in a monitoring block are:

FieldDescription
enabledBoolean flag specifying if monitoring enabled for this origin. The default is set by the proxy configuration and therefore might need to be enabled for an origin manually in the property configuration.
iptp_ping_interval_secs

Time between two RPC ping probes between a proxy and a GNA node, in seconds. This can be an integer in the range from 1 to 30.

The default is 1.

iptp_ping_timeout_secs

Timeout period after which an RPC ping between a proxy and a GNA node is said to have failed. This can be an integer in the range from 1 to 30.

The default is 1.

origin_ping_interval_secs

Time between two HTTP(S) ping probes between a GNA node and an origin server. This can be an integer in the range from 1 to 30.

The default is 1.

origin_ping_timeout_secs

Timeout period after which an HTTP(S) ping between a GNA node and an origin server is said to have failed. This can be an integer in the range from 0 to 30.

The default is 1.

min_successful_pings_for_healthy

The minimum consecutive number of pings that should succeed before we mark a node as healthy. This can be an integer in the range from 0 to 10.

The default is 0.

min_failed_pings_for_unhealthy

The minimum consecutive number of pings that should fail before we mark an endpoint as unhealthy. A value of 0 implies that the first failed ping will cause the endpoint to be marked as down.

The default value is 0.

origin_ping_method

DEPRECATED. The request method to use for the HTTP health check.

The default is GET (kMethodGet)

origin_ping_pathDEPRECATED. The path to the request origin for the HTTP health check. If the path is empty, then origin monitoring is disabled. You must specify a path to monitor for the origin monitoring to be enabled.
origin_ping_http_statusList of valid HTTP statuses to expect for the response to an HTTP ping. For example, setting it to [200, 404] means that any response other than 200 or 404 will be considered to be a failure. If the field is not set then all valid HTTP responses are considered to be successful.
probe_requestThe probe request to send to the origin. This has to be set for the origin failover feature to work.

failure_handling

This block configures failover handling for the origin server.

The fields that can be used in a failure_handling block are:

FieldDescription
failover_hostThe failover origin host. Valid values are
  • FQDN of the origin
  • IP of the origin
  • Host header value specified in the end user request
failover_status_codesA list of response status codes for which failover origin server will be contacted by the proxy. A failover status code value 0 is translated to 000 when comparing the origin response status with the failover status codes.
failover_host_headerAn optional host header value for requests to the failover origin. If left empty, we reuse the origin request host header. Valid values are:
  • EDGE-DOMAIN: Set the upstream host header to the edge domain. This is the host header value specified in the end user request.
  • ORIGIN_DOMAIN: set the upstream host header to the origin domain
  • CUSTOM: a custom header specified in the field failover_custom_host_header

The default value is EDGE_DOMAIN.

failover_custom_host_headerThe failover origin host header if failover_host_header is set to CUSTOM.
max_retry_attempts

If there is a connection failure or a read timeout when trying to connect to the upstream, the proxy can retry the connection. This field sets the maximum number of retry attempts that will be made. The retry is done only if there was no data from the upstream  and the request is idempotent. This is useful for load balancers, which sometimes just don't respond after a successful connection has been established. This can be an integer in the range from 0 to 6.

The default is 0.

max_retry_attempts_http

If there is a connection failure or a read timeout when trying to connect to the upstream and there are HTTP-level failures, such as a parsing error or HTTP failover status codes specified above, the proxy can retry the connection. This allows us to retry the primary origin some number of times if we receive a specific HTTP code from the origin host, before we fail over to the failover host. This can be an integer in the range from 0 to 6.

The default is 0.

Here are some typical examples of a failure_handling block:

"failure_handling" : {
   "failover_host" : "failorigin-www.hsimpson.com",
   "failover_status_codes" : [500,503,504],
   "failover_host_header" : "ORIGIN_DOMAIN"
}
"failure_handling" : {
   "failover_host" : "failorigin-www.hsimpson.com",
   "failover_status_codes" : [503],
   "failover_host_header" : "CUSTOM",
   "failover_custom_host_header" : "origin-failover-custom-host-header"
 }

request_headers_to_origin

This block is used to add, set or remove upstream request headers. This is used as an extra knob to control the headers sent upstream.

The fields that can be used in a request_headers_to_origin block are:

FieldDescription
operation

Specifies what do do with a header. Valid values are:

  • SET: add a new header if it doesn't exist, or replace it if it does
  • APPEND: add a new header if it doesn't exist, or add the value to the list values present if the header exists
  • DELETE: if present, remove this header from the response
nameThe name of the header to operate on
value

The value for this header

Here's a typical use of request_headers_to_origin:

"request_headers_to_origin" :
   [
      {
         "operation" : "SET",
         "name" : "Origin",
         "value" : "http://www.tomboinsevenfour.net"
      }
   ]

In this example a header named Origin with the value http://www.tomboinsevenfour.net is added to the request header sent to the customer origin.

Controlling request headers sent to the origin

There are a number of ways we can configure what the request headers we send on to the origin. There are two shorthand methods for the most common use cases – the X-Forwarded-For and True-Client-IP headers – and a general method by which we can add or append to any additional headers we might desire, and also delete any we want to discard from the request.

Shorthand methods for configuring X-Forwarded-For and True-Client-IP headers

The shorthand method for setting X-Forwarded-For headers has been present for a while; a parallel method for setting True-Client-IP headers has recently been added. See the description of these fields in the table above.

When a HTTP request is relayed by proxy servers and load balancers, the origin web server cannot obtain the IP address of the originating client by reading the remote address, since that will be the IP address of the last proxy in the chain. The industry de-facto standard X-Forwarded-For request header is often injected by proxy servers and load balancers to convey this information, allowing the web server to perform IP address-based services such as geolocation or filtering.

The first proxy to handle the request reads the remote address and copies it into an X-Forwarded-For. The next proxy will read the remote address of the request, which will now be the IP of the first proxy, and appends it to the X-Forwarded-For it received before sending it on. Consider a case with 2 proxies between the client browser and the origin:

In this example the X-Forwarded-For header received by the origin might look like so:

X-Forwarded-For: 128.122.104.151, unknown, 192.41.101.55

Entries are always IP addresses, or the word unknown if the address could not be determined or if it has been disabled. The first IP address in the chain should normally be the actual IP address of the originating client. But access controls based on this header are extremely weak and simple to fake. Any intermediary in the chain can replace this header. This is perhaps the reason why client IP addresses were omitted from the HTTP specification.

In some of our configs you will find this:

"forwarded_for_headers" :  ["True-Client-IP", "X-Forwarded-For"],

The result of this is that a header named True-Client-IP is inserted into the request to the origin. But this header will not contain the IP address of the client as its name suggests, it will simply be a copy of the X-Forwarded-For header.

To set a True-Client-IP header that has just the originating client's address, do this:

"set_true_client_ip" : true,
"true_client_ip_headers" : ["True-Client-IP"],

Or, to set an X-Forwarded-For header that contains just the originating client IP, you can do this:

"overwrite_true_client_ip_headers" : true,
"set_true_client_ip" : true,
"true_client_ip_headers" : ["X-Forwarded-For"],

General methods for configuring headers — the request_headers_to_origin block

This block is used to add, set, or remove any upstream request headers that you want. This allows complete control over the headers we send to the origin.

The fields are:

FieldDescription
operationSpecifies what to do with a header. Valid values are:
  • SET: add a new header if it doesn't exist, or replace it if it does
  • APPEND: add a new header if it doesn't exist, or add the value to the list values present if the header exists
  • DELETE: if present, remove this header from the response
nameThe name of the header to operate on
valueThe value for this header

For example, to set the True-Client-IP header, you could do it this way:

"origin" : {
  ...
  "request_headers_to_origin" : [
    {
      "operation" : "SET",
      "name" : "True-Client-IP",
      "value" : "$remote_addr"
    }
  ]
  ...
}

This used to be the proper way to set this header as opposed to adding another copy of the X-Forwarded-For header with the name True-Client-IP, as has sometimes mistakenly been done in configs. The shorthand method described above is more compact.

Another example: this block deletes a header named X-Instart-Via from the list of headers to be sent to the origin:

"origin" : {
  ...
  "request_headers_to_origin" : [
    {
      "operation" : "DELETE",
      "name" : "X-Instart-Via"
    }
  ]
  ...
}

Edge configuration

The edge block specifies configuration for a Instart proxy. Here's a typical example:

"edge" : {
   "cloud_cache" : {
      "policy" : "FIXED_TTL",
      "ttl" : "24h",
      "cache_key" : {
         "drop_protocol" : true
      }
   }
}
The edge block can contain the following blocks:

client_cache

This block contains the configuration for the downstream client's cache. 

The fields for a client_cache block are described in the Caching Configuration document.

cloud_cache

This block contains the configuration for edge's cloud cache

The fields for a cloud_cache block are described in the Caching Configuration document.

ssl

This block contains the SSL configuration for the downstream client's SSL connection with our proxy. The fields are:

FieldDescription
enabledA boolean flag specifying that SSL is enabled or not.
sni_certA certificate reference identifying the certificate to use for SNI requests.
non_sni_certsA list of certificates to serve non-SNI requests.
sni_ssl_ciphers

Specifies the ciphers enabled for SNI. The ciphers are specified in the format understood by the OpenSSL library, for example:

- ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

The full list can be viewed using the the openssl ciphers command.

The default is "" and implies using the default specified by the OpenSSL library.

spdyAn optional block specifying configuration for the SPDY protocol. Can be enabled only if SSL is configured.
request_headers_from_client

Used to add, set or remove request headers from the requesting client.

response_headers_to_clientUsed to add, set or remove downstream headers. However, this should be used to do tweaking of responses in production only if it is very customer-specific. Most of the general configuration should be available in the corresponding sections. For example, to set cache-control end-user TTL, cache-config parameters should be used.
response_cookies_to_clientUsed to add or remove downstream cookies. Creates Set-Cookie header(s) in the response to the client. These modifications are applied after any changes made by response_headers_to_client.

The fields for the optional spdy block can be:

FieldDescription
chunk_size

The maximum size of chunks into which the response body is sliced, in KB. Any non-zero value can be specified. Note: internally "k" is appended to the value specified. For example,

"chunk_size" : 5

will be translated to

"spdy_chunk_size": "5k"

for Nginx's consumption.

headers_compression_levelThe compression level of a response in the range from 1 (fastest, least compressed) to 9 (slowest, most compressed). 0 means compression is disabled.

The fields for the optional response_headers_to_client block can be:

FieldDescription
operationSpecifies what to do with a header. Valid values are:
  • SET: add a new header if it doesn't exist, or replace it if it does
  • APPEND: add a new header if it doesn't exist, or add the value to the list values present if the header exists
  • DELETE: if present, remove this header from the response
nameThe name of the header to operate on
valueThe value for this header

Here's a typical use of response_headers_to_client:

"response_headers_to_client" :
   [
      {
         "operation" : "SET",
         "name" : "Cache-Control",
         "value" : "max-age=604800"
      }
   ]

This block will add a cache-control header with the value max-age=604800 to the response. If the header already exists in the response from the origin, this header will overwrite the original and replace it. If the operation had instead been APPEND, the value will be appended to the existing list of values.