Configuration JSON Overview
A brief overview of the configuration JSON and its components
Configuration of ESB3024 Router is done by PUT:ing a JSON object to a REST API
located at https://<router-host>:5001/v2/configuration by default.
This document will go through the JSON object, briefly describe its fields and link to more in-depth documentation where appropriate. For information on the JSON language syntax, please refer to the official JSON documentation.
Top-level fields
Here we’ll go through all the fields that may exist at the first level of the JSON object. In the following sections we’ll explore some of them in more detail while some others are complex enough to warrant their own pages.
"cdns"(array, objects)
A list of all CDNs associated with this router, described further down."content_server"(object)
Parameters for the content HTTP interface, described further down."custom_lua"(string)
Container-specific path to the parent folder under which the/v1/lua/<path str>.luaPUTendpoint will cache the uploaded Lua script files with relative paths as specified by the<path str>.luaargument. Uploaded Lua scripts are then loaded into the Lua environment available in request/response translation functions as well as routing weight functions. The/v1/lua/<path str>.luaPUTendpoint will attempt to create the folder and any required subdirectories on the specified path, should they not exist. Full read-write access for the router need to be maintained to the parent folder, so that the configured folder can be created by the router, to the configured folder itself, its children and every contained.luascript."hosts"(array, objects)
A list of all hosts available in the CDNs listed above, described further down."id"(string)
Always"ACD", read only."image_tag"(string)
A string unique to the version of software installed, read only."managed_sessions"(object)
Settings for how to configure managed sessions, described further down."metadata"(object)
Contains metadata about the configuration, described further down."request_translation_function"(string)
A Lua function body for changing incoming HTTP requests, described further down."response_translation_function"(string)
A Lua function body for changing outgoing HTTP responses, described further down."rest_api_server"(object)
Settings for the API endpoint used for e.g. PUT:ing the configuration, described further down."routing"(object)
Client routing rules, described further down."session_groups"(array, objects)
Classification rules for incoming requests, described further down."settings"(object)
Settings for functionality that can be enabled or disabled, described further down."standard_lua"(string)
Container-specific path to a folder containing pre-installed Lua script files that are loaded into the Lua environment available in request/response translation functions as well as routing weight functions."tuning"(object)
Adjustments of timings, log level, thresholds etc, described further down."version"(string)
Always"v2", read only.
"cdns"
A list containing CDN definitions. Each object contains the following data:
"disabled_hosts"(array, strings)
Hostnames temporarily taken out of routing, e.g. due to maintenance or because they are known to be broken. For redirecting CDNs, these hosts are added to anExclude-Hostheader telling the CDN not to use them."http_port"(integer)
The HTTP port the hosts in the CDN listen to."https_port"(integer)
The HTTPS port the hosts in the CDN listen to."id"(string, unique)
Unique internal name used to reference the CDN within the router."manifest_availability_check"(object)
Specifies if a CDN should be checked for manifest availability, and if so for which session groups."enabled"(boolean)
Toggle availability check."session_group_ids"(array, integers)
List of the session groups for which to perform check.
"redirecting"(boolean)
Setting to true makes the router request a redirect URL from the CDN to forward to the client, otherwise the router constructs its own redirect response with the selected host in theLocationheader."response_code_rules"(array, objects)
List of response actions per matching response code from redirecting CDN. Each object contains the following data:"pattern"(string)
Sequence of digits and / or wildcards in the form of the letter x. Example:"4xx"which matches response codes 400-499."action"(string)
Specifies which action to take when the response code from a redirecting CDN matches the pattern. Valid values are"default", which lets the router proceedas-ifno pattern was matching,"continue", to proceed with selecting the next host in the CDN,"redirect"to let the router redirect the request to the URL returned by the redirecting CDN, and"proxy"which returns the response from the redirecting CDN back to the clientas-ifthe response originated from the router itself."new_response_code"(integer)
The overridden response code to send back to the client irrespective of"action". It replaces the response code in the otherwise verbatim response for a selected"proxy"action.
"timeout_action"(string)
Specifies which action to take when the request to the redirecting CDN times out without detecting a response. Valid values are"abort"which stops selection, and"continue"which continues with selecting the next host in the CDN.
"content_server"
Settings for the routing interface that clients request content through.
"http_enable"(boolean)
Toggles if HTTP interface is available or not."http_port"(integer)
Which port the HTTP interface should listen on."https_enable"(boolean)
Toggles if encrypted HTTPS interface is available or not."https_port"(integer)
Which port the HTTPS interface should listen on.
"hosts"
A list containing CDN host definitions. Each object contains the following data:
"cdn_id"(string)
A reference to a CDN in thecdnsarray."host"(string)
The IP or hostname for the host."ipv6_address"(string)
If the client connects via IPv6 or has put an IPv6 address in theX-Forwarded-Forheader, then the router will connect to the CDN using the address fromipv6_address. Ifipv6_addressis not given, the connection will be made using the address fromhost."id"(string)
A unique identifier used in the routing rule tree."proxy_url"(string)
When using EDNS routing, the incoming request is sent to a proxy server located atproxy_urlthat creates and sends an EDNS request based on the client’s HTTP request. A default installation of ESB3024 includes an EDNS proxy located athttp://localhost:8888.
"managed_sessions"
Settings for managed client sessions.
"fraction"(number)
The fraction of sessions to be managed, between 0.0 and 1.0."max_active"(integer)
The maximum number of active managed sessions."session_types"(array, objects)
A list of the various types of managed sessions and their respective settings. Each object contains the following data:"enabled"(boolean)
description: Toggle this session type."max_active"(integer)
The maximum number of active sessions belonging to this session type."session_group_ids"(array, integers)
The session groups allowed to belong to this session type, or empty if any."type"(string)
The type of managed session. The only valid value is"instream".
"metadata"
Metadata mostly generated from the configuration.
"etag"(string)
The MD5 hash of the configuration’s size in memory."extra_info"(object)
This field can store any arbitrary key-value pairs, e.g. to tag or name a configuration. The only configurable field in"metadata"."source_ip"(string)
The IP address from which the configuration was sent."timestamp"(string)
The ISO-8601 formatted timestamp of when the configuration was applied.
"request_translation_function"
The content of this field is a Lua function body that can be used to modify an incoming request before passing it on to be classified and routed. See Lua Hooks for details.
"response_translation_function"
The content of this field is a Lua function body that can be used to modify an outgoing response before it is sent back to the requesting client. See Lua Hooks for details.
"rest_api_server"
Settings for the configuration REST endpoint itself.
"enable"(boolean)
Determines whether the REST API is turned on or not."port"(integer)
HTTPS port to listen to.
"routing"
A tree structure of objects setting up a routing algorithm. See Routing Engine for more details.
"session_groups"
A list containing session group definitions. See Session Groups and Classification for details.
"settings"
Various behavioral settings related to content requests and CDN requirements.
"reversed_filename_comparison"(object)
Compares segment filenames from the end when trying to match requests with content. This allows the router to be compatible with CDNs that put e.g. a timestamp first in the filename."enabled"(boolean)
Toggle Akamai support on or off.
"allowed_clients"(array, strings)
If non-empty, this array contains all IP:s proxies that are allowed to use the X-Forwarded-For HTTP header."dash_manifest_rewrite"(object)
Rewrite DASH manifests to use absolute URLs for clients that don’t support HTTP redirect properly."enabled"(boolean)
Enable or disable DASH manifest rewrite."session_group_ids"(array, integers)
A list of session groups for which to perform manifest rewrite so it only has to be done for e.g. a set of user agents known to be faulty."extended_content_identifier"(object)
Sets a list of query parameters that may be used to identify a specific content along with the path, used for caching."enabled"(boolean)
Turns on or off query parameter content identifiers."included_query_params"(array, strings)
The list of query parameter names to allow.
"hls_manifest_rewrite"(object)
Rewrite HLS manifests to use absolute URLs for clients that don’t support HTTP redirect properly."enabled"(boolean)
Enable or disable DASH manifest rewrite."session_group_ids"(array, integers)
A list of session groups for which to perform manifest rewrite so it only has to be done for e.g. a set of user agents known to be faulty.
"usage_log"(object)
Usage logging settings. By default, usage logs such as the number of redirected requests handled during a time period are written to."/opt/edgeware/acd/router/log/usage.log"unless the environment variableUSAGE_LOGGING_DIRhas been set to something else."enabled"(boolean)
Enables usage logging."log_interval"(integer)
Number of milliseconds between each usage log write.
"tuning"
Settings for tuning the behavior of the router.
"access_log"(boolean)
Enable or disable access logging."content_cache_size_full_manifests"(integer)
Size of cache for storing full manifests and associated metadata, in number of manifests."content_cache_size_light_manifests"(integer)
Size of cache for storing simplified manifest metadata, in number of manifests."content_light_cache_time_milliseconds"(integer)
Number of milliseconds before a light manifest content expires."content_live_cache_time_milliseconds"(integer)
Number of milliseconds before a full manifest live content expires."content_vod_cache_time_milliseconds"(integer)
Number of milliseconds before a full manifest VOD content expires."cout_flush_rate_milliseconds"(integer)
How often to flush logs to stdout even if buffer isn’t full to make sure logs arrive at a timely fashion."cpu_load_window_size"(integer)
Window size used to calculate a running average of the CPU load."eager_cdn_switching"(boolean)
Tells the router to evaluate the routing tree for every request of a session, even if there are no known issues for the client."http_pipelining_enable"(boolean)
Allows the router to send requests to the CDN while waiting for responses to earlier requests."log_level"(integer)
The verbosity of log printouts. Higher value means more logs: 0 -> Critical, 1 -> Error, 2 -> Warnings, 3 -> Info, 4 -> Debug, 5 -> Trace."max_connections_per_host"(integer)
The number of connections the router is allowed to have to a single CDN host."overload_threshold"(integer)
How long the task queue may be before router is considered overloaded."ready_threshold"(integer)
How short the task queue must become before an overloaded router is no longer considered overloaded."redirecting_cdn_manifest_download_retries"(integer)
Number of times the router can try requesting a manifest or redirect location from a CDN before giving up."repeated_session_start_threshold_seconds"(integer)
How long time a session must wait between requests to avoid being flagged for repeating requests too often, possibly leading to lowered quality of service."selection_input_item_limit"(integer)
The maximum number of key:value items that can be stored on the router using the/v1/selection_inputAPI. Only the leaf values in the input JSON object count towards this limit."selection_input_metrics_timeout_seconds"(integer)
How many seconds a value send to the/v1/selection_inputAPI remains before it’s considered obsolete."session_idle_deactivate_timeout_milliseconds"(integer)
Number of milliseconds between requests before a session is considered idle."session_idle_delete_timeout_milliseconds"(integer)
Number of milliseconds an idle session stays alive to be resumed before it is purged."target_connect_timeout_seconds"(integer)
Number of seconds allowed to establish a connection to a CDN."target_max_idle_time_seconds"(integer)
Number of seconds a connection to a CDN is kept alive even if no new requests occur."target_request_attempts"(integer)
Number of times the router will make requests to different hosts, when it gets 5xx error responses, before giving up and sending an error response to the client."target_response_timeout_seconds"(integer)
Number of seconds before a request to a CDN times out."target_retry_connect_timeout_seconds"(integer)
Number of seconds allowed when retrying to establish a connection to a CDN."target_retry_response_timeout_seconds"(integer)
Number of seconds before a retry request to a CDN times out.
A Full Configuration Example
{
"cdns": [
{
"disabled_hosts": [],
"http_port": 80,
"https_port": 443,
"id": "allowed-cdn",
"manifest_availability_check": {
"enabled": false,
"session_group_ids": []
},
"redirecting": false
},
{
"disabled_hosts": [],
"http_port": 80,
"https_port": 443,
"id": "offload-cdn",
"manifest_availability_check": {
"enabled": false,
"session_group_ids": []
},
"redirecting": false
}
],
"content_server": {
"http_enable": true,
"http_port": 80,
"https_enable": true,
"https_port": 443
},
"custom_lua": "/tmp/custom_lua",
"hosts": [
{
"cdn_id": "allowed-cdn",
"host": "allowed-host4.example",
"id": "allowed-host-4"
},
{
"cdn_id": "allowed-cdn",
"host": "allowed-host6.example",
"id": "allowed-host-6"
},
{
"cdn_id": "offload-cdn",
"host": "offload-host.example",
"id": "offload-host"
}
],
"managed_sessions": {
"fraction": 0.0,
"max_active": 0,
"session_types": [
{
"enabled": false,
"max_active": 0,
"session_group_ids": [],
"type": "instream"
}
]
},
"metadata": {
"extra_info": {
"field_1": "value_1",
"config_name": "large_config",
"purpose": "demonstration",
"arbitrary": "value"
}
},
"request_translation_function": "",
"response_translation_function": "",
"rest_api_server": {
"enable": true,
"port": 5001
},
"routing": {
"id": "routing_table",
"member_order": "sequential",
"members": [
{
"id": "test-subnet-name",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "print(tostring(request.subnet)); return 0"
},
{
"id": "test-host-4",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "retval = request.subnet == 'test_net_4' and 1 or 0;\
if retval == 1 then print('### ipv4') end; return 0"
},
{
"id": "test-host-6",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "retval = request.subnet == 'test_net_6' and 1 or 0;\
if retval == 1 then print('### ipv6') end; return 0"
},
{
"id": "test-offload",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "retval = ((request.subnet == 'test_net_6')\
or (request.subnet == 'test_net_4')) and 1 or 0;\
if retval == 0 then print('### offload') end; return 0"
},
{
"id": "allowed-host-4",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "return request.subnet == 'test_net_4' and 1 or 0"
},
{
"id": "allowed-host-6",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "return request.subnet == 'test_net_6' and 1 or 0"
},
{
"id": "offlaod-host",
"member_order": "weighted",
"members": [],
"url_rewrite_function": "",
"weight_function": "return 1"
}
],
"url_rewrite_function": "",
"weight_function": "return 100"
},
"session_groups": [
{
"classifiers": [
[
{
"id": 1,
"inverted": false,
"name": "hls",
"rule": {
"pattern": "/([^\\.]+)\\.news_reports_\\d+/\\.example\\.com.*",
"rule_type": "regex_rule",
"source": "session/content_url_path"
}
}
]
],
"id": 1,
"name": "hls"
},
{
"classifiers": [
[
{
"id": 2,
"inverted": false,
"name": "vod",
"rule": {
"pattern": "*vod*",
"rule_type": "string_match_rule",
"source": "session/content_url_path"
}
}
]
],
"id": 2,
"name": "vod"
},
{
"classifiers": [
[
{
"id": 5,
"inverted": true,
"name": "offload_no_peering_subnet",
"rule": {
"ip_ranges": [
"158.174.0.0/16",
"95.192.0.0/12"
],
"rule_type": "ip_ranges_rule",
"source": "session/client_ip"
}
}
]
],
"id": 5,
"name": "offload_no_peering_subnet"
},
{
"classifiers": [
[
{
"id": 6,
"inverted": true,
"name": "offload_country_name",
"rule": {
"country": "Sweden",
"rule_type": "geoip_rule",
"source": "session/client_ip"
}
}
]
],
"id": 6,
"name": "offload_country_name"
},
{
"classifiers": [
[
{
"id": 7,
"inverted": false,
"name": "onload_city_name",
"rule": {
"rule_type": "geoip_rule",
"source": "session/client_ip"
}
}
]
],
"id": 7,
"name": "onload_city_name"
},
{
"classifiers": [
[
{
"id": 8,
"inverted": false,
"name": "offload_no_peering_asn_name",
"rule": {
"asn": "Tele*",
"rule_type": "geoip_rule",
"source": "session/client_ip"
}
}
]
],
"id": 8,
"name": "offload_no_peering_asn_name"
}
],
"settings": {
"reversed_filename_comparison": {
"enabled": false
},
"dash_manifest_rewrite": {
"enabled": false,
"session_group_ids": []
},
"extended_content_identifier": {
"enabled": false,
"included_query_params": []
},
"hls_manifest_rewrite": {
"enabled": false,
"session_group_ids": []
}
},
"standard_lua": "/tmp/standard_lua",
"tuning": {
"access_log": false,
"content_cache_size_full_manifests": 1000,
"content_cache_size_light_manifests": 10000,
"content_light_cache_time_milliseconds": 86400000,
"content_live_cache_time_milliseconds": 5000,
"content_vod_cache_time_milliseconds": 10000,
"cout_flush_rate_milliseconds": 1000,
"cpu_load_window_size": 10,
"eager_cdn_switching": false,
"http_pipelining_enable": false,
"log_level": 5,
"max_connections_per_host": 5,
"overload_threshold": 32,
"ready_threshold": 8,
"redirecting_cdn_manifest_download_retries": 2,
"repeated_session_start_threshold_seconds": 30,
"selection_input_metrics_timeout_seconds": 86400,
"session_idle_deactivate_timeout_milliseconds": 20000,
"session_idle_delete_timeout_milliseconds": 1800000,
"target_connect_timeout_seconds": 1,
"target_max_idle_time_seconds": 30,
"target_request_attempts": 2,
"target_response_timeout_seconds": 1,
"target_retry_connect_timeout_seconds": 2,
"target_retry_response_timeout_seconds": 2
}
}