** 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]
-== 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
`/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
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
enable them.
-==== Configure the `dhcp_sql` module
+=== Configure the `dhcp_sql` module
Add the `dhcp_sql` module to the active configuration:
====
-==== Configure the `dhcp_sqlippool` module
+=== Configure the `dhcp_sqlippool` module
Add the `dhcp_sqlippool` module to the active configuration:
`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.
The schema, stored procedure definition and any additional setup scripts for
your database are in `<raddb>/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.
udp 0 0 0.0.0.0%<interface>: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:
-= 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
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]
-== 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.]
-== Configure common reply options
+= Configure Common Reply Options
FreeRADIUS includes a powerful xref:index.adoc[policy language] called
"unlang".
}
----
-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.
-== 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
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
}
----
-=== 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.
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
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
-== 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.
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.
+====
-=== 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
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
-== 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
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
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
-== 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
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
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.
-== 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
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.
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].
-== 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.
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:
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:
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.
[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].
projects / thirdparty / freeradius-server.git / commitdiff
