Redis IP Pool Module

The redis_ippool module implements a fast and scalable IP allocation system using Redis.

The module supports both IPv4 and IPv6 address and prefix allocation, and implements pre-allocation for use with DHCPv4.

Lease allocation throughput scales with the number of members in the Redis cluster.

Configuration Settings

Al configuration items at this level (below the redis block) are polymorphic, meaning xlats, attribute references, literal values and execs may be specified.

For example pool_nam could be pool_name = 'my_test_pool' if only a single pool were being used.

pool_name: Name of the pool from which leases are allocated.
offer_time: How long a lease is reserved for after making an offer.

If no value is provided, the value from lease_time is used for initial allocations.

No value should be provided for PPP/VPNs, this is mainly for the DORA flow in DHCP.

lease_time: How long a lease is allocated.
wait_num: How many slaves we want to acknowledge allocations or updates.
wait_timeout: How long we wait for slaves to acknowledge writing.
gateway: Gateway identifier, usually NAS-Identifier or the actual Option 82 gateway. Used for bulk lease cleanups.
owner: The unique owner identifier to which an IP is assigned.

This is used as the lookup key to determine the IP address that has been allocated to a owner. It MUST therefore be something unique to each "owner" to which an IP address may be assigned.

For DHCP it is often simply the MAC address of the owner.

RFC 2132 specifies that the DHCP client may supply a unique identifier ("uid") using Option 61 (Client-Identifier) in which case it must be used as the lookup key for configuration data. Otherwise the client hardware address must be used. To comply with this requirement use the following:

For purposes such as IP assignment using a RADIUS Framed-IP-Address attribute the "owner" identifier could be a User-Name or a certificate serial number provided that the number of sessions is limited to one per user/serial.

On a hostile network it SHOULD include a component that you trust, arranged such that the overall key cannot be spoofed by manipulation of the user-controlled data. For example you might determine that Vendor-Specific.ADSL-Forum.Agent-Circuit-ID is trusted but that Calling-Station-Id is formatted as a user-controlled MAC address:

requested_address: The IP address being renewed or released.
ipv4_integer: Whether IPv4 addresses should be cast to integers, for renew operations.
allocated_address_attr: List and attribute where the allocated address is written to.
range_attr: List and attribute where the IP-Pool.Range ID (if set) is written to.

The idea of the IP-Pool.Range is that it provides a key into other datastores or caches, which store the additional options associated with the range an IP address belongs to.

There may be multiple ranges of IP address contained within any given pool, which is why this is provided in addition to the pool name.

expiry_attr: If set - the list and attribute to write the remaining lease time to.

This attribute can be populated on alloc, or renew, if an IP address was available for the alloc.

copy_on_update: If true - Copy the value of ip_address to the attribute specified by allocated_address_attr when performing an update/renew.

This behavior is needed for DHCP where we need to send back Your-IP-Address in ACKs.

redis { … }: Redis connection settings.

Identical to all other Redis based modules.

See the redis module for more information.

Default Configuration

redis_ippool {
	pool_name = &control.IP-Pool.Name
	offer_time = 30
	lease_time = 3600
#	wait_num = 10
#	wait_timeout = 2
#	gateway = &NAS-Identifier
	owner = &Client-Hardware-Address
#	owner = "%{&Client-Identifier || &Client-Hardware-Address}"
#	owner = "%{Vendor-Specific.ADSL-Forum.Agent-Circuit-ID} %{Calling-Station-Id}"
	requested_address = "%{&Requested-IP-Address || &Net.Src.IP}"
#	ipv4_integer = yes
	allocated_address_attr = &reply.Your-IP-Address
	range_attr = &reply.IP-Pool.Range
	expiry_attr = &reply.IP-Address-Lease-Time
	copy_on_update = yes
	redis {
		server = localhost
		pool {
			start = 0
			min = 0
#			max = 1
			spare = 1
			uses = 0
			lifetime = 0
			retry_delay = 30
			idle_timeout = 60
		}
	}
}