



= SQL-IP-Pool Module

The module `sqlippool` provide configuration for the SQL based IP Pool module.

NOTE: The database schemas are available at `raddb/sql/ippool/<DB>/schema.sql`.

## Configuration Settings


sql_module_instance:: SQL instance to use (from `raddb/mods-available/sql`)

If you have multiple sql instances, such as `sql sql1 {...}`,
use the *instance* name here: `sql1`.



dialect:: This is duplicative of info available in the SQL module, but
we have to list it here as we do not yet support nested
reference expansions.



ippool_table:: SQL table to use for ippool range and lease info.



lease_duration:: IP lease duration.



offer_duration:: DHCP offer duration.



pool_name: The attribute in the `control` list which contains the pool name.



allocated_address_attr:: List and attribute where the allocated address is written to.

[NOTE]
====
It MUST be a qualified name of an attribute of a type which contains IP addresses.

e.g. `ipaddr`, `ipv4prefix,` `ipv6addr`, or `ipv6prefix`.
====


owner:: Expansion which identifies the owner of the lease.

For an operation (i.e. a request to extend a lease, or release an
IP address) to be applied, the owner specified in the incoming
packet must match the owner recorded for the lease.

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.

For RADIUS the owner will likely be specified by:

  * `%{radius.Calling-Station-Id}` which binds the lease to the mac address
  of the user's device.  For RADIUS this is almost always the better
  option as it can allow the user's device to move between NAS.

  * `%{radius.NAS-Port}` which binds the lease to a given port on the NAS.
  i.e. any device on that port can modify the lease.  This should only
  be used when the port is constant for the length of the session
  (nearly everywhere except 802.11 wireless).

For DHCPv4 the owner will likely be specified by:

  * `%{dhcpv4.Client-Hardware-Address}` which binds the lease to the
  mac address of the user's device.

  * `%{&dhcpv4.Client-Identifier || &dhcpv4.Client-Hardware-Address}`
  which binds the lease to either the custom identifier set by the
  DHCP client, or if this is absent, the mac address of the user's
  device.

On a hostile network the owner SHOULD include a component that you
trust, arranged such that the overall value cannot be spoofed by
manipulation of the user-controlled data (i.e. the mac or identifier)
provided by the user's device.

For example it might be that the value `Vendor-Specific.ADSL-Forum.Agent-Circuit-ID` is
considered trusted as it's set by a controlled device at the edge of
the network.  Calling-Station-Id however, is usually provided by
the user's device so may be spoofed.

In order to prevent an attacker releasing DHCP leases for another
device on the network, the owner string should be constructed so
that it contains both the trusted and untrusted attributes, or if
the trusted attribute is sufficiently stable and unique, only the
trusted attribute.
One example would be `%{Vendor-Specific.ADSL-Forum.Agent-Circuit-ID}.%{Calling-Station-Id}`.`


     owner = "%{radius.Vendor-Specific.ADSL-Forum.Agent-Circuit-ID}.%{radius.Calling-Station-Id}"



requested_address:: The IP address being renewed or released.

For RADIUS the requested_address will almost always be `%{radius.Framed-IP-Address}`.

For DHCPv4 the requested_address will almost always be
`%{&dhcpv4.Requested-IP-Address || &dhcpv4.Client-IP-Address}`.




gateway:: The device controlling access to the network or relaying
DHCP packets.

For RADIUS, this device is recorded so that if an Accounting-On or
Accounting-Off packet is received, then all leases associated with
the gateway can be released. 'gateway' in this context is synonymous
with the NAS the user is connected to.

For DHCPv4, this device is recorded so that we can respond correctly
to lease queries.


     gateway = "%{dhcpv4.Gateway-IP-Address}"


messages { ... }:: These messages are added to the `control.:` items, as
`Module-Success-Message`. They are not logged anywhere else, unlike
previous versions.
If you want to have them logged to a file, see the `linelog` module,
and create an entry which writes `Module-Success-Message` message.

WARNING: MySQL (MyISAM) has certain limitations that means it can hand out
the same IP address to 2 different users.
  *We suggest* using an SQL DB with proper transaction support, such as PostgreSQL,
or using MySQL with InnoDB.







.Load the queries from a separate file.


== Default Configuration

```
sqlippool {
	sql_module_instance = "sql"
	dialect = "mysql"
	ippool_table = "fr_ippool"
	lease_duration = 3600
	offer_duration = 60
	pool_name = IP-Pool.Name
	allocated_address_attr = radius.Framed-IP-Address
	owner = "%{radius.Calling-Station-ID}"
#	owner = "%{&dhcpv4.Client-Identifier || &dhcpv4.Client-Hardware-Address}"
	requested_address = "%{radius.Framed-IP-Address}"
#	requested_address = "%{&dhcpv4.Requested-IP-Address || &dhcpv4.Client-IP-Address}"
	gateway = "%{&radius.NAS-Identifier || &radius.NAS-IP-Address}"
	messages {
		exists = "Existing IP: %{reply.${..allocated_address_attr}} (did %{Called-Station-Id} cli %{Calling-Station-Id} port %{NAS-Port} user %{User-Name})"
		success = "Allocated IP: %{reply.${..allocated_address_attr}} from %{control.IP-Pool.Name} (did %{Called-Station-Id} cli %{Calling-Station-Id} port %{NAS-Port} user %{User-Name})"
		clear = "Released IP ${..requested_address} (did %{Called-Station-Id} cli %{Calling-Station-Id} user %{User-Name})"
		failed = "IP Allocation FAILED from %{control.IP-Pool.Name} (did %{Called-Station-Id} cli %{Calling-Station-Id} port %{NAS-Port} user %{User-Name})"
		nopool = "No IP-Pool.Name defined (did %{Called-Station-Id} cli %{Calling-Station-Id} port %{NAS-Port} user %{User-Name})"
	}
	$INCLUDE ${modconfdir}/sql/ippool/${dialect}/queries.conf
}
```
