CDNs and Hosts

Configuring CDNs and hosts

In order to route requests, the ACD Director needs to be configured with hosts that can serve them. Hosts are grouped in host groups, where each group contains hosts that share some common settings. There are three types of host groups: host, redirecting and DNS:

host: Content is served directly. An example of a such a host is the ESB3004 SW Streamer.
redirecting: These hosts are themselves CDN selectors. The Director expects a redirecting CDN to respond with a redirection URL which tells where the content can be found. A typical redirecting CDN is the ESB3008 HTTP Request Router.
DNS: These hosts are EDNS servers. The ACD Director sends DNS requests to these hosts and expects them to respond with an IP address where the content can be found.

Each host group contains a list of hosts. In addition to that, the host groups have different parameters depending on their type.

Common host group parameters

These parameters are present in all host groups:

name: The name of the host group. This is used to reference the host group from other parts of the configuration.
type: The type of the host group as listed above.
headersToForward: A list of HTTP headers to forward from the client to the CDN. This is useful if the CDN needs to know about the original Host header or any custom headers added by the client or an upstream proxy. If the incoming request contains an X-Forwarded-For header, that header will be forwarded to the CDN even if it is not listed.
hosts: A list of hosts in this host group. The configuration of hosts is detailed in Hosts below.

Parameters shared by `host` and `redirecting` host groups

These parameters are only present in host and redirecting host groups:

httpPort: The port to use when sending HTTP requests to the hosts in this group.
httpsPort: The port to use when sending HTTPS requests to the hosts in this group.

`host` group parameters

These parameters are only present in host host groups:

createStreamerSession: AgileTV streamers require a session to be allocated when redirecting to them. Setting this parameter to true tells the Director to create such a session when redirecting to hosts in this group.

`redirecting` group parameters

These parameters are only present in redirecting host groups:

allowAnyRedirectType: The ACD Director expects redirecting CDNs to redirect with response code 302. Setting this parameter to true allows the Director to accept any 3xx response code as a redirection URL.

Hosts

The hosts parameter is the same in all host groups. It contains a list of hosts, each with the following parameters:

name: The name of the host. This is used to reference the host from other parts of the configuration.
hostname: The hostname of the host. This is where requests are sent. It can be an IPv4 address or a domain name.
ipv6_address: The IPv6 address of the host. This is used when the Director needs to send requests to the host over IPv6. If this parameter is not set, the Director will use the hostname parameter for both IPv4 and IPv6 requests.
healthChecks: A list of Lua functions to determine if the host is healthy and can be selected for routing. If any of the health check functions returns false, the host will be considered unhealthy and will not be selected for routing. All health check functions are detailed in the section Built-in Lua functions.

Configuration examples

Below are some examples on how different types of host groups with hosts can be configured.

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: host
  Adding a 'host' element
    hostGroup : {
      name (default: ): streamers
      type (default: host): ⏎
      httpPort (default: 80): ⏎
      httpsPort (default: 443): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: ⏎
      ]
      createStreamerSession (default: False): True
      hosts : [
        host : {
          name (default: ): streamer1
          hostname (default: ): streamer1.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): health_check()
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: y
        host : {
          name (default: ): streamer2
          hostname (default: ): streamer2.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "streamers",
      "type": "host",
      "httpPort": 80,
      "httpsPort": 443,
      "headersToForward": [
        ""
      ],
      "createStreamerSession": true,
      "hosts": [
        {
          "name": "streamer1",
          "hostname": "streamer1.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "health_check()"
          ]
        },
        {
          "name": "streamer2",
          "hostname": "streamer2.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: redirecting
  Adding a 'redirecting' element
    hostGroup : {
      name (default: ): edgeware
      type (default: redirecting): ⏎
      httpPort (default: 80): ⏎
      httpsPort (default: 443): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: ⏎
      ]
      allowAnyRedirectType (default: False): ⏎
      hosts : [
        host : {
          name (default: ): rr1
          hostname (default: ): convoy-rr1.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): health_check()
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: y
        host : {
          name (default: ): rr2
          hostname (default: ): convoy-rr2.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "edgeware",
      "type": "redirecting",
      "httpPort": 80,
      "httpsPort": 443,
      "headersToForward": [
        ""
      ],
      "allowAnyRedirectType": false,
      "hosts": [
        {
          "name": "rr1",
          "hostname": "convoy-rr1.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "health_check()"
          ]
        },
        {
          "name": "rr2",
          "hostname": "convoy-rr2.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

$ confcli services.routing.hostGroups -w
Running wizard for resource 'hostGroups'

Hint: Hitting return will set a value to its default.
Enter '?' to receive the help string

hostGroups : [
  hostGroup can be one of
    1: dns
    2: host
    3: redirecting
  Choose element index or name: dns
  Adding a 'dns' element
    hostGroup : {
      name (default: ): external-dns
      type (default: dns): ⏎
      headersToForward <A list of HTTP headers to forward to the CDN. (default: [])>: [
        headersToForward (default: ): ⏎
        Add another 'headersToForward' element to array 'headersToForward'? [y/N]: n
      ]
      hosts : [
        host : {
          name (default: ): dns-host
          hostname (default: ): dns.example.com
          ipv6_address (default: ): ⏎
          healthChecks : [
            healthCheck (default: always()): ⏎
            Add another 'healthCheck' element to array 'healthChecks'? [y/N]: n
          ]
        }
        Add another 'host' element to array 'hosts'? [y/N]: ⏎
      ]
    }
  Add another 'hostGroup' element to array 'hostGroups'? [y/N]: ⏎
]
Generated config:
{
  "hostGroups": [
    {
      "name": "external-dns",
      "type": "dns",
      "headersToForward": [
        ""
      ],
      "hosts": [
        {
          "name": "dns-host",
          "hostname": "dns.example.com",
          "ipv6_address": "",
          "healthChecks": [
            "always()"
          ]
        }
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y