



= 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.

NOTE: 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 `link:https://freeradius.org/rfc/rfc2865.html#NAS-Identifier[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.



https://tools.ietf.org/html/rfc2132[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 `link:https://freeradius.org/rfc/rfc2865.html#User-Name[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.

NOTE: 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
		}
	}
}
```
