FreeRADIUS InkBridge

SQL-IP-Pool

The sqlippool module allocates IP addresses from one or more pools of addresses. It tracks addresses to that it does not issue the same leased IP address to multiple devices.

Using FreeRADIUS for IP address allocation has some advantages. Centralized pool management means that the pools remains available when one or more of the NASs becomes unavailable. When pools are managed on a NAS, the pools are down when the NAS is down.

Networks may have organisation-specific policies for the way that IP addresses are assigned. These policies are difficult to implement on a NAS, but can be implemented with FreeRADIUS. For example, FreeRADIUS can assign pools of IP addresses to specific NASs or user groups. FreeRADIUS also control reallocation, in order to move users from one pool to another, without disconnecting them. This move allows address ranges to be retired or repurposed without forcibly disconnecting the users.

As with most FreeRADIUS modules, the sqlippool module ships with a default configuration that "just works". However, the module can also be configured to use sophisticated IP allocation policies, via custom SQL queries.

All of the SQL queries used by the module are configurable. The module simply provides for a few "hooks", in order to allocate an IP, clear an IP, expire IPs, etc. The result is that the IP pool allocations works with all possible SQL databases, without requiring code changes. In addition, anyone familiar with SQL can customize the allocation policies. Minimal knowledge of FreeRADIUS is required.

The default schema and queries are also designed to manage both dynamic and static IP address assignment through the use of the status column.

Operation

The SQL IP Pools module only perform an action when FreeRADIUS receives a packet. The entire state of the pools is held in the fr_ippool table. The benefit of this approach is that the RADIUS server can be restarted, replaced, or debugged without losing track of any IP addresses.

One downside is that there is no method to perform actions at a particular time. We suggest using "cron" for periodic cleanups, analysis, etc.

Another downside is that FreeRADIUS does not "know" the state of a particular IP address. The sqlippool module simply runs SQL queries, which either return an IP address, or return "failed to allocate IP". Since the entire state of the pool is in the SQL database, we recommend using standard SQL queries to find the state of an individual IP address, MAC address, etc.

Access-Request: A device connects to the NAS with correct credentials

  1. FreeRADIUS receives an Access-Request from the NAS. After some processing (modules. unlang, etc.), the IP-Pool.Name attribute is added to the control list. This attribute indicates that the IP address should be allocated from the named pool. This attribute can be added from any module, database, unlang, etc.

  2. When the sqlippool module is eventually run, it looks for the IP-Pool.Name attribute, and runs the various SQL queries in order to perform IP address allocation. If the module is configured to place address into the Framed-IP-Address attribute (as it is by default), and that attribute already exists, the module does nothing, and returns noop.

  3. The module then runs the alloc_existing query, which looks for the IP address last assigned to the device from the pool indicated by IP-Pool.Name. The device is identified using the owner configuration item (typically NAS-Port) and the gateway configuration item (usually NAS-IP-Address).

  4. If no address was found using alloc_existing, and both requested_address expands to a value and the alloc_requested query is configured, then the module runs the alloc_requested query which looks to see if the address identified by requested_address is available.

  5. If no address was found using alloc_existing or alloc_requested, the module then runs the alloc_find query, which chooses a free IP address from the pool indicated by IP-Pool.Name. If alloc_find does not return an IP address, the pool_check query is run in order to determine why the allocation failed. For example, either the requested pool is empty (i.e. no free addresses), or it is non-existent. This information is returned in the sqlippool module return code, as notfound, or one of the other return codes.

  6. If an IP address has been found, the module runs the alloc_update query. This query assigns the IP address to the device by updating the fr_ippool row for the IP address with information about the lease. The default information includes expiry time based on the configured lease_duration, a unique identifier for the device as specified by the owner configuration item (typically NAS-Port) and gateway (the NAS-IP-Address). This information can be used to assign the same IP to the same user or device, on subsequent allocation requests. With some database backends (PostgreSQL and MS SQLServer) the update can be incorporated into the alloc_existing, alloc_requested and alloc_find queries, reducing round trips to the database and improving performance.

  7. The module returns updated to indicate that it was successful in allocating an IP address.

  8. After some additional processing (modules, unlang, etc.), FreeRADIUS sends an Access-Accept containing a Framed-IP-Address attribute holding the allocated IP address to the NAS.

Accounting Start: A device and a NAS successfully establish a session

  1. The NAS sends an Accounting Start request to FreeRADIUS. After some processing (modules. unlang, etc.), the sqlippool module is run.

  2. The sqlippol module runs the update_update query. This query uses the configured requested_address, owner and pool_name in order to identify which entry in the fr_ippool table to update. The expiry_time is updated based on the configured lease_duration. This update extends the initial lease to the configured lease_duration in case the event that the Accounting Start request was delayed.

  3. The module returns updated to indicate that it was successful in updating the state of the IP address.

  4. After some additional processing (modules, unlang, etc.), FreeRADIUS sends an Accounting-Response to the NAS.

Accounting Interim-Update: A NAS sends an Interim-Update notification for a device’s session

  1. The NAS sends an Accounting Interim-Update request to FreeRADIUS. After some processing (modules. unlang, etc.), the sqlippool module is run.

  2. The sqlippol module runs the update_update query. This query uses the configured requested_address, owner and pool_name in order to identify which entry in the fr_ippool table to update. The expiry_time is updated based on the configured lease_duration.

  3. The module returns updated to indicate that it was successful in updating the state of the IP address.

  4. After some additional processing (modules, unlang, etc.), FreeRADIUS sends an Accounting-Response to the NAS.

Accounting Stop: A device disconnects or its session times out

  1. The NAS sends an Accounting Stop request to FreeRADIUS. After some processing (modules. unlang, etc.), the sqlippool module is run.

  2. The sqlippol module runs the release_clear query. This query uses the configured requested_address, owner and pool_name in order to identify which entry in the fr_ippool table to update. The update "clears" the IP address, and marks it as free for later allocation. Note that by default, this "clear" does removes information about which user or device was associated with that address. The result is that on subsequent allocations, it is not possible to re-allocate the same IP address to the same user or device. If re-allocation of the previous IP address is required, then the query should be amended to not update the value of the owner field.

  3. The module returns updated to indicate that it was successful in updating the state of the IP address.

  4. After some additional processing (modules, unlang, etc.), FreeRADIUS sends an Accounting-Response to the NAS.

Accounting On/Off: A NAS indicates that all of its sessions have been cleared

  1. The NAS sends an Accounting On or Accounting Off request to FreeRADIUS. After some processing (modules. unlang, etc.), the sqlippool module is run.

  2. The sqlippol module runs the bulk_release_clear query. This query uses the configured gateway in order to identify all leases in the fr_ippool table which belong to the NAS in question. The leases are cleared, and the IP addresses are immediately released for further allocation. This process effectively returns all IP address occupied by the dropped sessions back into the pool.

  3. The module returns updated to indicate that it was successful in updating the state of the IP addresses.

  4. After some additional processing (modules, unlang, etc.), FreeRADIUS sends an Accounting-Response to the NAS.