smart_proxy_dhcp_kea_api 1.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60b69b716ae58881effcacb442e0357e0d92a2b30b4c5be29e24439e07c9e047
-  data.tar.gz: c698f7bdb99f3965eb1f7eb02afe908559b29c2145e3c8870b87038c3552c101
+  metadata.gz: 950a20554504d738a61674a78b9838c3730d4952e56fcd02d87e95242645e898
+  data.tar.gz: 7b1d8c8dfb590d4bcd898aa32204ca04b3a6c06ddbd118b3af0a0241105c36bd
 SHA512:
-  metadata.gz: bd83ca3c705b98af40b57b11b9d9d10386f43277a07884d537eda07f28ef433e3939aeb5d7ab90d351e0f1f429560ea642a9a8ce0b4a98eb60867cb037c6b1e5
-  data.tar.gz: e965386db272058aa1504d089cc69e3e39ada4610a2fe96ff4e2f1a2c5ee7632577430f781e0bffc16239f7243d94f5acb536ef0e6ebcefd0558541b080a018d
+  metadata.gz: 023627a6dcfb40be4e77f83fed7aebb7d96ff7c630105f967baaa4620ea6a1d403f139ecd42aa3a6ca92f92087399c5b515fb58c281da6ae36c8e1cb80bb57b0
+  data.tar.gz: d5b5ca744246290728a63e1a22e72b64a74ebf41e3f3ec9ead6b499e61a6b330f9655cb9d51c80c7381e71d878ccb9e479876103a693f810eff5cfdb352c6a69

data/README.md

@@ -1,38 +1,51 @@
 # Foreman Smart Proxy DHCP Kea API
