#  -*- text -*-
#
#
#  $Id: 4e02dcf22ce52a2bccd682b34c176b563df79e47 $

#######################################################################
#
#  = 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_name` could be `pool_name = 'my_test_pool'` if
#  only a single pool were being used.
#
redis_ippool {
	#
	#  pool_name:: Name of the pool from which leases are allocated.
	#
	pool_name = control.IP-Pool.Name

	#
	#  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_.
	#
	offer_time = 30

	#
	#  lease_time:: How long a lease is allocated.
	#
	lease_time = 3600

	#
	#  association_time:: How long the owner -> IP association should be
	#  kept.
	#
	#  If this is set, and the value is greater than `lease_time` then
	#  the association between the "owner" and an IP address will be kept
	#  for this many seconds after the allocation / most recent renewal.
	#
	#  This allows for "sticky" addressing, where a request for an
	#  address will return the last one allocated to the owner if it is
	#  within this number of seconds of the allocation / most recent
	#  renewal and the address has not been allocated to another owner.
	#
#	association_time = 7200

	#
	#  wait_num:: How many slaves we want to acknowledge allocations or
	#  updates.
	#
#	wait_num = 10

	#
	#  wait_timeout:: How long we wait for slaves to acknowledge writing.
	#
#	wait_timeout = 2

	#
	#  gateway:: Gateway identifier, usually `NAS-Identifier` or the
	#  actual Option 82 gateway. Used for bulk lease cleanups.
	#
#	gateway = NAS-Identifier

	#
	#  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.
	#
	owner = Client-Hardware-Address

	#
	#  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:
	#
#	owner = "%{Client-Identifier || Client-Hardware-Address}"

	#
	#  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:
	#
#	owner = "%{Vendor-Specific.ADSL-Forum.Agent-Circuit-ID} %{Calling-Station-Id}"

	#
	#  requested_address:: The IP address being renewed or released.
	#
	requested_address = "%{Requested-IP-Address || Net.Src.IP}"

	#
	#  ipv4_integer:: Whether IPv4 addresses should be cast to integers,
	#  for renew operations.
	#
	#
#	ipv4_integer = yes

	#
	#  allocated_address_attr:: List and attribute where the allocated
	#  address is written to.
	#
	allocated_address_attr = reply.Your-IP-Address

	#
	#  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.
	#
	range_attr = reply.IP-Pool.Range

	#
	#  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.
	#
	expiry_attr = reply.IP-Address-Lease-Time

	#
	#  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.
	#
	copy_on_update = yes

	#
	#  redis { ... }:: Redis connection settings.
	#
	#  Identical to all other Redis based modules.
	#
	#  NOTE: See the `redis` module for more information.
	#
	redis {
		server = localhost

		pool {
			start = 0
			min = 0
#			max = 1
			spare = 1
			uses = 0
			lifetime = 0
			retry_delay = 30
			idle_timeout = 60
		}
	}
}
