Skip to content

IMPLEMENTATION.md

Latest commit

 

History

History
420 lines (353 loc) · 14.7 KB

IMPLEMENTATION.md

File metadata and controls

420 lines (353 loc) · 14.7 KB
Raw

NetBox DHCP KEA Plugin - Implementation Summary

Overview

This NetBox plugin provides comprehensive management for ISC KEA DHCP server configurations, including servers, DHCP options, client classification, and integration with NetBox Prefixes.

Implemented Components

1. Data Models (models.py)

DHCPServer

  • Manages DHCP server instances
  • Fields: name, description, ip_address, status, service_template
  • Used to identify DHCP servers in your infrastructure

VendorOptionSpace

  • Defines vendor-specific option spaces with enterprise IDs
  • Fields: name, enterprise_id, manufacturer, description

OptionDefinition

  • Defines DHCP option definitions (KEA option-def)
  • Fields: name, code, option_type, option_space, vendor_option_space, is_array, encapsulate, record_types, description
  • Supports both standard (RFC-defined) and custom options

OptionData

  • Configures DHCP option values (KEA option-data)
  • Fields: distinctive_name, definition, option_space, vendor_option_space, delivery_type, data, always_send, csv_format, description
  • Many-to-many relationships with ClientClass, Subnet, and SubnetPool

ClientClass

  • Configures client classification rules
  • Fields: name, test_expression, description, only_in_additional_list, next_server, server_hostname, boot_file_name
  • Many-to-many relationship with OptionData
  • Supports KEA test expressions for client matching

Subnet

  • Links NetBox Prefixes to DHCP configurations (KEA subnet)
  • Fields: prefix (OneToOne), server, valid_lifetime, max_lifetime, routers_option_offset
  • Many-to-many relationships with OptionData and ClientClass
  • Validates that max_lifetime >= valid_lifetime
  • Calculates pools from child IP Ranges or available IPs
  • Computes reservations from assigned IP addresses within the prefix

SubnetPool

  • Pool-level DHCP configuration for a Subnet's IP Range
  • Fields: subnet, ip_range (OneToOne), client_class, description
  • Many-to-many relationships with evaluate_additional_classes (ClientClass) and option_data (OptionData)
  • Annotates NetBox IPRanges with KEA pool-level settings (client-class, evaluate-additional-classes, option-data)

DHCPHARelationship

  • Manages High Availability relationships between DHCP servers
  • Fields: name, description, mode (hot-standby/load-balancing/passive-backup), heartbeat_delay, max_response_delay, etc.
  • Contains multiple DHCPServer entries defining the HA cluster
  • Helper methods: get_primary_server(), get_synced_*_count(), migrate_configs_to_new_primary()

Hook

  • Defines KEA hook libraries
  • Fields: name, library_name, description, is_standard, allowed_processes, parameters
  • Supports both standard KEA hooks and custom hook libraries

HookGroup

  • Groups hooks together for assignment to DHCP servers
  • Fields: name, description, library_path
  • Many-to-many relationships with Hook and DHCPServer

2. Forms (forms.py)

  • DHCPServerForm: Full CRUD for DHCP servers with HA-aware configuration
  • VendorOptionSpaceForm: Full CRUD for vendor option spaces
  • OptionDefinitionForm: Full CRUD for option definitions
  • OptionDataForm: Full CRUD for option data values
  • ClientClassForm: Includes dynamic multi-select for options and servers
  • SubnetForm: Dynamic selects for prefix, server, options, and client classes
  • SubnetPoolForm: Pool-level configuration with validation against parent subnet
  • DHCPHARelationshipForm: HA relationship configuration
  • HookForm: Hook library configuration with process filtering
  • HookGroupForm: Hook group management