+
 [![Gem Version](https://badge.fury.io/rb/smart_proxy_dhcp_kea_api.svg)](https://badge.fury.io/rb/smart_proxy_dhcp_kea_api)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 
-A Foreman Smart Proxy plugin to provide DHCP management by interacting with the ISC Kea API. This provider allows Foreman to view subnets and leases and to create and delete host reservations directly via Kea's JSON-RPC interface.
+A Foreman Smart Proxy plugin to provide DHCP management by interacting
+with the ISC Kea API. This provider allows Foreman to view subnets and
+leases and to create and delete host reservations directly via Kea's
+JSON-RPC interface.
 
 > [!NOTE]
 > This plugin currently supports **IPv4 only**.
 
-## Table of Contents
-
 [[_TOC_]]
 
 ## Compatibility
 
-*   **Foreman Smart Proxy:**
-*   **ISC Kea:** 3.0.0 or newer
+* **ISC Kea:** >= 3.0.0
 
 ## Features
 
-- Adds ISC Kea as a DHCP provider for Foreman.
-- Fetches subnet and pool information directly from the Kea API.
-- Fetches active lease information.
-- Provides host reservation management (add/delete).
-- Suggests the next available IP address from a subnet's pool.
-- Passes next-server and PXE boot file to Kea
+* Adds ISC Kea as a DHCP provider for Foreman.
+* Fetches subnet and pool information directly from the Kea API.
+* Fetches active lease information.
+* Provides host reservation management (add/delete).
+* Provides lease deletion via `lease4-del`.
+* Suggests the next available IP address from a subnet's pool.
+* Passes next-server, PXE boot file, DNS servers, NTP servers,
+  and domain-name to Kea.
+* Round-trips reservation options (PXE settings, DNS, routers)
+  so Foreman can pre-fill them on edit.
+* Exposes subnet-level DHCP options (next-server, boot-file-name,
+  DNS, NTP) to Foreman's UI.
+* Automatic cache refresh with configurable TTL.
+* Optional subnet filtering to manage only a subset of Kea's
+  subnets.
 
 ## Prerequisites
 
-- A running Foreman Smart Proxy instance.
-- A running ISC Kea DHCP server.
-- Network connectivity from the Smart Proxy server to the Kea server's API endpoint (default port 8000).
+* A running Foreman Smart Proxy instance.
+* A running ISC Kea DHCP server.
+* Network connectivity from the Smart Proxy server to the Kea
+  server's API endpoint (default port 8000).
 
 > [!WARNING]
-> The Kea server **must** be configured with the **`host_cmds`** and **`lease_cmds`** hook libraries loaded for the `dhcp4` service. This plugin will not function without them.
+> The Kea server **must** be configured with the **`host_cmds`**
+> and **`lease_cmds`** hook libraries loaded for the `dhcp4`
+> service. This plugin will not function without them.
 
 ## Installation
 
@@ -42,31 +55,39 @@ First, install the gem on your Foreman Smart Proxy server:
 gem install smart_proxy_dhcp_kea_api
 ```
 
-Add the gem to `/usr/share/foreman-proxy/bundler.d/Gemfile.local.rb`:
+Register the gem with the Smart Proxy bundler by creating a file
+in `/usr/share/foreman-proxy/bundler.d/`:
 
-```ruby
-gem 'smart_proxy_dhcp_kea_api'
+```bash
+echo "gem 'smart_proxy_dhcp_kea_api'" \
+  > /usr/share/foreman-proxy/bundler.d/dhcp_kea_api.rb
 ```
 
-After installing the gem or changing its configuration, you must restart the `foreman-proxy` service for the changes to take effect.
- ```bash
+Then run `bundle install` and restart the proxy:
+
+```bash
+cd /usr/share/foreman-proxy && bundle install
 systemctl restart foreman-proxy
- ```
+```
 
 ## Configuration
 
-Configuration is done in two files in the `/etc/foreman-proxy/settings.d/` directory.
+Configuration is done in two files in the
+`/etc/foreman-proxy/settings.d/` directory.
 
 ### 1. Enable the DHCP Module
 
-First, you must enable the main DHCP module and tell it to use this plugin as its provider.
+First, enable the main DHCP module and tell it to use this plugin
+as its provider.
 
 **File:** `/etc/foreman-proxy/settings.d/dhcp.yml`
+
 ```yaml
 ---
 :enabled: true
 :use_provider: dhcp_kea_api
-# It is highly recommended to enable the ping check for unused IPs to prevent conflicts.
+# It is highly recommended to enable the ping check for unused
+# IPs to prevent conflicts.
 :ping_free_ip: true
 ```
 
@@ -76,43 +97,74 @@ Next, create a configuration file for the Kea provider itself.
 
 **File:** `/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`
 
-This file enables the provider and contains all the settings needed to connect to your Kea API server.
+This file enables the provider and contains all the settings
+needed to connect to your Kea API server.
+
 
-| Setting                    | Description                                                                  | Default                  | Required |
-| -------------------------- | ---------------------------------------------------------------------------- | ------------------------ | -------- |
-| `:enabled`                 | Enables or disables this provider module.                                    | `false`                  | **Yes**  |
-| `:kea_api_url`             | The full URL to your Kea API endpoint (HTTP or HTTPS).                       | `http://127.0.0.1:8000/` | **Yes**  |
-| `:open_timeout`            | Time in seconds to wait for the initial connection to be established.        | `5`                      | No       |
-| `:read_timeout`            | Time in seconds to wait for a response after connecting.                     | `10`                     | No       |
-| `:blacklist_duration_minutes` | The duration in minutes to temporarily blacklist a suggested IP.             | `5`                      | No       |
+| Setting                       | Default                  | Required | Description                     |
+| ----------------------------- | ------------------------ | -------- | ------------------------------- |
+| `:enabled`                    | `false`                  | **Yes**  | Enables this provider.          |
+| `:kea_api_url`                | `http://127.0.0.1:8000/` | **Yes**  | Kea API endpoint URL.           |
+| `:kea_api_username`           | `nil`                    | No       | HTTP Basic Auth username.       |
+| `:kea_api_password`           | `nil`                    | No       | HTTP Basic Auth password.       |
+| `:open_timeout`               | `5`                      | No       | Connect timeout (seconds).      |
+| `:read_timeout`               | `10`                     | No       | Response timeout (seconds).     |
+| `:blacklist_duration_minutes` | `5`                      | No       | IP blacklist duration (min).    |
+| `:cache_ttl`                  | `60`                     | No       | Cache refresh interval (sec).   |
+| `:managed_subnets`            | `nil`                    | No       | CIDRs to manage (all if unset). |
+
+**Example configuration:**
+
+```yaml
+---
+:enabled: true
+:kea_api_url: http://127.0.0.1:8000/
+:kea_api_username: admin
+:kea_api_password: secret
+:cache_ttl: 120
+:managed_subnets:
+  - 192.168.1.0/24
+  - 10.0.0.0/16
+```
 
 ### Verifying the Installation
 
-The Smart Proxy will test its connection to the Kea API upon initialisation. Due to lazy loading, this check runs **on the first DHCP request** after a proxy restart, not during the initial boot sequence.
+Due to lazy loading, the plugin connects to Kea on the **first
+DHCP request** after a proxy restart, not at boot time.
 
-Check `/var/log/foreman-proxy/proxy.log` for a "Successfully connected to Kea API" message at that time to confirm everything is working. If the connection fails, the first DHCP request will fail with an error in the log, preventing further issues.
+Check `/var/log/foreman-proxy/proxy.log` for messages like
+`Loaded subnet 192.168.x.x/255.255.255.0 and mapped to Kea ID 1`
+to confirm the connection is working. If the connection fails,
+the first DHCP request will return an error and the log will
+contain the details.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on this project's GitLab page.
+Bug reports and pull requests are welcome on this project's
+GitLab page.
 
 ## Licence Information
 
+<!-- markdownlint-disable MD033 -->
+
 <details>
 <summary>Copyright and Licence (GPLv3)</summary>
 
-Copyright © 2025 Sam McCarthy
+Copyright (c) 2025 Sam McCarthy
 
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public Licence as published by
-the Free Software Foundation, either version 3 of the Licence or
-(at your option) any later version.
+This program is free software: you can redistribute it and/or
+modify it under the terms of the GNU General Public Licence as
+published by the Free Software Foundation, either version 3 of
+the Licence or (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 GNU General Public Licence for more details.
 
 You should have received a copy of the GNU General Public Licence
-along with this program.  If not, see <https://www.gnu.org/licenses/>.
-</details>
+along with this program. If not, see
+[https://www.gnu.org/licenses/](https://www.gnu.org/licenses/).
+
+</details>
+<!-- markdownlint-enable MD033 -->

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_main.rb

@@ -8,7 +8,7 @@ module Proxy
     module KeaApi
       # The main provider class for the `dhcp_kea_api` module. This class inherits
       # from the Foreman Smart Proxy's core `DHCP::Server` and implements the
-      # Kea-specific logic for adding and deleting DHCP reservations.
+      # Kea-specific logic for adding and deleting DHCP reservations and leases.
       class Provider < ::Proxy::DHCP::Server
         attr_reader :subnet_service, :client
 
@@ -25,40 +25,9 @@ module Proxy
         end
 
         # Creates a new DHCP reservation in Kea.
-        # This method orchestrates the process by first calling the parent class's
-        # `add_record` to perform initial validation and IP selection, then building
-        # the Kea-specific payload and sending it via the API client.
         #
         # @param options [Hash] A hash containing the details for the new reservation.
-        # @option options [String] 'mac' The hardware address of the host.
-        # @option options [String] 'ip' The IP address to reserve.
-        # @option options [String] 'hostname' The hostname for the reservation.
-        # @option options [Proxy::DHCP::Subnet] :subnet The subnet object this reservation belongs to.
-        # @option options [String, nil] 'nextServer' (optional) The IP of the TFTP boot server.
-        # @option options [String, nil] 'filename' (optional) The boot filename (e.g., 'pxelinux.0').
         # @return [Proxy::DHCP::Reservation] The created reservation object.
-        #
-        # @example Add a new DHCP reservation for a host
-        #   # Assume @provider is an instance of Proxy::DHCP::KeaApi::Provider
-        #   # and 'subnet' is a valid Proxy::DHCP::Subnet object for '192.168.1.0/24'
-        #   options = {
-        #     'mac' => 'aa:bb:cc:dd:ee:ff',
-        #     'hostname' => 'test-host.example.com',
-        #     'ip' => '192.168.1.15',
-        #     subnet: subnet,
-        #     'nextServer' => 'tftp.example.com',
-        #     'filename' => 'pxelinux.0',
-        #     'routers' => ['192.168.1.1'],
-        #     'ntp_servers' => ['192.168.1.254']
-        #   }
-        #
-        #   reservation = @provider.add_record(options)
-        #
-        #   reservation.mac      #=> "aa:bb:cc:dd:ee:ff"
-        #   reservation.ip       #=> "192.168.1.15"
-        #   reservation.name     #=> "test-host.example.com"
-        #   reservation.subnet   #=> #<Proxy::DHCP::Subnet ...>
-        #
         def add_record(options = {})
           logger.debug "DHCP options received from Foreman: #{options.inspect}"
           record = super
@@ -70,43 +39,93 @@ module Proxy
           reservation_args['option-data'] = option_data unless option_data.empty?
 
           @client.post_command('dhcp4', 'reservation-add', { reservation: reservation_args })
-          subnet_service.add_host(record.subnet.network, record)
+          begin
+            subnet_service.add_host(record.subnet.network, record)
+          rescue StandardError => e
+            logger.error "Cache update failed after successful reservation-add for MAC #{record.mac}. " \
+                         "Kea and cache are out of sync: #{e.message}"
+            raise
+          end
 
           logger.info "Successfully added reservation for MAC #{record.mac} and IP #{record.ip}"
           record
         end
 
-        # Deletes a DHCP reservation from Kea.
-        #
-        # @param record [Proxy::DHCP::Reservation] The reservation object to be deleted.
-        #   This object should be retrieved from the subnet service first.
-        # @return [Proxy::DHCP::Reservation] The object that was successfully deleted.
-        # @raise [Proxy::DHCP::Error] if the corresponding Kea subnet-id cannot be found or the API call fails.
+        # Deletes a DHCP record from Kea. Handles both reservations and leases.
         #
-        # @example Delete a known DHCP reservation
-        #   # Assume @provider is an instance of Proxy::DHCP::KeaApi::Provider
-        #   mac_to_delete = 'aa:bb:cc:dd:ee:ff'
+        # @param record [Proxy::DHCP::Reservation, Proxy::DHCP::Lease] The record to be deleted.
+        # @return [Proxy::DHCP::Record] The object that was successfully deleted.
+        # @raise [Proxy::DHCP::Error] if the record type is unsupported, the corresponding
+        #   Kea subnet-id cannot be found, or the API call fails.
+        def del_record(record)
+          logger.debug "Deleting record: #{record.inspect}"
+
+          if record.is_a?(::Proxy::DHCP::Reservation)
+            del_reservation(record)
+          elsif record.is_a?(::Proxy::DHCP::Lease)
+            del_lease(record)
+          else
+            raise Proxy::DHCP::Error, "Cannot delete unsupported record type: #{record.class.name}"
+          end
+
+          record
+        end
+
+        # Loads subnet-level DHCP options from the cached Kea configuration.
         #
-        #   # First, find the reservation object
-        #   record_to_delete = @provider.get_record('mac' => mac_to_delete)
+        # @param subnet [Proxy::DHCP::Subnet] The subnet to load options for.
+        # @return [void]
+        def load_subnet_options(subnet)
+          opts = @subnet_service.subnet_options[subnet.network]
+          return unless opts
+
+          apply_boot_subnet_options(subnet, opts)
+          apply_mapped_subnet_options(subnet, opts)
+        end
+
+        private
+
+        # Applies the boot/server fields, which are top-level Kea config fields
+        # rather than `option-data` entries (so they are not in OPTION_MAP).
         #
-        #   # Now, pass the entire object to del_record
-        #   if record_to_delete
-        #     result = @provider.del_record(record_to_delete)
-        #     #=> #<Proxy::DHCP::Reservation ...>
-        #   end
+        # @param subnet [Proxy::DHCP::Subnet] The subnet to modify.
+        # @param opts [Hash] The cached options hash.
+        # @return [void]
+        def apply_boot_subnet_options(subnet, opts)
+          subnet.options[:nextServer] = opts['next-server'] if opts['next-server']
+          subnet.options[:filename] = opts['boot-file-name'] if opts['boot-file-name']
+        end
+
+        # Applies every `option-data`-derived subnet option using OPTION_MAP as the
+        # single source of truth for the Kea-name -> Foreman-key (and list) mapping.
         #
-        def del_record(record)
-          logger.debug "Deleting record; #{record.inspect}"
-          unless record.is_a?(::Proxy::DHCP::Reservation)
-            logger.warn "Attempted to delete a record for MAC '#{record.mac}' but it is not a Reservation (actual type: #{record.class.name}). No action taken."
-            return record
+        # @param subnet [Proxy::DHCP::Subnet] The subnet to modify.
+        # @param opts [Hash] The cached options hash.
+        # @return [void]
+        def apply_mapped_subnet_options(subnet, opts)
+          SubnetService::OPTION_MAP.each do |kea_name, mapping|
+            value = opts[kea_name]
+            next unless value
+
+            subnet.options[mapping[:key]] = mapping[:list] ? split_option(value) : value
           end
+        end
+
+        # Splits a comma-separated option string into a trimmed array.
+        #
+        # @param value [String] The comma-separated string.
+        # @return [Array<String>] The split and stripped values.
+        def split_option(value)
+          value.split(',').map(&:strip)
+        end
 
-          subnet_id = @subnet_service.kea_id_map[record.subnet.network]
-          raise Proxy::DHCP::Error, "Unable to find Kea subnet-id for network #{record.subnet.network}" unless subnet_id
+        # Deletes a reservation from Kea by MAC address.
+        #
+        # @param record [Proxy::DHCP::Reservation] The reservation to delete.
+        # @return [void]
+        def del_reservation(record)
+          subnet_id = find_subnet_id!(record.subnet.network)
 
-          # Construct the arguments for the 'reservation-del' command using the identifier triplet.
           args = {
             'subnet-id': subnet_id,
             'identifier-type': 'hw-address',
@@ -114,21 +133,59 @@ module Proxy
           }
 
           @client.post_command('dhcp4', 'reservation-del', args)
-          subnet_service.delete_host(record)
+          begin
+            subnet_service.delete_host(record)
+          rescue StandardError => e
+            logger.error "Cache update failed after successful reservation-del for MAC #{record.mac}. " \
+                         "Kea and cache are out of sync: #{e.message}"
+            raise
+          end
 
           logger.info "Successfully deleted reservation for MAC #{record.mac} and IP #{record.ip}"
-          record
         end
 
-        private
+        # Deletes a lease from Kea by IP address.
+        #
+        # @param record [Proxy::DHCP::Lease] The lease to delete.
+        # @return [void]
+        def del_lease(record)
+          subnet_id = find_subnet_id!(record.subnet.network)
+
+          args = {
+            'subnet-id': subnet_id,
+            'ip-address': record.ip
+          }
+
+          @client.post_command('dhcp4', 'lease4-del', args)
+          begin
+            subnet_service.delete_lease(record)
+          rescue StandardError => e
+            logger.error "Cache update failed after successful lease4-del for IP #{record.ip}. " \
+                         "Kea and cache are out of sync: #{e.message}"
+            raise
+          end
+
+          logger.info "Successfully deleted lease for IP #{record.ip}"
+        end
+
+        # Looks up the Kea subnet-id for a network address, raising if not found.
+        #
+        # @param network [String] The subnet network address.
+        # @return [Integer] The Kea subnet-id.
+        # @raise [Proxy::DHCP::Error] if the subnet-id is not in the map.
+        def find_subnet_id!(network)
+          subnet_id = @subnet_service.kea_id_map[network]
+          raise Proxy::DHCP::Error, "Unable to find Kea subnet-id for network #{network}" unless subnet_id
+
+          subnet_id
+        end
 
         # Builds the initial hash of arguments required for a Kea reservation.
         #
         # @param record [Proxy::DHCP::Reservation] The reservation object from the parent class.
         # @return [Hash] A hash containing the base arguments for the Kea API.
         def build_base_reservation_args(record)
-          subnet_id = @subnet_service.kea_id_map[record.subnet.network]
-          raise Proxy::DHCP::Error, "Unable to find Kea subnet-id for network #{record.subnet.network}" unless subnet_id
+          subnet_id = find_subnet_id!(record.subnet.network)
 
           {
             'subnet-id': subnet_id,
@@ -139,16 +196,15 @@ module Proxy
         end
 
         # Adds next-server and boot-file-name options to the reservation arguments hash.
-        # This method modifies the `reservation_args` hash in place.
         #
         # @param reservation_args [Hash] The hash of arguments to be modified.
         # @param options [Hash] The original options hash from Foreman.
         # @return [void]
         def add_boot_and_server_options(reservation_args, options)
-          next_server_value = options[:nextServer]
+          next_server_value = options['nextServer']
           reservation_args[:'next-server'] = resolve_hostname(next_server_value) unless next_server_value.to_s.empty?
 
-          reservation_args[:'boot-file-name'] = options[:filename] unless options[:filename].to_s.empty?
+          reservation_args[:'boot-file-name'] = options['filename'] unless options['filename'].to_s.empty?
         end
 
         # Resolves a hostname to an IP address. If the provided string is already
@@ -165,27 +221,26 @@ module Proxy
           raise Proxy::DHCP::Error, "Could not resolve next-server hostname '#{hostname}': #{e.message}"
         end
 
-        # Builds the array of DHCP options (e.g. routers, ntp-servers) for the reservation.
+        # Builds the array of DHCP options (e.g. routers, ntp-servers, dns-servers) for the reservation.
         #
         # @param options [Hash] The original options hash from Foreman.
         # @return [Array<Hash>] An array of option hashes for the Kea API.
         def build_option_data(options)
           option_data = []
-          add_dhcp_option(option_data, 'routers', options[:routers])
-          add_dhcp_option(option_data, 'ntp-servers', options[:ntp_servers])
-          add_dhcp_option(option_data, 'domain-name', options[:domain_name])
+          SubnetService::OPTION_MAP.each do |kea_name, mapping|
+            add_dhcp_option(option_data, kea_name, options[mapping[:key].to_s])
+          end
           option_data
         end
 
         # A helper to add a DHCP option to the data array if the value exists.
-        # This method modifies the `option_data` array in place.
         #
         # @param option_data [Array<Hash>] The array of options to be modified.
         # @param name [String] The name of the DHCP option (e.g. 'routers').
         # @param value [String, Array] The value of the option.
         # @return [void]
         def add_dhcp_option(option_data, name, value)
-          return if value.to_s.empty?
+          return if value.nil? || (value.respond_to?(:empty?) && value.empty?)
 
           option_data << { name: name, data: Array(value).join(',') }
         end

data/lib/smart_proxy_dhcp_kea_api/dhcp_kea_api_plugin.rb

@@ -21,13 +21,18 @@ module Proxy
         # that the base classes we inherit from (like DHCP::Server) are available.
         requires :dhcp, '>= 1.17'
 
-        # Defines the default settings for this provider. These values are used if
-        # they are not explicitly overridden in a user's settings file
-        # (e.g. `/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`).
+        # Defines the default settings for this provider. These values are used
+        # if they are not overridden in the user's settings file
+        # (`/etc/foreman-proxy/settings.d/dhcp_kea_api.yml`).
+        # The `kea_api_username` and `kea_api_password` enable HTTP Basic
+        # Authentication when the Kea control agent requires it.
         default_settings kea_api_url: 'http://127.0.0.1:8000/',
+                         kea_api_username: nil,
+                         kea_api_password: nil,
                          blacklist_duration_minutes: 5,
                          open_timeout: 5,
-                         read_timeout: 10
+                         read_timeout: 10,
+                         cache_ttl: 60
 
         # Hooks into the Smart Proxy's dependency injection (DI) framework. These lines
         # delegate the responsibility of loading the required classes and wiring up