Route on GeoIP/ASN

How to write ESB3024 Router configurations for GeoIP and ASN-based routing using classifiers and session groups.

This page describes how to write configuration for GeoIP and ASN-based routing. For configuration in general, see Configuration.

For more details on session groups and classifiers, see Session Groups and Classification.

ASN

Routing on ASN is done through a combination of session group classifiers and Lua script weight functions. We need to create ASN classifier(s) and then associate them with a session group:

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

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

classifiers : [
  classifier can be one of
    1: anonymousIp
    2: asnIds
    3: contentUrlPath
    4: contentUrlQueryParameters
    5: geoip
    6: hostName
    7: ipranges
    8: random
    9: regexMatcher
    10: stringMatcher
    11: subnet
    12: userAgent
  Choose element index or name: geoip
  Adding a 'geoip' element
    classifier : {
      name (default: ): allowed_asn_classifier
      type (default: geoip): ⏎
      inverted (default: False): ⏎
      continent (default: ): ⏎
      country (default: ): ⏎
      cities : [
        city (default: ): ⏎
        Add another 'city' element to array 'cities'? [y/N]: ⏎
      ]
      asn (default: ): Agile*ISP
    }
  Add another 'classifier' element to array 'classifiers'? [y/N]: ⏎
]
Generated config:
{
  "classifiers": [
    {
      "name": "allowed_asn_classifier",
      "type": "geoip",
      "inverted": false,
      "continent": "",
      "country": "",
      "cities": [],
      "asn": "Agile*ISP"
    }
  ]
}
Merge and apply the config? [y/n]: y
$ confcli services.routing.sessionGroups -w
Running wizard for resource 'sessionGroups'

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

sessionGroups : [
  sessionGroup : {
    name (default: ): allowed_asn
    classifiers : [
      classifier (default: ): allowed_asn_classifier
      Add another 'classifier' element to array 'classifiers'? [y/N]: ⏎
    ]
  }
  Add another 'sessionGroup' element to array 'sessionGroups'? [y/N]: ⏎
]
Generated config:
{
  "sessionGroups": [
    {
      "name": "allowed_asn",
      "classifiers": [
        "allowed_asn_classifier"
      ]
    }
  ]
}
Merge and apply the config? [y/n]: y

{
  "session_groups": [
    {
      "id": 1,
      "name": "allowed_asn",
      "classifiers": [
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_asn_classifier",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "asn": "Agile*ISP"
            }
          }
        ]
      ]
    }
  ]
}

The asn value is a string, matching an ISP name or similar. It supports wildcard matching using asterisks and is case insensitive.

Note that each ASN classifier has to be in its own list. This is because classifiers within the same inner list all have to match for the entire list to be true, and that is impossible for classifiers that match against different ASNs. When the classifiers are in their own lists, it’s enough that one of them matches for the outer classifier list to also match.

Simple Example

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

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

rules : [
rules : [
  rule can be one of
    1: allow
    2: consistentHashing
    3: contentPopularity
    4: deny
    5: firstMatch
    6: random
    7: rawGroup
    8: rawHost
    9: split
    10: weighted
  Choose element index or name: split
  Adding a 'split' element
    rule : {
      name (default: ): asn_split_node
      type (default: split): ⏎
      rule (default: ): return in_session_group("allowed_asn")
      onMatch (default: ): allowed-asn-host
      onMiss (default: ): offload-host
    }
  Add another 'rule' element to array 'rules'? [y/N]: ⏎
]
Generated config:
{
  "rules": [
    {
      "name": "asn_split_node",
      "type": "split",
      "condition": "in_session_group('allowed_asn')",
      "onMatch": "allowed-asn-host",
      "onMiss": "offload-host"
    }
  ]
}
Merge and apply the config? [y/n]: y

{
  "content_server": {
    "http_enable": true,
    "http_port": 80,
    "https_enable": true,
    "https_port": 443
  },
  "session_groups": [
    {
      "id": 1,
      "name": "allowed_asn",
      "classifiers": [
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_asn_classifier_agile",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "asn": "Agile*ISP"
            }
          }
        ],
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_asn_classifier_edgeware",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "asn": "Edgeware *"
            }
          }
        ]
      ]
    }
  ],
  "cdns": [
    {
      "id": "basic-cdn",
      "http_port": 80,
      "https_port": 443,
      "redirecting": false,
      "manifest_availability_check": {
        "enabled": false,
        "session_group_ids": []
      }
    },
    {
      "id": "offload-cdn",
      "http_port": 80,
      "https_port": 443,
      "redirecting": false,
      "manifest_availability_check": {
        "enabled": false,
        "session_group_ids": []
      }
    }
  ],
  "hosts": [
    {
      "id": "default-host",
      "cdn_id": "basic-cdn",
      "address_family": "ipv4",
      "host": "cdn-host.example"
    },
    {
      "id": "offload-host",
      "cdn_id": "offload-cdn",
      "address_family": "ipv4",
      "host": "offload-host.example"
    }
  ],
  "routing": {
    "id": "routing_table",
    "member_order": "sequential",
    "members": [
      {
        "id": "default-node",
        "host-id": "default-host",
        "weight_function": "return in_session_group('allowed_asn')"
      },
      {
        "id": "offload-node",
        "host_id": "offload-host",
        "weight_function": "return 1"
      }
    ]
  }
}