3. Tables (tables.py)

  • DHCPServerTable: Displays servers with status
  • VendorOptionSpaceTable: Shows vendor option spaces
  • OptionDefinitionTable: Shows option definitions with code, type, and space
  • OptionDataTable: Shows option data with definition details
  • ClientClassTable: Lists classes with test expressions
  • SubnetTable: Shows prefix-to-server mappings with pool counts
  • SubnetPoolTable: Shows pool configurations with client class and option counts
  • DHCPHARelationshipTable: Displays HA relationships
  • HookTable: Shows hook libraries with allowed processes
  • HookGroupTable: Shows hook groups

4. Views (views.py)

Standard NetBox views for each model:

  • ObjectView: Detail view
  • ObjectListView: List/table view
  • ObjectEditView: Create/update form
  • ObjectDeleteView: Deletion confirmation

Additional tab views:

  • SubnetPoolsView: Pools tab on Subnet detail showing IP Range pools and their configuration
  • SubnetReservationsView: Reservations tab on Subnet detail showing DHCP reservations
  • DHCPServerPrefixesView: Prefixes tab on DHCP Server detail
  • DHCPServerKeaConfigView: KEA Config tab showing generated JSON

5. URL Routing (urls.py)

Complete URL patterns for all models:

  • /plugins/netbox-dhcp-kea-plugin/dhcp-servers/
  • /plugins/netbox-dhcp-kea-plugin/vendor-option-spaces/
  • /plugins/netbox-dhcp-kea-plugin/option-definitions/
  • /plugins/netbox-dhcp-kea-plugin/option-data/
  • /plugins/netbox-dhcp-kea-plugin/client-classes/
  • /plugins/netbox-dhcp-kea-plugin/subnets/
  • /plugins/netbox-dhcp-kea-plugin/subnet-pools/
  • /plugins/netbox-dhcp-kea-plugin/ha-relationships/
  • /plugins/netbox-dhcp-kea-plugin/hooks/
  • /plugins/netbox-dhcp-kea-plugin/hook-groups/

Each with list, add, detail, edit, delete, and changelog views.

6. Navigation (navigation.py)

Plugin menu with configurable structure (top-level or under Plugins submenu):

Server Configuration

  • DHCP Servers
  • Subnets
  • Client Classes

High Availability

  • HA Relationships

Hook Libraries

  • Hooks
  • Hook Groups

Option Definition

  • Option Definitions
  • Option Data
  • Vendor Option Spaces

Each menu item includes an "Add" button with proper permissions.

7. REST API (api/)

Complete REST API implementation:

Serializers (api/serializers.py)

  • DHCPServerSerializer
  • VendorOptionSpaceSerializer
  • OptionDefinitionSerializer
  • OptionDataSerializer
  • ClientClassSerializer
  • SubnetSerializer
  • SubnetPoolSerializer
  • DHCPHARelationshipSerializer
  • HookSerializer
  • HookGroupSerializer

All include proper relationships and nested serializers.

ViewSets (api/views.py)

  • DHCPServerViewSet (with kea-config action)
  • VendorOptionSpaceViewSet
  • OptionDefinitionViewSet
  • OptionDataViewSet
  • ClientClassViewSet
  • SubnetViewSet (with pools and relay-config actions)
  • SubnetPoolViewSet
  • DHCPHARelationshipViewSet
  • HookViewSet
  • HookGroupViewSet
  • PrefixRelayConfigView (standalone API view for prefix-based relay lookup)

With optimized querysets using select_related and prefetch_related.

API URLs (api/urls.py)

  • /api/plugins/netbox-dhcp-kea-plugin/dhcp-servers/
  • /api/plugins/netbox-dhcp-kea-plugin/dhcp-servers/{id}/kea-config/
  • /api/plugins/netbox-dhcp-kea-plugin/vendor-option-spaces/
  • /api/plugins/netbox-dhcp-kea-plugin/option-definitions/
  • /api/plugins/netbox-dhcp-kea-plugin/option-data/
  • /api/plugins/netbox-dhcp-kea-plugin/client-classes/
  • /api/plugins/netbox-dhcp-kea-plugin/subnets/
  • /api/plugins/netbox-dhcp-kea-plugin/subnets/{id}/pools/
  • /api/plugins/netbox-dhcp-kea-plugin/subnets/{id}/relay-config/
  • /api/plugins/netbox-dhcp-kea-plugin/subnet-pools/
  • /api/plugins/netbox-dhcp-kea-plugin/ha-relationships/
  • /api/plugins/netbox-dhcp-kea-plugin/hooks/
  • /api/plugins/netbox-dhcp-kea-plugin/hook-groups/
  • /api/plugins/netbox-dhcp-kea-plugin/relay-config/?prefix=X

