Kea Configuration for Cable Providers

The Network

The network described here is a small Cable modem based ISP network with only one service area. This simple network is depicted in the diagram below.

Requirements Summary

A Kea configuration for cable services can be complicated even if the service area consists of only one POP. This is due to the variety of networks that may simultaneously exist on a single cable modem at a customer residence.

There could be as many as three in a typical deployment. One for the cable modem itself, one for the Internet CPE, and finally one for the eMTA (if telephone service is offered). There are a few DHCP options that must be present as well beyond the usual gateway, subnetmask and DNS server options.

There are many advanced options that might be used in a cable modem deployment. For example, some configurations may require client classing due to the inability to separate DHCP requests by relay source (all come from the same source) such that cable modem, CPE, and eMTA DHCP requests can't be separated). In the interest of brevity, this document will not cover these advanced configurations.

Management features

The cable operator will need support for TFTP, to load images into the cable modems. They may also require a few advanced management features, provided by Kea hooks, including Bulk leasequery and Forensic logging. A basic logging configuration is provided, but most operators will want to expand on that.

As with any significant size network, the design should provide for high-availability. Although not depicted here, Kea does support High Availability. The recommended configuration is "hot-standby" as it is the simplest and most robust. Further information regarding High Availability is available in the ARM.

Performance considerations

The operator must ensure that the DHCP service scales for the number of expected clients, given the lease renewal period planned. In a cable environment, typically the operator plans ample overhead for a peak traffic 'avalanche' scenario when a CMTS needs to be rebooted, triggering a flood of DHCP renewal requests. This document does not go into performance considerations in detail, but we have avoided recommending configurations with known significant performance impacts. For more information, see this KB article on Kea Performance Optimization.. Performance tests are performed periodically on stable Kea branches. See this KB article on Kea 2.0, or consult the Reports tab on Kea.isc.org for details.

The Configuration

As before, both DHCPv4 and DHCPv6 configurations will be described. The complete configurations for each will be appended to the bottom of this article. This article is meant as a starting point for smaller, simpler networks. Full details about all of the Kea configuration possibilities can be found in the Kea ARM.

Internet subscriber subnet

This is the simplest part of the cable modem provider configuration for Kea. Nothing special needs to be done here. The example DHCPv4 and DHCPv6 subnet configurations from the Kea Configuration for Small Office or Home Use article would be sufficient to serve subscriber (cpe) devices. This will be reflected in the final configurations at the bottom of this article.

Cable modem subnets

Shown below is the shared-networks block for a DHCPv4 Kea instance that could be used by cable modems. Both of the subnets shown are used. They are grouped together in a shared-networks block so that Kea understands that the subnets are related. The first subnet of 10.128.0.0/24 will be used by KNOWN paying subscribers (note the special client class of KNOWN that is referenced in the pools block). This subnet also has a tftp server and boot file for the cable modem configuration specified in the options section. Additionally, RFC 868 time servers are supplied in the time-servers option as these are used by cable modems.

The second subnet is for UNKNOWN which is selected in the pools block by referencing the special client class UNKNOWN. It again has the options for tftp server and boot file which, in this case, is a different configuration file for customers who failed to pay their bill. Again, the time-servers option is included here.

The KNOWN and UNKNOWN special classes can be used to control access in the manner shown here. A client becomes a member of the KNOWN class by having a reservation present for the client. The client 00:0c:01:02:03:04 is KNOWN as it has a reservation. Further details about special classes are available in the Kea ARM. It is also possible to store the reservations in a database and update them dynamically using the API. Details about that are also available in the ARM.

There may be other options required for use with cable modems. In some cases cable modems may need to be added to client classes for special options required by the vendor. Sometimes operators may even need to deliver differing configuration files depending on vendor or service level. This can all be accomplished with client-class. See the Kea ARM, or this KB article, for details regarding the usage of client classing.