Geographical Location

Routing on geographical location is done in a similar fashion. Once again, we create location classifier(s) and associate them with a session group:

Geographical locations are provided by a MaxMind database.

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

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

classifiers : [
  classifier can be one of
    1: anonymousIp
    2: asnIds
    3: contentUrlPath
    4: contentUrlQueryParameters
    5: geoip
    6: hostName
    7: ipranges
    8: random
    9: regexMatcher
    10: stringMatcher
    11: subnet
    12: userAgent
  Choose element index or name: geoip
  Adding a 'geoip' element
    classifier : {
      name (default: ): allowed_location
      type (default: geoip): ⏎
      inverted (default: False): ⏎
      continent (default: ): ⏎
      country (default: ): ⏎
      cities : [
        city (default: ): stockholm
        Add another 'city' element to array 'cities'? [y/N]: ⏎
      ]
      asn (default: ): ⏎
    }
  Add another 'classifier' element to array 'classifiers'? [y/N]: ⏎
]
Generated config:
{
  "classifiers": [
    {
      "name": "allowed_location",
      "type": "geoip",
      "inverted": false,
      "continent": "",
      "country": "",
      "cities": [
        "stockholm"
      ],
      "asn": ""
    }
  ]
}
Merge and apply the config? [y/n]: y

  "session_groups": [
    {
      "id": 1,
      "name": "allowed_location",
      "classifiers": [
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_location_classifier",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "continent": "",
              "country": "",
              "region": "",
              "cities": ["stockholm"]
            }
          }
        ]
      ]
    }
  ]

At least one of the optional fields continent, country, region and cities are required. The classifier matches a request when all specified fields do (for the cities list, one matching member is sufficient). All values support wildcard matching using asterisks and are case insensitive.

Note that each location classifier has to be in its own list. This is because classifiers within the same inner list all have to match for the entire list to be true, and that is impossible for classifiers that match against different locations. When the classifiers are in their own lists, it’s enough that one of them matches for the outer classifier list to also match.

Simple Example

confcli services.routing.rules -w
Running wizard for resource 'rules'

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

rules : [
rules : [
  rule can be one of
    1: allow
    2: consistentHashing
    3: contentPopularity
    4: deny
    5: firstMatch
    6: random
    7: rawGroup
    8: rawHost
    9: split
    10: weighted
  Choose element index or name: split
  Adding a 'split' element
    rule : {
      name (default: ): geographic_location_split_node
      type (default: split): ⏎
      rule (default: ): return in_session_group("allowed_location")
      onMatch (default: ): allowed-location-host
      onMiss (default: ): offload-host
    }
  Add another 'rule' element to array 'rules'? [y/N]: ⏎
]
Generated config:
{
  "rules": [
    {
      "name": "geographic_location_split_node",
      "type": "split",
      "condition": "in_session_group('allowed_location')",
      "onMatch": "allowed-location-host",
      "onMiss": "offload-host"
    }
  ]
}
Merge and apply the config? [y/n]: y

{
  "content_server": {
    "http_enable": true,
    "http_port": 80,
    "https_enable": true,
    "https_port": 443
  },
  "session_groups": [
    {
      "id": 1,
      "name": "allowed_location",
      "classifiers": [
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_location_classifier_sweden",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "country": "Sweden"
            }
          }
        ],
        [
          {
            "id": 1,
            "inverted": false,
            "name": "allowed_location_classifier_oslo",
            "rule": {
              "rule_type": "geoip_rule",
              "source": "session/client_ip",
              "country": "Norway",
              "cities": ["Oslo"]
            }
          }
        ]
      ]
    }
  ],
  "cdns": [
    {
      "id": "basic-cdn",
      "http_port": 80,
      "https_port": 443,
      "redirecting": false,
      "manifest_availability_check": {
        "enabled": false,
        "session_group_ids": []
      }
    },
    {
      "id": "offload-cdn",
      "http_port": 80,
      "https_port": 443,
      "redirecting": false,
      "manifest_availability_check": {
        "enabled": false,
        "session_group_ids": []
      }
    }
  ],
  "hosts": [
    {
      "id": "default-host",
      "cdn_id": "basic-cdn",
      "address_family": "ipv4",
      "host": "cdn-host.example"
    },
    {
      "id": "offload-host",
      "cdn_id": "offload-cdn",
      "address_family": "ipv4",
      "host": "offload-host.example"
    }
  ],
  "routing": {
    "id": "routing_table",
    "member_order": "sequential",
    "members": [
      {
        "id": "default-node",
        "host_id": "default-host",
        "weight_function": "return in_session_group('allowed_location')"
      }
      {
        "id": "offload-node",
        "host_id": "offload-host",
        "weight_function": "return 1"
      }
    ]
  }
}