8. Template Extension (template_content.py)

PrefixDHCPInfo - Injects DHCP configuration into Prefix detail pages:

  • Displays in right column of Prefix detail view
  • Shows server, lifetimes, router IP
  • Lists associated option data
  • Lists client class assignments
  • Provides edit link to configuration

9. Templates

Detail View Templates

  • dhcpserver.html: Server details with KEA config preview
  • vendoroptionspace.html: Vendor option space details
  • optiondefinition.html: Option definition details
  • optiondata.html: Option data details with definition info
  • clientclass.html: Class details with test expression and options
  • subnet.html: Subnet configuration details with all relationships
  • subnetpool.html: Pool detail page with KEA JSON preview
  • dhcpharelationship.html: HA relationship details
  • hook.html: Hook library details
  • hookgroup.html: Hook group details

Tab Templates

  • subnet_pools.html: Pools tab showing IP ranges and configured pool settings
  • subnet_reservations.html: Reservations tab showing DHCP reservations
  • dhcpserver_prefixes.html: Prefixes tab on server detail
  • dhcpserver_kea_config.html: KEA config output tab

Injection Template

  • inc/prefix_dhcp_panel.html: DHCP info panel for IPAM Prefix views

10. Filter Sets (filtersets.py)

  • DHCPServerFilterSet: Filter by HA relationship, HA role
  • VendorOptionSpaceFilterSet: Filter by name, enterprise ID, manufacturer
  • OptionDefinitionFilterSet: Filter by standard/custom, vendor space, option space, type
  • OptionDataFilterSet: Filter by definition, vendor space, delivery type
  • ClientClassFilterSet: Filter by only_in_additional_list
  • SubnetFilterSet: Filter by server
  • SubnetPoolFilterSet: Filter by subnet, client class
  • DHCPHARelationshipFilterSet: Filter by mode
  • HookFilterSet: Filter by standard, allowed processes
  • HookGroupFilterSet: Filter by hooks, servers

Features

Core Functionality

✅ DHCP server management ✅ Vendor option space definitions ✅ DHCP option definitions (KEA option-def) ✅ DHCP option data/values (KEA option-data) ✅ Client classification with test expressions ✅ Link prefixes to DHCP configurations (Subnets) ✅ Pool-level configuration (SubnetPool) with client classes and option data ✅ Lease lifetime management ✅ Many-to-many relationships (options, classes) ✅ Hook library management

High Availability (HA) Support

✅ HA relationship management (hot-standby, load-balancing, passive-backup) ✅ Server role definitions (primary, secondary, standby, backup) ✅ Automatic config sync from primary to all HA peers ✅ HA-aware KEA config generation via to_kea_dict() ✅ Protection against orphaned configs (primary deletion/role change blocked) ✅ Config migration helper for switching primary servers ✅ UI hides config management for non-primary servers ✅ Auto-redirect form submissions to primary server

NetBox Integration

✅ Extends NetBox Prefix model ✅ Injects DHCP info into Prefix detail pages ✅ Uses NetBoxModel base class ✅ Full tag support ✅ Change logging/audit trail ✅ Custom field support

API

✅ REST API for all models ✅ Nested serializers for relationships ✅ Optimized database queries ✅ Standard NetBox API patterns ✅ KEA config generation endpoint ✅ Relay config lookup by prefix

UI/UX

✅ Navigation menu integration ✅ List/detail/edit/delete views ✅ Dynamic form fields ✅ Related object linking ✅ Responsive tables ✅ Subnet Pools and Reservations tabs