{
  "Dhcp4": {
    "shared-networks": [
      {
        "name": "CableModems",
        "subnet4": [
          {
            "subnet": "10.128.0.0/24",
            "pools": [
              {
                "pool": "10.128.0.10 - 10.128.0.254",
                "client-class": "KNOWN"
              }
            ],
            "reservations": [
              {
                "hw-address": "00:0c:01:02:03:04"
              }
            ],
            "option-data": [
              {
                "name": "routers",
                "data": "10.128.0.1"
              },
              {
                "name": "time-servers",
                "data": "192.0.2.4, 192.0.2.5"
              },
              {
                "name": "tftp-server-name",
                "data": "172.31.10.12"
              },
              {
                "name": "boot-file-name",
                "data": "some-cable-modem.cfg"
              }
            ]
          },
          {
            "subnet": "10.128.255.0/24",
            "pools": [
              {
                "pool": "10.128.255.10 - 10.128.255.254",
                "client-class": "UNKNOWN"
              }
            ],
            "option-data": [
              {
                "name": "routers",
                "data": "10.128.255.1"
              },
              {
                "name": "time-servers",
                "data": "192.0.2.4, 192.0.2.5"
              },
              {
                "name": "tftp-server-name",
                "data": "172.31.10.12"
              },
              {
                "name": "boot-file-name",
                "data": "some-cable-modem-nonpay.cfg"
              }
            ]
          }
        ]
      }
    ]
  }
}

At the time of this writing, most cable operators use only DHCPv4 for the cable modem provisioning and management.

Lease Query support

It should be noted that some CMTS require bulk leasequery functionality to properly serve a cable modem network. This is used to recover from a reboot or other event that removes cable modem to IP address mappings from the system. As of Kea 2.3.5, bulk leasequery for DHCPv4 is now supported. The configuration below shows a simple example to serve a CMTS router at 192.0.2.1 from a Kea server at 192.0.2.3.

    "hooks-libraries": [
      {
        "library": "/path/libdhcp_lease_query.so",
        "parameters":
          {
            "requesters": [ 
              "192.0.2.1"
            ],
            "advanced" :
              {
                "bulk-query-enabled": true,
                "lease-query-ip": "192.0.2.3"
              }
          }
      }
    ],

eMTA subnet

This is also very simple though not quite as simple as the Internet Subscriber Subnet above. There may be special vendor specific options that may be required here depending on modem brand. A very simple subnet will be shown in the final example below. In practice the configuration may be somewhat more complex. This is another area where currently, DHCPv4 is the dominant address form.

Complete DHCPv4 configuration

This is a complete configuration that could be used to serve basic cable internet and phone service. In the interfaces section we have dhcp-socket-type set to udp. This is because we know all traffic will be relayed to the DHCP server so there is no reason to listen for broadcast packets locally. Additionally, you will notice that there are several user-context sections. These are comments which convey some identifying information regarding their enclosing block.

There are probably additional vendor-specific options needed, which will vary depending on your equipment. You may want to review the article about logging as the loggers configuration below is pretty anemic.

