From: nolade Date: Mon, 21 Apr 2025 21:03:50 +0000 (-0400) Subject: docs: update/copy-edit dhcpv4 pages under >>Howto >> Protocols >> DHCP X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=533c229361e4a475facb80b5c5a720a217c7b08f;p=thirdparty%2Ffreeradius-server.git docs: update/copy-edit dhcpv4 pages under >>Howto >> Protocols >> DHCP --- diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 60c8fd01126..2125da5503d 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -68,15 +68,15 @@ ** xref:protocols/index.adoc[Protocols] *** xref:protocols/dhcp/index.adoc[DHCP] **** xref:protocols/dhcp/prepare.adoc[Preparation] -**** xref:protocols/dhcp/enable.adoc[Enabling the DHCP service] -**** xref:protocols/dhcp/test.adoc[Testing the DHCP service] -**** xref:protocols/dhcp/policy.adoc[Defining the DHCP policy] -***** xref:protocols/dhcp/policy_ippool_creation.adoc[IP pool creation] -***** xref:protocols/dhcp/policy_common_options.adoc[Common options] -***** xref:protocols/dhcp/policy_network_options.adoc[Network options and IP pool selection] -***** xref:protocols/dhcp/policy_subnet_options.adoc[Subnet options] -***** xref:protocols/dhcp/policy_device_options.adoc[Device, class and group options] -***** xref:protocols/dhcp/policy_ippool_access.adoc[IP pool access restriction] +**** xref:protocols/dhcp/enable.adoc[Enable the DHCP Service] +**** xref:protocols/dhcp/test.adoc[Test the DHCP Service] +**** xref:protocols/dhcp/policy.adoc[Define the DHCP Policy] +***** xref:protocols/dhcp/policy_ippool_creation.adoc[IP Pool Creation] +***** xref:protocols/dhcp/policy_common_options.adoc[Common Options] +***** xref:protocols/dhcp/policy_network_options.adoc[Network options and IP Pool Selection] +***** xref:protocols/dhcp/policy_subnet_options.adoc[Subnet Options] +***** xref:protocols/dhcp/policy_device_options.adoc[Device, Class and Group Options] +***** xref:protocols/dhcp/policy_ippool_access.adoc[IP Pool Access Restriction] *** xref:protocols/radius/index.adoc[RADIUS] **** xref:protocols/radius/using_coa.adoc[Using CoA] ***** xref:protocols/radius/coa_examples.adoc[CoA Examples] diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/enable.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/enable.adoc index 2824bd0f482..8d152dc5f8c 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/enable.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/enable.adoc @@ -1,11 +1,6 @@ -== Enabling the DHCP service += Enable the DHCP service -A major difference between configuring FreeRADIUS as a DHCP server versus most -other DHCP software such as ISC DHCP is that other software typically uses a -single monolithic configuration file whereas FreeRADIUS has a collection of -configuration files. This reflects the modularity of FreeRADIUS; attempting to -put the entire configuration in a single file would result in a very difficult -to read configuration. +A major difference between configuring FreeRADIUS as a DHCP server and other DHCP software, such as ISC DHCP, lies in the approach taken by FreeRADIUS. Unlike other software that uses a single, monolithic configuration file, FreeRADIUS has a collection of modular configuration files. Attempting to consolidate the entire configuration into a single file would result in an extremely challenging task. The root of the FreeRADIUS configuration may be in a different location on the filesystem depending on how FreeRADIUS has been installed. This directory will @@ -17,7 +12,7 @@ Pre-built packages will default to either `/etc/raddb` or `/etc/freeradius`. -=== Enable the DHCP virtual server +== Enable the DHCP virtual server The FreeRADIUS configuration separates each network service that it provides into "virtual servers". A number of sample virtual server definitions are @@ -74,7 +69,7 @@ Their contents contain directives in the FreeRADIUS policy language, "unlang". Many examples are provided which have been carefully described. -=== Enable SQL and IP pool modules +== Enable SQL and IP pool modules FreeRADIUS has many modules to support different aspects of the functionality required for the network protocols it can process. The two of most significance @@ -85,7 +80,7 @@ These should be symlinked or copied into `/mods-enabled` in order to enable them. -==== Configure the `dhcp_sql` module +=== Configure the `dhcp_sql` module Add the `dhcp_sql` module to the active configuration: @@ -128,7 +123,7 @@ will be stored. ==== -==== Configure the `dhcp_sqlippool` module +=== Configure the `dhcp_sqlippool` module Add the `dhcp_sqlippool` module to the active configuration: @@ -154,9 +149,9 @@ items are: `lease_duration`:: How long an IP is leased to the client in a DHCP ACK. -=== Provision the database +== Provision the database -You should provision your database by creating a user for FreeRADIUS (matching +Provision your database by creating a user for FreeRADIUS (matching the configuration that you have previously provided) and then loading the schema. The procedure for doing this will vary according to the database server. @@ -164,7 +159,7 @@ server. The schema, stored procedure definition and any additional setup scripts for your database are in `/mods-config/sql/ippool-dhcp/{dialect}/`. -=== Test FreeRADIUS startup +== Test FreeRADIUS startup Once you have provisioned your schema, created a user account and granted access to the user, you should be able to start FreeRADIUS. @@ -180,11 +175,12 @@ designated interface on port 67: udp 0 0 0.0.0.0%:67 ... users:(("radiusd",...)) ================================================================== -Note that if the database is inaccessible then FreeRADIUS will normally refuse -to start. +[NOTE] +==== +If the database is inaccessible then FreeRADIUS will normally refuse +to start. Refer to the xref:ROOT:debugging/radiusd_X.adoc[Debugging] section for more details about startup issues. +==== -The FreeRADIUS wiki contains extensive information about debugging FreeRADIUS -startup issues that we do not repeat in any detail here. Essentially, stop your init system from repeatedly trying to launch FreeRADIUS: diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/index.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/index.adoc index fde22024f03..6b2a0c0c408 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/index.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/index.adoc @@ -1,12 +1,9 @@ -= FreeRADIUS DHCP server += DHCP Server This guide describes how FreeRADIUS can be used in place of ISC DHCP or ISC Kea -to provide a significantly more performant and, above all, more flexible DHCP -server. +to provide a significantly more performant and flexible DHCP server. -This guide provides a suggested configuration that should be somewhat familiar -to anyone who has previously implemented DHCP using the most frequently used -features of other DHCP server software. +The suggested configuration is likely familiar to anyone who’s used DHCP with common features of other DHCP server software. The modular design of FreeRADIUS means that there is no one "right" way to implement the DHCP service. FreeRADIUS allows you to put together a "mix and @@ -17,19 +14,19 @@ code certain DHCP reply parameters within configuration and then look up additional parameters using a datastore such as: * a local file such as a structured text file or an SQLite database - * an organisational LDAP directory + * an organizational LDAP directory * an SQL or "no SQL" database * a remote endpoint such as a RESTful HTTP API The policy language and modular configuration of FreeRADIUS is sufficiently -powerful and that almost any aspect of the server's behaviour can be customised +powerful and that almost any aspect of the server's behaviour can be customized to implement even the most sophisticated DHCP configurations. == Sections in this guide -This guide is organised into four parts that should be read in order: +This guide is organized into four sections and we recommend to review each one in the following order: 1. xref:protocols/dhcp/prepare.adoc[Preparation] -2. xref:protocols/dhcp/enable.adoc[Enabling the DHCP service] -3. xref:protocols/dhcp/test.adoc[Testing the DHCP service] -4. xref:protocols/dhcp/policy.adoc[Defining the DHCP policy] +2. xref:protocols/dhcp/enable.adoc[Enable the DHCP service] +3. xref:protocols/dhcp/test.adoc[Test the DHCP service] +4. xref:protocols/dhcp/policy.adoc[Define the DHCP policy] diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy.adoc index d8f1bcb79a9..7a82dbceffd 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy.adoc @@ -1,14 +1,13 @@ -== Defining the DHCP policy += Define the DHCP policy Now that FreeRADIUS is successfully running as a DHCP server it is necessary to -configure a DHCP policy so that it returns correctly formed responses to the DHCP -requests that it receives. +configure a DHCP policy so that it returns correctly formed responses to the DHCP requests that it receives. This involves a number of steps: - * xref:protocols/dhcp/policy_ippool_creation.adoc[Defining the IP address pools.] - * xref:protocols/dhcp/policy_common_options.adoc[Defining the options that are common to all replies.] - * xref:protocols/dhcp/policy_network_options.adoc[Defining the options for the network from which the request originates and ensuring that IP addresses are allocated from the correct pool.] - * xref:protocols/dhcp/policy_subnet_options.adoc[Defining the options for the subnet to which this issued IP address belongs.] - * xref:protocols/dhcp/policy_device_options.adoc[Defining the device, class and group based options specific to the device.] - * xref:protocols/dhcp/policy_ippool_access.adoc[Using device properties to restrict access to certain pools.] + * xref:protocols/dhcp/policy_ippool_creation.adoc[Define the IP address pools.] + * xref:protocols/dhcp/policy_common_options.adoc[Define the options that are common to all replies.] + * xref:protocols/dhcp/policy_network_options.adoc[Define the options for the network from which the request originates and ensuring that IP addresses are allocated from the correct pool.] + * xref:protocols/dhcp/policy_subnet_options.adoc[Define the options for the subnet to which this issued IP address belongs.] + * xref:protocols/dhcp/policy_device_options.adoc[Define the device, class and group based options specific to the device.] + * xref:protocols/dhcp/policy_ippool_access.adoc[Configure device properties to restrict access to certain pools.] diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc index 9fd7aaf530a..a1c132f2de4 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_common_options.adoc @@ -1,4 +1,4 @@ -== Configure common reply options += Configure Common Reply Options FreeRADIUS includes a powerful xref:index.adoc[policy language] called "unlang". @@ -40,7 +40,7 @@ dhcp_common { } ---- -Note, FreeRADIUS has four main operators for assigning values to attributes: +FreeRADIUS has four main operators for assigning values to attributes: `=`:: Add the attribute to the list, if and only if an attribute of the same name is not already present in that list. diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_device_options.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_device_options.adoc index a5c95be57c7..17bcf220331 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_device_options.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_device_options.adoc @@ -1,4 +1,4 @@ -== Configure "device", "class" and "group" options += Configure "device", "class" and "group" options Beyond the global, network and subnet options already described, most sites will have a number of group or class based options, and have a requirement for @@ -25,7 +25,7 @@ options. We describe some of these options in more detail. -=== Directly in Policy +== Directly in Policy Simple class options can be written directly into policy. This is most suited to those options that rarely change and are based on attributes in the @@ -104,7 +104,7 @@ if (DHCP-Client-Identifier && \ } ---- -=== In Text Files +== In Text Files The `files` module that has already been described for global, network and subnet options can also be used to apply options to groups of clients. @@ -148,7 +148,7 @@ group2 DHCP-LPR-Server := 192.168.20.200 ---- -=== In the SQL Database +== In the SQL Database Policy and files are both read during startup and editing them while FreeRADIUS is running will not result in any changes in behaviour. If @@ -276,7 +276,7 @@ dhcp_sql.authorize The file `policy.d/dhcp` contains a policy named `dhcp_policy_sql` which provides further worked examples for different types of option lookups. -=== Testing "device", "class" and "group" options +== Test "device", "class" and "group" options You should now test that any device-related options that you have configured using the various methods available are applied successfully by generating diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_access.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_access.adoc index 40b8e3094a3..061bc104c9d 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_access.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_access.adoc @@ -1,4 +1,4 @@ -== Configure access restrictions for pools += Configure Access Restrictions for Pools We can combine what we have learned in the preceeding sections to provide pools whose access is restricted in some way, for example to a particular class. @@ -50,5 +50,8 @@ network DHCP-Network-Subnet < 10.99.99.0/24, \ DHCP-Router-Address := 10.99.99.1 ---- -Note that any number of additional filters can be added to the initial "check" +[NOTE] +==== +Any number of additional filters can be added to the initial "check" line to restrict matches to the network block. +==== diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_creation.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_creation.adoc index e976873c12f..618747734c2 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_creation.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_ippool_creation.adoc @@ -1,4 +1,4 @@ -=== Determine the IP pool plan += Determine the IP Pool Plan Except for cases where all IP allocation is performed using a mapping from the device MAC address to a fixed IP address, the DHCP configuration will involve @@ -46,7 +46,7 @@ more granularity that their Layer 2 network, such as by considering device attributes ("class" membership in ISC parlance) or Option 82 circuit data. -=== Populate the IP Pools +== Populate the IP Pools By this stage you should have derived a list of pools, the IP address ranges contained therein, and the means of selecting the pool to use based on the diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_network_options.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_network_options.adoc index e2657a8cfee..06aeab05b84 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_network_options.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_network_options.adoc @@ -1,4 +1,4 @@ -== Configure network-specific options and IP pool selection += Configure Network-Specific Options and IP Pool Selection In an environment where multiple networks (often VLANs) are in use, it is necessary to identify which network a client belongs to in order to assign an @@ -147,7 +147,7 @@ with a key of `network` and no further filtering, so `Fall-Through` is set on that record in order that the other records will be tested to find subnet matches. -=== Example packet processing +== Example packet processing For our example, we consider a request arriving from a DHCP relay within 10.10.0.0/16. In the absence of any specific DHCP subnet selection options in @@ -172,7 +172,7 @@ allocation. The assigned IP address and network parameters will subsequently be returned in the DHCP reply. -=== Testing the pool operation and network-specific options +== Testing the pool operation and network-specific options Before proceeding further, you should test the operation of the IP pools and ensure that any network-specific reply attributes that you have configured are diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/policy_subnet_options.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/policy_subnet_options.adoc index 1980e89cd0c..b2569ac1b6d 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/policy_subnet_options.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/policy_subnet_options.adoc @@ -1,4 +1,4 @@ -== Configure subnet-specific options for shared networks += Configure Subnet-Specific Options for Shared Networks In the case that shared-networks are in use, with the pool containing equally-valid IP addresses from multiple subnets, it is necessary to set the @@ -101,7 +101,7 @@ subnet DHCP-Network-Subnet < 10.30.20.0/24 DHCP-Router-Address := 10.30.20.1 ---- -=== Example packet processing +== Example packet processing For our example, we consider a request arriving from a DHCP relay within 10.30.10.0/24. In the absence of any specific DHCP subnet selection options in @@ -135,7 +135,7 @@ the pool name and network options. The assigned IP address, network and subnet parameters will subsequently be returned in the DHCP reply. -=== Testing the subnet-specific options +== Testing the subnet-specific options If you have set any subnet-specific reply parameters then you should test these before proceeding further. diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/prepare.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/prepare.adoc index aa43530a66d..f4a6c2c1fa6 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/prepare.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/prepare.adoc @@ -1,9 +1,9 @@ -== Preparation += Preparation It is necessary to consider the requirements for the installation in order to devise an efficient and manageable set up. -=== Understand the network topology +== Understand the network topology When multiple networks (VLANs) are in use consideration must be given to how the correct "pool" (IP address ranges) from which to allocate addresses is @@ -16,11 +16,11 @@ requests or determined by dynamic lookup, should be well defined and understood. Other DHCP servers may implement implicit assumptions about the requirement of -your network topology and silently define particular behaviours, such as the +your network topology and silently define particular behaviors, such as the selection of IP address pool for a request based on a relay address. Some of -these behaviours must be specifed explicitly when using FreeRADIUS. +these behaviors must be specifed explicitly when using FreeRADIUS. -=== Choose a database backend +== Choose a database backend FreeRADIUS stores its leases in an SQL database, so one of the key decisions to make is which database to use. @@ -53,7 +53,7 @@ familiarity and your need for commercial support. FreeRADIUS ships with a default database schema and set of queries for each supported database. These are sufficient for most DHCP deployments but can be reviewed and modified as required to suit a particular situation, for example -to customise the IP allocation policy such as by disabling address +to customize the IP allocation policy such as by disabling address "stickiness". Now xref:protocols/dhcp/enable.adoc[enable the DHCP service]. diff --git a/doc/antora/modules/howto/pages/protocols/dhcp/test.adoc b/doc/antora/modules/howto/pages/protocols/dhcp/test.adoc index c9783562861..619f374722d 100644 --- a/doc/antora/modules/howto/pages/protocols/dhcp/test.adoc +++ b/doc/antora/modules/howto/pages/protocols/dhcp/test.adoc @@ -1,4 +1,4 @@ -== Testing the DHCP service += Test the DHCP Service We can verify that FreeRADIUS is providing a DHCP service using the `dhcpclient` tool that is included with the FreeRADIUS distribution. @@ -25,8 +25,8 @@ DHCP-Client-Identifier := abc123 EOF ---- -We can now generate this packet by invoking one of the following commands based -on the current circumstances... +We can generate this packet by invoking one of the following commands based +on the current circumstances. From the host that is running the FreeRADIUS DHCP server: @@ -60,7 +60,7 @@ address on the interface used by the dhcpclient tool to send the Discover packet. ==== -When one of the above commands is run, the tool with generate output such as +When one of the above commands is run, the tool generates output such as the following which shows that the packet was sent and that it is now waiting for replies: @@ -113,7 +113,7 @@ Each received DHCP response will generate output such as the following: Examine the DHCP response to ensure that it has the correct message type (`DHCP-Offer`, in this case), contains the temporary IP address that you configured earlier, i.e. `DHCP-Your-IP-Address = 1.2.3.4`, and any other -expected reply parameters (which we configure later). You should also carefully +expected reply parameters (which we configure later). Carefully examine the output of a FreeRADIUS debug session (`radius -X`) to ensure that the policy is being executed in the way that you expect and that no warnings are being generated. @@ -126,18 +126,12 @@ DHCP parameters ("attributes") understood by FreeRADIUS. [WARNING] ==== -When you are done **remember** to remove the temporary edit that was made to -the `dhcp` virtual server that provides the static IP assignment. +When you are done testing, **remember** to remove the temporary edit that was made to the `dhcp` virtual server that provides the static IP assignment. ==== -=== Testing the DHCP policy +== Testing the DHCP policy The remainder of this guide describes how to configure the IP address plan, -setup the IP pools and define a DHCP policy. You should develop your policy by -making small, incremental changes to the provided configuration and then test -those changes with the approach described above, using `dhcpclient` and `radius -X`, -modifying the sample DHCP packet as required. If you break the policy then -revert the last change, attempt to understand what went wrong, and try -something else. +setup the IP pools and define a DHCP policy. It's recommended to develop your policy by making small, incremental changes to the provided configuration and then test those changes with the approach described above, using `dhcpclient` and `radius -X`, modifying the sample DHCP packet as required. If you break the policy then revert the last change, attempt to understand what went wrong, and try something else. Now xref:protocols/dhcp/policy.adoc[define the DHCP policy].