Database Schema

DHCPServer
├── Subnet (many)
│   ├── Prefix (one-to-one)
│   ├── OptionData (many-to-many)
│   ├── ClientClass (many-to-many)
│   │   └── OptionData (many-to-many)
│   └── SubnetPool (many)
│       ├── IPRange (one-to-one)
│       ├── ClientClass (foreign key, optional)
│       ├── ClientClass (many-to-many, evaluate_additional_classes)
│       └── OptionData (many-to-many)
├── OptionData (many-to-many, server-level)
├── HookGroup (foreign key, optional)
│   └── Hook (many-to-many)
└── DHCPHARelationship (foreign key, optional)
    └── DHCPServer (many)

Usage Example

from netbox_dhcp_kea_plugin.models import (
    Subnet, SubnetPool, DHCPServer, OptionDefinition, OptionData, ClientClass
)

# Create infrastructure
server = DHCPServer.objects.create(
    name="kea-dhcp-01",
    ip_address=ip_address,  # IPAddress object from NetBox IPAM
    status="active",
    service_template=service_template,
)

# Define option definition
dns_def = OptionDefinition.objects.create(
    name="domain-name-servers",
    code=6,
    option_type="ipv4-address",
    option_space="dhcp4",
    is_standard=True,
)

# Create option data
dns_option = OptionData.objects.create(
    distinctive_name="DNS Servers",
    definition=dns_def,
    data="8.8.8.8, 8.8.4.4",
)

# Create client class
guest_class = ClientClass.objects.create(
    name="guest-devices",
    test_expression="substring(hardware,1,3) == 0xaabbcc",
)
guest_class.option_data.add(dns_option)

# Configure subnet
prefix = Prefix.objects.get(prefix="192.168.1.0/24")
subnet = Subnet.objects.create(
    prefix=prefix,
    server=server,
    valid_lifetime=3600,
    max_lifetime=7200,
    routers_option_offset=1,
)
subnet.option_data.add(dns_option)
subnet.client_classes.add(guest_class)

# Optionally configure pool-level settings
ip_range = IPRange.objects.get(start_address="192.168.1.100/24", end_address="192.168.1.200/24")
pool = SubnetPool.objects.create(
    subnet=subnet,
    ip_range=ip_range,
    client_class=guest_class,
    description="Guest pool",
)
pool.option_data.add(dns_option)

Next Steps

To use this plugin:

  1. Run migrations: python manage.py migrate
  2. Access via NetBox UI: Plugins > DHCP Servers/Subnets/etc.
  3. View DHCP info on Prefix detail pages
  4. Use REST API for automation
  5. Export configurations for KEA deployment

File Structure

netbox_dhcp_kea_plugin/
├── __init__.py                 # Plugin configuration
├── models.py                   # Data models
├── forms.py                    # Django forms
├── tables.py                   # Display tables
├── views.py                    # View classes
├── urls.py                     # URL routing
├── navigation.py               # Menu items
├── template_content.py         # Template extensions
├── filtersets.py               # Query filters
├── api/
│   ├── __init__.py
│   ├── serializers.py          # API serializers
│   ├── views.py                # API viewsets
│   └── urls.py                 # API routing
├── management/
│   └── commands/
│       └── generate_kea_demo_data.py
└── templates/
    └── netbox_dhcp_kea_plugin/
        ├── subnet.html
        ├── subnet_pools.html
        ├── subnet_reservations.html
        ├── subnetpool.html
        ├── dhcpserver.html
        ├── dhcpserver_prefixes.html
        ├── dhcpserver_kea_config.html
        ├── optiondata.html
        ├── optiondefinition.html
        ├── clientclass.html
        ├── clientclass_prefixes.html
        ├── clientclass_servers.html
        ├── vendoroptionspace.html
        ├── dhcpharelationship.html
        ├── hook.html
        ├── hookgroup.html
        └── inc/
            └── prefix_dhcp_panel.html