{
  "Dhcp4": {
    "hooks-libraries": [
      {
        "library": "/path/libdhcp_lease_query.so",
        "parameters":
          {
            "requesters": [ 
              "192.0.2.1"
            ],
            "advanced" :
              {
                "bulk-query-enabled": true,
                "lease-query-ip": "192.0.2.3"
              }
          }
      }
    ],
    "interfaces-config": {
      "interfaces": [
        "ens256"
      ],
      "dhcp-socket-type": "udp"
    },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "/tmp/dhcp4.leases"
    },
    "valid-lifetime": 28800,
    "calculate-tee-times": true,
    "option-data": [
      {
        "name": "domain-name-servers",
        "data": "192.0.2.6, 192.0.2.7"
      }
    ],
    "shared-networks": [
      {
        "name": "CableModems",
        "subnet4": [
          {
            "subnet": "10.128.0.0/24",
            "user-context": {
              "comment": "Valid subscriber cable modems"
            },
            "pools": [
              {
                "pool": "10.128.0.10 - 10.128.0.254",
                "client-class": "KNOWN"
              }
            ],
            "reservations": [
              {
                "hw-address": "00:0c:01:02:03:04"
              }
            ],
            "option-data": [
              {
                "name": "routers",
                "data": "10.128.0.1"
              },
              {
                "name": "time-servers",
                "data": "192.0.2.4, 192.0.2.5"
              },
              {
                "name": "tftp-server-name",
                "data": "172.31.10.12"
              },
              {
                "name": "boot-file-name",
                "data": "some-cable-modem.cfg"
              }
            ]
          },
          {
            "subnet": "10.128.255.0/24",
            "user-context": {
              "comment": "Invalid devices and cable modems without a subscription"
            },
            "pools": [
              {
                "pool": "10.128.255.10 - 10.128.255.254",
                "client-class": "UNKNOWN"
              }
            ],
            "option-data": [
              {
                "name": "routers",
                "data": "10.128.255.1"
              },
              {
                "name": "time-servers",
                "data": "192.0.2.4, 192.0.2.5"
              },
              {
                "name": "tftp-server-name",
                "data": "172.31.10.12"
              },
              {
                "name": "boot-file-name",
                "data": "some-cable-modem-nonpay.cfg"
              }
            ]
          }
        ]
      }
    ],
    "subnet4": [
      {
        "subnet": "100.64.0.0/24",
        "user-context": {
          "comment": "CPE subnet subject to CGNAT"
        },
        "pools": [
          {
            "pool": "100.64.0.1 - 100.64.0.253"
          }
        ],
        "option-data": [
          {
            "name": "routers",
            "data": "100.64.0.254"
          }
        ]
      },
      {
        "subnet": "10.64.64.0/24",
        "user-context": {
          "comment": "eMTA subnet for phone services to subscribers"
        },
        "pools": [
          {
            "pool": "10.64.64.10 - 10.64.64.254"
          }
        ],
        "option-data": [
          {
            "name": "routers",
            "data": "10.64.64.1"
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp4",
        "output_options": [
          {
            "output": "/tmp/kea-dhcp4.log",
            "maxver": 10
          }
        ],
        "severity": "INFO"
      }
    ]
  }
}

Complete DHCPv6 configuration

The DHCPv6 configuration can be much shorter in a cable service provider network. This is because only the CPE devices (customer router, gaming consoles, PC and etc...) are being served with IPv6 addresses in this article's scenario. That is somewhat likely to change in the future as DHCPv4 starts being replaced by DHCPv6. Below is a complete configuration that should work in a cable modem deployment that supports DHCPv6 for CPE devices. As previously mentioned, you may want to review the logging configuration article and configure more robust logging.

You may also notice that there is a block called pd-pools that mentions prefix, prefix length, and delegated length. That is used by Kea to delgate prefixes to the CPE routers for use internally as IPv6 no longer has a NAT component. More details are available in the ARM.

{
  "Dhcp6": {
    "interfaces-config": {
      "interfaces": [
        "ens256"
      ]
    },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "/tmp/dhcp6.leases"
    },
    "valid-lifetime": 28800,
    "preferred-lifetime": 23040,
    "calculate-tee-times": true,
    "option-data": [
      {
        "name": "dns-servers",
        "data": "2001:db8:192:0::6, 2001:db8:192:0::7"
      }
    ],
    "subnet6": [
      {
        "subnet": "2001:db8:64:0::/64",
        "user-context": {
          "comment": "CPE subnet"
        },
        "pools": [
          {
            "pool": "2001:db8:64:0::2 - 2001:db8:64:0:ffff:ffff:ffff:ffff"
          }
        ],
        "pd-pools": [
          {
            "prefix": "2001:db8:128::",
            "prefix-len": 48,
            "delegated-len": 60
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp6",
        "output_options": [
          {
            "output": "/tmp/kea-dhcp6.log",
            "maxver": 10
          }
        ],
        "severity": "INFO"
      }
    ]
  }
}