Products‎ > ‎Jagornet DHCP Server‎ > ‎

Documentation

Jagornet DHCP Server User Guide - Community Edition v2.0.5

A. Gregory Rabil

Copyright © 2016 Jagornet Technologies, LLC

07/06/2016


Chapter 1. Introduction

Table of Contents

Welcome
Features

Welcome

Welcome to Jagornet DHCP Server Community Edition Version 2.0.5. Please visit these links for the latest news and information on Jagornet DHCP Server.

Features

Jagornet DHCP Server is an open source Dynamic Host Configuration Protocol server for IPv6 (DHCPv6) and IPv4 (DHCPv4) implemented in Java. The server supports the following features:

Chapter 2. Getting Started

System requirements

Jagornet DHCP Server requires any platform with a certified Java 6 runtime environment.

The server has been successfully tested on multiple flavors of Linux (including RHEL/CentOS, Ubuntu), Solaris, and Windows (including XP SP2, 2003, 7, 2008) using the Sun/Oracle JRE6 for the respective platforms. The server has also been successfully tested on OS X 10.x running Apple's Java 6 runtime and FreeBSD running the OpenJDK 6 runtime.

Installation

Java 6 runtime must be available on the host where the Jagornet DHCP server will be installed. The JAVA_HOME environment variable should be set to the home directory of your Java 6 JRE.

  1. Create the installation directory on the host system and expand the compressed installation file for your target platform.

    • Linux/Unix/Mac

      • Installation folder: /opt/jagornet

      • Compressed install file: jagornet-dhcpserver-2.0.5.tar.gz

      • JAGORNET_DHCP_HOME=/opt/jagornet/jagornet-dhcpserver-2.0.5

    • Windows

      • Installation folder: C:\jagornet

      • Compressed install file: jagornet-dhcpserver-2.0.5.zip

      • JAGORNET_DHCP_HOME=C:\jagornet\jagornet-dhcpserver-2.0.5

  2. After extracting the compressed files, a jagornet-dhcpserver-2.0.5 directory will be created in the installation folder, with the following contents.

    • JAGORNET_DHCP_HOME/bin - executable command line files. See the section on Running the Server.

    • JAGORNET_DHCP_HOME/conf - configuration files. See the section on Configuration.

    • JAGORNET_DHCP_HOME/db - database directory. See the section on Binding Database.

    • JAGORNET_DHCP_HOME/docs - documentation files.

    • JAGORNET_DHCP_HOME/lib - Java library files.

    • JAGORNET_DHCP_HOME/log - server output files. See the section on Logging.

Running the Server

Note

To start the Jagornet DHCP Server, you must have superuser or administrator access rights on the host system because the server must bind to privileged port numbers 67 for DHCPv4 and 547 for DHCPv6 to service client requests. Optionally, the server can be instructed to bind to a different port numbers for testing purposes only. See the Startup Options for more information.

Please also note that your host system's firewall must be configured to enable inbound and outbound traffic for the UDP ports of the DHCPv4 and DHCPv6 server.

Startup Options

The main Java class of the Jagornet DHCP Server supports the following usage:

usage: com.jagornet.dhcp.server.JagornetDhcpServer [options]
Jagornet DHCP Server Community Edition 2.0.5
Copyright Jagornet Technologies, LLC 2009-2016.  All Rights Reserved.  
-4b,--v4bcast <interface>         DHCPv4 broadcast support (default = none).
                                    Use this option to specify the interface for
                                    the server to receive and send broadcast
                                    DHCPv4 packets. Only one interface may be
                                    specified. All other interfaces on the host
                                    will only receive and send unicast traffic.
                                    The default IPv4 address on the specified
                                    interface will be used for determining the
                                    DHCPv4 client link within the server
                                    configuration file.
-4p,--v4port <portnum>            DHCPv4 Port number (default = 67).
-4u,--v4ucast <addresses>         DHCPv4 Unicast addresses (default = all IPv4
                                    addresses). Use this option to instruct the
                                    server to bind to a specific list of IPv4
                                    addresses, separated by spaces. These
                                    addresses should be configured on one or
                                    more DHCPv4 relay agents connected to DHCPv4
                                    client links.
-6m,--v6mcast <interfaces>        DHCPv6 Multicast support (default = none).
                                    Use this option without arguments to
                                    instruct the server to bind to all
                                    multicast-enabled IPv6 interfaces on the
                                    host. Optionally, use arguments to list
                                    specific interfaces, separated by spaces.
-6p,--v6port <portnum>            DHCPv6 Port number (default = 547).
-6u,--v6ucast <addresses>         DHCPv6 Unicast addresses (default = all IPv6
                                    addresses). Use this option to instruct the
                                    server to bind to a specific list of global
                                    IPv6 addresses, separated by spaces. These
                                    addresses should be configured on one or
                                    more DHCPv6 relay agents connected to DHCPv6
                                    client links.
-?,--help                         Show this help page.
-c,--configfile <filename>        Configuration file (default = 
                                    $JAGORNET_DHCP_HOME/conf/dhcpserver.xml).
-li,--list-interfaces             Show detailed host interface list, then
                                    exit.
-tc,--test-configfile <filename>  Test configuration file, then exit.
-v,--version                      Show version information, then exit.

Note

Users should NOT directly invoke the main Java class, but are encouraged to use the wrapper scripts which ensure the proper environment, classpath and Java VM arguments. See the following sections for Linux/Unix/Mac or Windows host systems.

Linux/Unix/Mac

The $JAGORNET_DHCP_HOME/bin/dhcpserver script can be used to operate the server from a command shell. This script supports the following options:

  • start [startup options] - starts the server with any startup options provided.

  • stop - stops the server.

  • restart [startup options] - stop and start the server.

  • status - check if the server is running.

  • version - display server version and exit.  A convenience option which can be used instead of 'start -v' or 'start --version'.

  • test-configfile <configfile> - test server configuration file and exit. A convenience option instead of 'start -tc <filename>' or 'start --test-configfile <filename>'.

  • list-interfaces - list host interfaces and exit. A convenience method instead of 'start -li' or 'start --list-interfaces'.

Startup examples:

  1. Display the server version and exit (any of the following):

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver version

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start -v

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start --version

  2. Start the server with the default options (DHCPv6 unicast on all interfaces, no DHCPv6 multicast, DHCPv4 unicast on all interfaces, no DHCPv4 broadcast):

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start

  3. Start the server on a test port with support for multicast on all IPv6 multicast-enabled interfaces:

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start -6p 10547 -6m

  4. Start the server with support for DHCPv6 multicast on the interface named 'eth0' and DHCPv4 broadcast on the interface named 'eth1':

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start -6m eth0 -4b eth1

  5. Start the server with an alternate configuration file, one specific unicast address, and two specific multicast interfaces:

    • > $JAGORNET_DHCP_HOME/bin/dhcpserver start -c conf/my-dhcpserver.xml -6u 2001:db8::1 -6m eth0 eth1

Windows

Windows Service

Jagornet DHCP Server can operate as a Microsoft Windows Service courtesy of Yet Another Java Service Wrapper (YAJSW). Startup options must be provided in JAGORNET_DHCP_HOME\bin\yajsw-stable-11.0\conf\wrapper.conf. Edit this file using a standard text editor (i.e. notepad.exe), and locate the following set of commented properties:

# Application parameters.  Add parameters as needed starting from 1
# YAJSW: to specify the main class please use wrapper.java.app.mainclass=
#wrapper.app.parameter.1=
#wrapper.app.parameter.2=
#wrapper.app.parameter.#=

Provide desired startup options by adding uncommented wrapper.app.parameter.# entries for each option and each option value. For example:

  1. Start the server on a test port with support for multicast on all IPv6 multicast-enabled interfaces:

    wrapper.app.parameter.1=-6p
    wrapper.app.parameter.2=10547
    wrapper.app.parameter.3=-6m
  2. Start the server with support for DHCPv6 multicast on one interface and DHCPv4 broadcast on another interface:

    wrapper.app.parameter.1=-6m
    wrapper.app.parameter.2=eth0
    wrapper.app.parameter.3=-4b
    wrapper.app.parameter.4=eth1
  3. Start the server with an alternate configuration file, one specific unicast address, and two specific multicast interfaces:

    wrapper.app.parameter.1=-c
    wrapper.app.parameter.2=conf\my-dhcpserver.xml
    wrapper.app.parameter.3=-6u
    wrapper.app.parameter.4=2001:db8::1
    wrapper.app.parameter.5=-6m
    wrapper.app.parameter.6=eth0
    wrapper.app.parameter.7=eth1

The following batch files are provided for operating the Jagornet DHCP Server as a Windows Service.

  • JAGORNET_DHCP_HOME%\bin\JagornetDhcpServer.bat - run the server in the command window. Use Ctrl+C to stop.

  • JAGORNET_DHCP_HOME%\bin\InstallJagornetDhcpServer.bat - install the Jagornet DHCP Server as a Windows Service. On Windows 7 / Server 2008 this must be "Run As Administrator".

  • JAGORNET_DHCP_HOME%\bin\UninstallJagornetDhcpServer.bat - remove the Jagornet DHCP Server as a Windows Service. On Windows 7 / Server 2008 this must be "Run As Administrator".

  • JAGORNET_DHCP_HOME%\bin\StartJagornetDhcpServer.bat - start the Jagornet DHCP Server as a Windows Service. The server can also be started using Windows Control Panel -> Administrative Tools -> System or the Microsoft Management Console (MMC) Services controller.

  • JAGORNET_DHCP_HOME%\bin\StopJagornetDhcpServer.bat - stop the Jagornet DHCP Server as a Windows Service. The server can also be stopped using Windows Control Panel -> Administrative Tools -> System or the Microsoft Management Console (MMC) Services controller.

Command Shell

As an alternative to running Jagornet DHCP Server as a Windows Service, the JAGORNET_DHCP_HOME%\bin\dhcpserver.bat batch file can be used to operate the server from a command shell. Provide any desired startup options on the command line. Enter <Ctrl+C> in the command shell window to stop the server.

Startup examples:

  1. Display the server version and exit (any of the following):

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver version

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start -v

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start --version

  2. Start the server with the default options (DHCPv6 unicast on all interfaces, no DHCPv6 multicast, DHCPv4 unicast on all interfaces, no DHCPv4 broadcast):

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start

  3. Start the server on a test port with support for multicast on all IPv6 multicast-enabled interfaces:

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start -6p 10547 -6m

  4. Start the server with support for DHCPv6 multicast on the interface named 'eth0' and DHCPv4 broadcast on the interface named 'eth1':

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start -6m eth0 -4b eth1

  5. Start the server with an alternate configuration file, one specific unicast address, and two specific multicast interfaces:

    • > %JAGORNET_DHCP_HOME\bin\dhcpserver start -c conf\my-dhcpserver.xml -6u 2001:db8::1 -6m eth0 eth1

Chapter 3. Configuration

Hierarchy

The Jagornet DHCP server is configured via the conf/dhcpserver.xml XML document. See the Startup Options to change the name and location of the configuration file. The XML schema which defines all server configuration elements is available at conf/dhcpserver.xsd. The configuration file has this general hierarchical structure:

  • global policies and options

  • global filters

    • filter policies and options

  • links

    • link policies and options

    • v6address/v6prefix/v4 pools

      • pool policies and options

      • pool filters

        • pool filter policies and options

    • link filters

      • link filter policies and options

      • link filter v6address/v6prefix/v4 pools

        • link filter pool policies and options

Policies and options are defined below and follow the natural hierarchy rules. That is, policies and options defined at a higher level apply to all lower levels unless override by another level in the hierarchy, which then takes precedence to the further lower levels. Options and polices cannot be removed or set to null at any level, unless specifically stated otherwise.

Server Policies

Server polices are configured using the polices element. Each policy is specified with name and value elements. For example:

<policies>
...  
  <policy>
    <name>sendRequestedOptionsOnly</name>
    <value>true</value>
  </policy>
...
</policies>

The table below describes the policies available for the Jagornet DHCP Server. The Hierarchy Support column indicates which levels of the configuration hierarchy the policy is supported. For policies that are supported at 'all' levels, the lower level policy overrides the value of any matching higher level policy.

Table 3.1. Policies

Policy

Default Value

Description

Hierarchy Support

database.schemaType jdbc-derby The binding database schema type, which can be one of the following:
  • jdbc-derby - the default schema type uses JDBC to access an embedded Apache Derby database for lease bindings.

  • jdbc-h2 - this schema type uses JDBC to access an embedded H2 database for lease bindings.

  • jdbc-sqlite - this schema type uses JDBC to access an embedded SQLite database for lease bindings.

  • sqlite - this shema type uses JNI to access an embedded SQLite database for lease bindings.

  • mongo - this schema type uses a Java client library to access a Mongo database for lease bindings. Note that Mongo DB cannot be embedded and must be installed separately.

  • global

database.schemaVersion 2 The binding database schema version. Version 1 schema uses a relational model, and can only be used with the jdbc-* schemaTypes. Version 2 uses a single table model and can be used with all schemaTypes..
  • global

dhcp.ignoreLoopback true Ignore the loopback addresses when binding sockets during server startup.
  • global

dhcp.ignoreLinkLocal true Ignore the link local addresses when binding sockets during server startup.
  • global

dhcp.ignoreSelfPackets true Ignore packets received from one of the server's addresses.
  • global

dhcp.processor.recentMessageTimer

5000

Number of milliseconds to keep track of recent messages.  Used to minimize replays of the same message to the server.  That is, to help mitigate denial of service (DOS) attacks.

  • global

binding.manager.reaper.startupDelay

10000

Number of milliseconds for background thread to wait before checking for expired leases at server startup. Note that bindings are always expired when needed to free them for assignment.

  • global

binding.manager.reaper.runPeriod

60000

Number of milliseconds for background thread to wait between checks for expired leases. Note that bindings are always expired when needed to free them for assignment.

  • global

binding.manager.offerExpiration

12000

Number of milliseconds after which an offered address is considered free if the address is not requested by the client.

  • global

binding.manager.deleteOldBindings

false

Flag to indicate if the server should delete bindings upon expiration, or keep the binding while marking it expired.

  • global

       

sendRequestedOptionsOnly

false

Flag to indicate if the server should return only the options requested by a client in the Option Request Option (ORO) if available, or send all configured options.

  • all

supportRapidCommit

false

Flag to indicate if the server should support clients requesting rapid commit of binding.

  • global

  • filter

  • link

  • linkFilter

verifyUnknownRebind

false

Flag to indicate if the server should attempt to verify that addresses in a client's request are appropriate for the client's link, even though that client is unknown to the server.  See section 18.2.4 of RFC 3315.

  • global

  • filter

  • link

  • linkFilter

       

preferredLifetime

3600

Number of seconds for the preferred lifetime of addresses/prefixes provided by the server to the client.

  • global

  • link

  • pool

validLifetime

3600

Number of seconds for the valid lifetime of addresses/prefixes provided by the server to the client.

  • global

  • link

  • pool

iaNaT1

0.5

Percentage of shortest preferred lifetime of the addresses in the IA_NA to set the IA_NA T1 (renew) time in server replies.

  • global

  • link

iaNaT2

0.8

Percentage of shortest preferred lifetime of the addresses in the IA_NA to set the IA_NA T2 (rebind) time in server replies.

  • global

  • link

iaPdT1

0.5

Percentage of shortest preferred lifetime of the prefixes in the IA_PD to set the IA_PD T1 (renew) time in server replies.

  • global

  • link

iaPdT2

0.8

Percentage of shortest preferred lifetime of the addresses in the IA_PD to set the IA_PD T2 (rebind) time in server replies.

  • global

  • link

       

ddns.update

none

Support Dynamic DNS updates for clients which send the Client FQDN option. Available values are:

  • none - no DDNS updates

  • honorNoUpdate - honor client FQDN NoUpdate flag

  • honorNoAAAA - honor client FQDN NoAAAA flag

  • global

  • filter

  • link

  • linkFilter

ddns.synchronize

false

Flag to indicate if the server should synchronize DDNS updates with issuing of leases.  That is, the DHCP Reply message will not be sent to the client until the DDNS update completes.

  • all

ddns.domain

 

The domain to use for the client FQDN. If the Client FQDN option in an unqualified hostname, this domain will be appended to the hostname to form the FQDN for DDNS updates. If the Client FQDN contains a domain name, that domain name (everything after the first label, i.e. after the first dot ".") will be replaced by this configured domain name.

  • all

ddns.ttl

0.3

Value for the TTL of DDNS updates. If the value is less than one(1), it is assumed to be a percentage of the valid lifetime in seconds.  If the value is greater than or equal to one(1), it assumed to be an absolute number of seconds.

  • all

ddns.server

 

The IP address of the dynamic DNS server for sending DDNS updates.

  • all

ddns.tsig.keyName

 

The name of the TSIG key for signed DDNS updates.

  • all

ddns.tsig.algorithm

 

The algorithm name used for the TSIG key for signed DDNS updates.  Currently supported value is 'hmac-sha256.'

  • all

ddns.tsig.keyData

 

The public key data of the TSIG key in base 64 encoding.

  • all

ddns.forward.zone.name

 

The name of the dynamic zone for forward DDNS updates. If not set, the zone will be assumed to be the ddns.domain, or if that is not set, then the portion of the client supplied FQDN which follows the first label.

  • all

ddns.forward.zone.ttl

0.3

Value for the TTL of forward DDNS updates. If the value is less than one(1), it is assumed to be a percentage of the valid lifetime in seconds.  If the value is greater than or equal to one(1), it assumed to be an absolute number of seconds.  This policy is only necessary if the forward DDNS TTL is different from the ddns.ttl policy value.

  • all

ddns.forward.zone.server

 

The IP address of the dynamic DNS server for sending forward DDNS updates. This policy is only necessary if the forward DDNS server is different from the ddns.server policy value.

  • all

ddns.forward.zone.tsig.keyName

 

The name of the TSIG key for signed forward DDNS updates. This policy is only necessary if the forward DDNS key name is different from the ddns.tsig.keyName policy value.

  • all

ddns.forward.zone.tsig.algorithm

 

The algorithm name used for the TSIG key for signed forward DDNS updates. This policy is only necessary if the forward DDNS algorithm is different from the 'ddns.tsig.algorithm' policy value. Currently supported value is 'hmac-sha256.'

  • all

ddns.forward.zone.tsig.keyData

 

The public key data of the TSIG key in base 64 encoding for signed reverse DDNS updates. This policy is only necessary if the forward DDNS key data is different from the ddns.tsig.keyData policy value.

  • all

ddns.reverse.zone.name

 

The name of the dynamic zone for reverse DDNS updates. If not set, the zone will be assumed to be the ip6.arpa domain  corresponding to the subnet based on the ddns.reverse.zone.bitLength policy below.

  • all

ddns.reverse.zone.bitLength

64

The number of bit representing the subnet for calculating the reverse zone name.

  • all

ddns.reverse.zone.ttl

0.3

Value for the TTL of reverse DDNS updates. If the value is less than one(1), it is assumed to be a percentage of the valid lifetime in seconds. If the value is greater than or equal to one(1), it assumed to be an absolute number of seconds. This policy is only necessary if the reverse DDNS TTL is different from the ddns.ttl policy value.

  • all

ddns.reverse.zone.server

 

The IP address of the dynamic DNS server for sending reverse DDNS updates. This policy is only necessary if the reverse DDNS server is different from the ddns.server policy value.

  • all

ddns.reverse.zone.tsig.keyName

 

The name of the TSIG key for signed reverse DDNS updates. This policy is only necessary if the reverse DDNS key name is different from the ddns.tsig.keyName policy value.

  • all

ddns.reverse.zone.tsig.algorithm

 

The algorithm name used for the TSIG key for signed reverse DDNS updates. This policy is only necessary if the reverse DDNS algorithm is different from the ddns.tsig.algorithm policy value. Currently supported value is 'hmac-sha256.'

  • all

ddns.reverse.zone.tsig.keyData

 

The public key data of the TSIG key in base 64 encoding for signed reverse DDNS updates. This policy is only necessary if the reverse DDNS key data is different from the ddns.tsig.keyData policy value.

  • all

v4.header.sname   The server host name field of the DHCPv4 header. Used in conjunction with v4.header.filename. See also - v4TftpServerNameOption.
  • all

v4.header.filename   The boot file name field of the DHCPv4 header. The name of a boot file which the client will retrieve from the server specified in the sname header field. See also - v4BootFileNameOption.
  • all

v4.ignoredMacAddrs 000000000000, FFFFFFFFFFFF A list of comma separated MAC addresses for the server to ignore requests from.
  • all

v4.defaultLeasetime 3600 The lease time for DHCPv4 clients.
  • all

v4.pingCheckTimeout 0 The number of milliseconds to wait for a response to a ping before offering new addresses to DHCPv4 clients.
  • global

       

DHCP Options

DHCP options are configured using the options element. Each option is specified by an element with a name of the option, for example dnsServersOption. The Jagornet DHCP server supports all options defined in RFC 3315, as well as other DHCPv6 options defined in additional RFCs. In addition the Jagornet DHCP server supports the most common DHCPv4 options.

DHCPv6 Server Identifier Option

The Server Identifier Option is required by the DHCPv6 protocol for the server to include in reply packets. The v6ServerIdOption must be specified in the conf/dhcpserver.xml file. The default conf/dhcpserver.xml file supplied with the Jagornet DHCP server specifies an empty DHCPv6 server identifier option as follows:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

    <v6ServerIdOption>
        <opaqueData>
            <hexValue/>
        </opaqueData>
    </v6ServerIdOption>

</dhc:dhcpServerConfig>

Using this default configuration, a DUID-LLT, as defined by section 9.2 of RFC 3315, will be automatically generated by the Jagornet DHCP server upon initial startup. This will cause the conf/dhcpserver.xml file to be rewritten with the generated serverIdOption, for example:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

  <v6ServerIdOption>
    <opaqueData>
        <hexValue>0001000149EFC509001E52C94D49</hexValue>
    </opaqueData>
  </v6ServerIdOption>

</dhc:dhcpServerConfig>

This is the recommended way to create a server identifier. Optionally, the v6ServerIdOption can be specified using the asciiValue of an opaque data option type, for example:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

    <v6ServerIdOption>
        <opaqueData>
            <asciiValue>Jagornet-DHCPv6</asciiValue>
        </opaqueData>
    </v6ServerIdOption>

</dhc:dhcpServerConfig>

Whichever method is chosen to create the server identifier, it should not be changed once it has been created.

DHCPv4 Server Identifier Option

The Server Identifier Option is required by the DHCPv4 protocol for the server to include in reply packets. The identifier is an IPv4 address which DHCPv4 clients will send unicast requests to. The v4ServerIdOption must be specified in the conf/dhcpserver.xml file. The default conf/dhcpserver.xml file supplied with the Jagornet DHCP server specifies an empty DHCPv4 server identifier option as follows:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

    <v4ServerIdOption>
        <ipAddress/>
    </v4ServerIdOption>

</dhc:dhcpServerConfig>

Using this default configuration, the default IP address of the host will be set for the DHCPv4 server identifier by the Jagornet DHCP server upon initial startup. This will cause the conf/dhcpserver.xml file to be rewritten with the populated v4ServerIdOption, for example:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

  <v4ServerIdOption>
    <ipAddress>10.10.10.10</ipAddress>
  </v4ServerIdOption>

</dhc:dhcpServerConfig>

This is the recommended way to create a server identifier. Optionally, the V4ServerIdOption can be specified using the ipAddress element, for example:

<?xml version="1.0" encoding="UTF-8"?>

<dhc:dhcpServerConfig xmlns:dhc="http://jagornet.com/dhcp/xml">

    <v4ServerIdOption>
        <ipAddress>11.11.11.11<ipAddress>
    </v4ServerIdOption>

</dhc:dhcpServerConfig>

Whichever method is chosen to create the server identifier, it should not be changed once it has been created because this address will be used by clients when renewing their lease.

Configuration Options

Configuration Options are those options that can be configured for the server to return to clients in reply messages. For example, most network clients will need to know the address of one or more Domain Name System (DNS) servers.

DHCPv6 Configuration Options

Options can be returned at three distinct "levels" within the returned DHCPv6 reply packet.

  1. v6MsgConfigOptions - Message configuration options will be returned to the client at the outermost layer of the DHCPv6 packet. For Info-Request messages, only message configuration options are returned to the client. All known configuration options are returned to the client at the message level.

  2. v6IaNaConfigOptions/v6IaTaConfigOptions/v6IaPdConfigOptions - Identity association configuration options will be returned to the client inside the Identity Association (IA) option within the reply message. Separate configuration options elements are available for each type of IA option, including IA_NA, IA_TA, and IA_PD options. No known configuration options are returned to the client at the IA level, therefore these elements are for experimental and future use.

  3. v6NaAddrConfigOptions/v6TaAddrConfigOptions/v6PrefixConfigOptions - Address configuration options will be returned to the client inside the address or prefix option within the IA option within the reply message. Separate configuration options elements are available for each of the associated IA option type. No known configuration options are returned to the client at the address level, therefore these elements are for experimental and future use.

Table 3.2. DHCPv6 Configuration Options

Code Name (Reference) Option Element Syntax
7 v6PreferenceOption

(Section 22.8 of RFC 3315)

<v6PreferenceOption>
  <unsignedByte>10</unsignedByte>
</v6PreferenceOption>
12 v6ServerUnicastOption

(Section 22.8 of RFC 3315)

<v6ServerUnicastOption>
  <ipAddress>2001:db8::1</ipAddress>
</v6ServerUnicastOption>
13 v6StatusCodeOption

(Section 22.13 of RFC 3315)

<v6StatusCodeOption>
  <code>5</code>
  <message>UseMulticast</message>
</v6StatusCodeOption>
17 v6VendorInfoOption

Section 22.16 of RFC 3315

<v6VendorInfoOption>
  <enterpriseNumber>999</enterpriseNumber>
  <subOptionList>
    <optionDef code="1" name="VendorSubopt1">
      <stringOption>
        <string>VendorSpecial</string>
      </stringOption>
    </optionDef>
    <optionDef code="2" name="VendorSubopt2">
      <ipAddressOption>
        <ipAddress>2001:db8::999</ipAddress>
      </ipAddressOption>
    </optionDef>
  </subOptionList>
</v6VendorInfoOption>
21 v6SipServerDomainNamesOption

(RFC 3319)

<v6SipServerDomainNamesOption>
  <domainName>sip.foo.com.</domainName>
  <domainName>sip.bar.com.</domainName>
</v6SipServerDomainNamesOption>
22 v6SipServerAddressesOption

(RFC 3319)

<v6SipServerAddressesOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6SipServerAddressesOption>
23 v6DnsServersOption

(RFC 3646)

<v6DnsServersOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6DnsServersOption>
24 v6DomainSearchListOption

(RFC 3646)

<v6DomainSearchListOption>
  <domainName>foo.com.</domainName>
  <domainName>bar.com.</domainName>
</v6DomainSearchListOption>
27 v6NisServersOption

(RFC 3898)

<v6NisServersOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6NisServersOption>
28 v6NisPlusServersOption

(RFC 3898)

<v6NisPlusServersOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6NisPlusServersOption>
29 v6NisDomainNameOption

(RFC 3898)

<v6NisDomainNameOption>
  <domainName>foo.com.</domainName>
</v6NisDomainNameOption>
30 v6NisPlusDomainNameOption

(RFC 3898)

<v6NisPlusDomainNameOption>
  <domainName>foo.com.</domainName>
</v6NisPlusDomainNameOption>
31 v6SntpServersOption

(RFC 4075)

<v6SntpServersOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6SntpServersOption>
32 v6InfoRefreshTimeOption

(RFC 4242)

<v6InfoRefreshTimeOption>
  <unsignedInt>3600</unsignedInt>
</v6InfoRefreshTimeOption>
33 v6BcmcsDomainNamesOption

(RFC 4280)

<v6BcmcsDomainNamesOption>
  <domainName>bcmcs.foo.com.</domainName>
  <domainName>bcmcs.bar.com.</domainName>
</v6BcmcsDomainNamesOption>
34 v6BcmcsAddressesOption

(RFC 4280)

<v6BcmcsAddressesOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6BcmcsAddressesOption>
36 v6GeoconfCivicOption

(RFC 4776)

<v6GeoconfCivicOption>
  <what>1</what>
  <countryCode>US</countryCode>
  <civicAddressElement>
    <caType>0</caType>
    <caValue>de</caValue>
  </civicAddressElement>
  <civicAddressElement>
    <caType>128</caType>
    <caValue>Latn</caValue>
  </civicAddressElement>
  <civicAddressElement>
    <caType>1</caType>
    <caValue>Bayern</caValue>
  </civicAddressElement>
</v6GeoconfCivicOption>
40 v6PanaAgentAddressesOption

(RFC 5192)

<v6PanaAgentAddressesOption>
  <ipAddress>2001:db8::1</ipAddress>
  <ipAddress>2001:db8::2</ipAddress>
</v6PanaAgentAddressesOption>
41 v6NewPosixTimezoneOption

(RFC 4833)

<v6NewPosixTimezoneOption>
  <string>EST5EDT4,M3.2.0/02:00,M11.1.0/02:00</string>
</v6NewPosixTimezoneOption>
42 v6NewTzdbTimezoneOption

(RFC 4833)

<v6NewTzdbTimezoneOption>
  <string>Europe/Zurich</string>
</v6NewTzdbTimezoneOption>
51 v6LostServerDomainNameOption

(RFC 5223)

<v6LostServerDomainNameOption>
  <domainName>lost.foo.com.</domainName>
</v6LostServerDomainNameOption>

DHCPv4 Configuration Options

Options are returned within the returned DHCPv4 reply packet.

Table 3.3. DHCPv4 Configuration Options

Code Name (Reference) Option Element Syntax
1 v4SubnetMaskOption

(Section 3.3 of RFC 2132)

<v4SubnetMaskOption>
  <ipAddress>255.255.255.0</ipAddress>
</v4SubnetMaskOption>
2 v4TimeOffsetOption

(Section 3.4 of RFC 2132)

<v4TimeOffsetOption>
  <unsignedInt>5000</unsignedInt>
</v4TimeOffsetOption>
3 v4RoutersOption

(Section 3.5 of RFC 2132)

<v4RoutersOption>
  <ipAddress>10.0.0.1</ipAddress>
  <ipAddress>10.0.0.2</ipAddress>
</v4RoutersOption>
4 v4TimeServersOption

(Section 3.6 of RFC 2132)

<v4TimeServersOption>
  <ipAddress>10.0.0.1</ipAddress>
  <ipAddress>10.0.0.2</ipAddress>
</v4TimeServersOption>
6 v4DomainServersOption

(Section 3.8 of RFC 2132)

<v4DomainServersOption>
  <ipAddress>10.0.0.1</ipAddress>
  <ipAddress>10.0.0.2</ipAddress>
</v4DomainServersOption>
15 v4DomainNameOption

(Section 3.17 of RFC 2132)

<v4DomainNameOption>
  <domainName>foo.com.</domainName>
</v4DomainNameOption>
43 v4VendorSpecificOption

(Section 8.4 of RFC 2132)

<v4VendorSpecificOption>
  <subOptionList>
    <optionDef code="1" name="VendorSubopt1">
      <stringOption>
        <string>VendorSpecial</string>
      </stringOption>
    </optionDef>
    <optionDef code="2" name="VendorSubopt2">
      <ipAddressOption>
        <ipAddress>10.11.12.13</ipAddress>
      </ipAddressOption>
    </optionDef>
  </subOptionList>
</v4VendorSpecificOption>
44 v4NetbiosNameServersOption

(Section 8.5 of RFC 2132)

<v4NetbiosNameServersOption>
  <ipAddress>10.0.0.1</ipAddress>
  <ipAddress>10.0.0.2</ipAddress>
</v4NetbiosNameServersOption>
46 v4NetbiosNodeTypeOption

(Section 8.7 of RFC 2132)

<v4NetbiosNodeTypeOption>
  <unsignedByte>8</unsignedByte>
</v4NetbiosNodeTypeOption>
66 v4TftpServerNameOption

(Section 9.4 of RFC 2132)

<v4TftpServerNameOption>
  <string>tftp.foo.com.</string>
</v4TftpServerNameOption>
67 v4BootFileNameOption

(Section 9.5 of RFC 2132)

<v4BootFileNameOption>
  <string>bootfile-name</string>
</v4BootFileNameOption>

Generic Options

Generic options are used to define new option types for experimental or future options. Generic options are defined using the optionDef element. The otherOptions element of the configuration options can be used to add one or more new or experimental options to the options that will be sent by the server to the client. Generic options are also used when defining the suboptionList of the Vendor Information Option as shown in the table above.

Option Definition Type

The option definition type predefines several option types for use in creating new, experimental, or vendor options.

Table 3.4. Generic Option Definitions

Element Generic Option Definition Syntax
nilOption
<optionDef code="99" name="MyOption">
  <nilOption/>
</optionDef>
uByteOption
<optionDef code="99" name="MyOption">
  <uByteOption>
    <unsignedByte>255</unsignedByte>
  </uByteOption>
</optionDef>
uByteListOption
<optionDef code="99" name="MyOption">
  <uByteListOption>
    <unsignedByte>1</unsignedByte>
    <unsignedByte>10</unsignedByte>
    <unsignedByte>255</unsignedByte>
  </uByteListOption>
</optionDef>
uShortOption
<optionDef code="99" name="MyOption">
  <uShortOption>
    <unsignedShort>65535</unsignedShort>
  </uShortOption>
</optionDef>
uShortListOption
<optionDef code="99" name="MyOption">
  <uShortListOption>
    <unsignedShort>1</unsignedShort>
    <unsignedShort>999</unsignedShort>
    <unsignedShort>65535</unsignedShort>
  </uShortListOption>
</optionDef>
uIntOption
<optionDef code="99" name="MyOption">
  <uIntOption>
    <unsignedInt>4294697295</unsignedInt>
  </uIntOption>
</optionDef>
stringOption
<optionDef code="99" name="MyOption">
  <stringOption>
    <string>myOptionStringValue</string>
  </stringOption>
</optionDef>
ipAddressOption
<optionDef code="99" name="MyOption">
  <ipAddressOption>
    <ipAddress>2001:db8::1</ipAddress>
  </ipAddressOption>
</optionDef>
ipAddressListOption
<optionDef code="99" name="MyOption">
  <ipAddressListOption>
    <ipAddress>2001:db8::1</ipAddress>
    <ipAddress>2001:db8::2</ipAddress>
    <ipAddress>2001:db8::3</ipAddress>
  </ipAddressListOption>
</optionDef>
domainNameOption
<optionDef code="99" name="MyOption">
  <domainNameOption>
    <domainName>my.foo.com.</domainName>
  </domainNameOption>
</optionDef>
domainNameListOption
<optionDef code="99" name="MyOption">
  <domainNameListOption>
    <domainName>my.foo.com.</domainName>
    <domainName>my.bar.com.</domainName>
    <domainName>my.yuk.com.</domainName>
  </domainNameListOption>
</optionDef>
opaqueDataOption
<optionDef code="99" name="MyOption">
  <opaqueDataOption>
    <opaqueData>
      <hexValue>0123456789abcdef</hexValue>
    </opaqueData>
  </opaqueDataOption>
</optionDef>
opaqueDataListOption
<optionDef code="99" name="MyOption">
  <opaqueDataListOption>
    <opaqueData>
      <hexValue>0123456789abcdef</hexValue>
    </opaqueData>
    <opaqueData>
      <asciiValue>HelloWorld</asciiValue>
    </opaqueData>
    <opaqueData>
      <hexValue>0a1b2c3d4e5f</hexValue>
    </opaqueData>
  </opaqueDataListOption>
</optionDef>

Opaque Data Option

Opaque data options are those options which can contain opaque, binary data. Often, these options actually contain simple ASCII strings. Therefore, the opaqueData element contains either a hexValue element, which specifies the binary value as a hexadecimal string, or an asciiValue element, which specifies the ASCII string value.

Filters

Filters are used to classify DHCP clients so that specific configuration options can be supplied to certain classes of clients. A typical use of filters is to define a vendor class mapping to provide vendor specific information option data for clients that include the vendor class option in the request. Filters can also be used to arbitrarily group clients according to any criteria which matches one or more options supplied by the client. Each filter definition includes a name, one or more filter expressions, a set of one or more configured options, and optional server policies.

Filter Expressions

If more than one filter expression is defined in a filter, then the client request must match all of the expressions. That is, multiple filter expressions are logically anded together to form the match criteria. Each filter expression must contain at least one client class, option or custom expression.

Client Class Expression

A client class expression defines criteria for matching all or part of a DHCPv6 user class or vendor class, or a DHCPv4 vendor class option provided in the client request. The clientClassExpression element must specify only one of the three supported client class options - DHCPv6 user or vendor class, or DHCPv4 vendor class - and the required operator attribute, which defaults to 'equals' and defines the match criteria.

DHCPv6 User Class Filter Example

The following filter definition matches clients which supply a specific DHCPv6 user class option value. This filter is configured to provide a specific DNS domain name for such clients.

<filter>
  <name>DHCPv6 UserClass Filter</name>
  <filterExpressions>
    <filterExpression>
      <clientClassExpression operator="equals">
        <v6UserClassOption>
          <opaqueData>
            <asciiValue>MyUserClass</asciiValue>
          </opaqueData>
        </v6UserClassOption>
      </clientClassExpression>
    </filterExpression>
  </filterExpressions>
  <v6MsgConfigOptions>
    <v6DomainSearchListOption>
      <domainName>filter.com.</domainName>
    </v6DomainSearchListOption>
  </v6MsgConfigOptions>
</filter>
DHCPv6 Vendor Class Filter Example

The following filter definition matches client which supply a specific DHCPv6 vendor class option value. This filter is configured to provide a vendor specific information option, which contains two suboptions, for such clients.

<filter>
  <name>DHCPv6 VendorClass Filter</name>
  <filterExpressions>
    <filterExpression>
      <clientClassExpression operator="equals">
        <v6VendorClassOption>
          <opaqueData>
            <asciiValue>VendorXYZ</asciiValue>
          </opaqueData>
          <enterpriseNumber>12345</enterpriseNumber>
        </v6VendorClassOption>
      </clientClassExpression>
    </filterExpression>
  </filterExpressions>
  <v6MsgConfigOptions>
    <v6VendorInfoOption>
      <enterpriseNumber>12345</enterpriseNumber>
      <suboptionList>
        <optionDef code="1">
          <stringOption>
            <string>hello</string>
          </stringOption>
        </optionDef>
        <optionDef code="2">
          <ipAddressOption>
            <ipAddress>2001:db8::1</ipAddress>
          </ipAddressOption>
        </optionDef>
      </suboptionList>
    </v6VendorInfoOption>
  </v6MsgConfigOptions>
</filter>
DHCPv4 Vendor Class Filter Example

As another example, consider the following filter definition which matches DHCPv4 clients which supply a vendor class option beginning with the specified ASCII value. This filter is configured to provide the vendor specific information option for such clients.

<filter>
  <name>DHCPv4 VendorClass Filter</name>
  <filterExpressions>
    <filterExpression>
      <clientClassExpression operator="startsWith">
        <v4VendorClassOption>
          <opaqueData>
            <asciiValue>MyVendorPrefix</asciiValue>
          </opaqueData>
        </v4VendorClassOption>
      </clientClassExpression>
    </filterExpression>
  </filterExpressions>
  <v4ConfigOptions>
    <v4VendorSpecificOption>
      <opaqueData>
        <hexValue>01020304</hexValue>
      </opaqueData>
    </v4VendorSpecificOption>
  </v4ConfigOptions>
</filter>

Option Expression

An option expression defines the criteria for matching all or part of an option provided in the client request using the generic option definition, along with a value and operator, which forms the expression. The optionExpression element must specify the DHCPv6 option code in the code attribute, followed by the optional name attribute from the generic option definition type above, and the required operator attribute, which defaults to 'equals'.

Table 3.5. Filter Option Expressions

Option Type Available Operators Example Filters Option Expression Syntax
uByteOption
  • equals

  • lessThan

  • lessThanOrEqual

  • greaterThan

  • greaterThanOrEqual

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <uByteOption>
        <unsignedByte>255</unsignedByte>
      </uByteOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
uByteListOption
  • equals

  • contains

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <uByteListOption>
        <unsignedByte>1</unsignedByte>
        <unsignedByte>255</unsignedByte>
      </uByteListOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
uShortOption
  • equals

  • lessThan

  • lessThanOrEqual

  • greaterThan

  • greaterThanOrEqual

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="lessThan">
      <uShortOption>
        <unsignedShort>65535</unsignedShort>
      </uShortOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
uShortListOption
  • equals

  • contains

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <uShortListOption>
        <unsignedShort>1</unsignedShort>
        <unsignedShort>65535</unsignedShort>
      </uShortListOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
uIntOption
  • equals

  • lessThan

  • lessThanOrEqual

  • greaterThan

  • greaterThanOrEqual

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="lessThan">
      <uIntOption>
        <unsignedInt>10000</unsignedInt>
      </uIntOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
stringOption
  • equals

  • startsWith

  • endsWith

  • contains

  • regExp

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="endsWith">
      <stringOption>
        <string>mySuffix</string>
      </stringOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
ipAddressOption
  • equals

  • startsWith

  • endsWith

  • contains

  • regExp

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <ipAddressOption>
        <ipAddress>2001:db8::1</ipAddress>
      </ipAddressOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
ipAddressListOption
  • equals

  • contains

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="contains">
      <ipAddressListOption>
        <ipAddress>2001:db8::1</ipAddress>
      </ipAddressListOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
domainNameOption
  • equals

  • startsWith

  • endsWith

  • contains

  • regExp

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <domainNameOption>
        <domainName>foo.com.</domainName>
      </domainNameOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
domainNameListOption
  • equals

  • contains

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="contains">
      <domainNameListOption>
        <domainName>foo.com.</domainName>
      </domainNameListOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
opaqueDataOption
  • equals

  • startsWith

  • endsWith

  • contains

  • regExp

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="regExp">
      <opaqueDataOption>
        <opaqueData>
          <asciiValue>myRegularExpression</asciiValue>
        </opaqueData>
      </opaqueDataOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>
opaqueDataListOption
  • equals

  • contains

<filterExpressions>
  <filterExpression>
    <optionExpression code="99" operator="equals">
      <opaqueDataOption>
        <opaqueData>
          <asciiValue>opaqueAsciiData</asciiValue>
        </opaqueData>
      </opaqueDataOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>

DHCPv4 Option Expression

DHCPv4 option expressions use the same syntax as DHCPv6 option expressions, but must identify the option as a DHCPv4 option using the v4 attribute. For example:

<filterExpressions>
  <filterExpression>
    <optionExpression v4="true" code="99" operator="equals">
      <uByteOption>
        <unsignedByte>255</unsignedByte>
      </uByteOption>
    </optionExpression>
  </filterExpression>
</filterExpressions>

Custom Expressions

Custom expressions are used to define filter expressions that cannot be configured using standard option expressions. Currently, Jagornet DHCP Server Community Edition does not support custom expressions.

Links

A link defines a network segment for client requests. At least one DHCPv6 or DHCPv4 link is required proper server configuration. The Jagornet DHCP Server uses the link definition to classify each incoming client request. Once the client link is determined, the server will use the link definition to determine which addresses are available from the pools and/or bindings defined within the link. Additional configuration elements can be specified within the link including filters, policies, and options.

DHCPv6 Links

For DHCPv6, the link is determined by the server according to section 11 of RFC 3315. If the message is received directly and the source address is link-local, then the client is on the link attached to the server interface which received the message. If the message is received directly and the source address is not link-local, then the client is on the link identified by the source address. If the message is received from a relay agent, then the client is on the link identified by the link-address of the Relay-Forward message. Therefore, DHCPv6 link definitions are either local or remote.

Local DHCPv6 Link Example

Local links require the interface element to specify the name of the server interface.

<link>
  <name>Local IPv6 Client Link (Multicast traffic)</name>
  <!-- Local DHCPv6 links are defined by interface name -->
  <interface>eth2</interface>
  ...
</link>

Remote DHCPv6 Link Example

Remote links require the address element to specify the address of the remote link.

<link>
  <name>Remote IPv6 Client Link (Unicast/Multicast traffic)</name>
  <!-- Remote DHCPv6 links are defined in CIDR notation -->
  <address>2001:db8:2::/48</address>
  ...
</link>

DHCPv4 Links

For DHCPv4, the link is determined by the 'giAddr' field of the DHCPv4 request header. If the 'giAddr' field is zero, then the link is determined by the IP address assigned to the IPv4 broadcast interface provided to the server at startup.

DHCPv4 Link Example

<link>
  <name>IPv4 Client Link 1</name>
  <!-- All DHCPv4 links are defined in CIDR notation.
       For local links, specify the interface as a
       startup command-line option, and configure the
       subnet for that interface's IPv4 address. -->
    <address>10.0.0.0/24</address>
  ...
</link>

Pools

Pools may be defined only within Links or Link Filters. The Jagornet DHCP Server supports four types of pools.

  1. v6NaAddrPools - DHCPv6 Non-temporary address (NA) pools

  2. v6TaAddrPools - DHCPv6 Temporary address (TA) pools

  3. v6PrefixPools - DHCPv6 Prefix delegation (PD) pools

  4. v4AddrPools - DHCPv4 address (V4) pools

Address Pools

Non-temporary and temporary address pools are defined by the addressPool type. The address pool must contain a range element to define the addresses available for allocation in the pool. The range is specified using the start and end address of a range of addresses, or a prefix and length. For example:

<link>
    <name>Client Link 2</name>
    <address>2001:DB8:2::/48</address>
    <v6IaNaConfigOptions>
        <v6DnsServersOption>
            <ipAddress>2001:DB8:2::1</ipAddress>
        </v6DnsServersOption>
    </v6IaNaConfigOptions>
    <v6NaAddrPools>
        <pool>
            <range>2001:DB8:2::0A-2001:DB8:2::FF</range>
            <addrConfigOptions>
                <v6SipServerAddressesOption>
                    <ipAddress>2001:DB8:2::1:1</ipAddress>
                </v6SipServerAddressesOption>
            </addrConfigOptions>
        </pool>
        <pool>
            <range>2001:DB8:2:1::/64</range>
            <addrConfigOptions>
                <v6SipServerAddressesOption>
                    <ipAddress>2001:DB8:2:1::1:1</ipAddress>
                </v6SipServerAddressesOption>
            </addrConfigOptions>
        </pool>
    </v6NaAddrPools>
</link>

Prefix Pools

Prefix delegation pools are defined by the prefixPool type. The prefix pool must contain a range element to define the prefix available for delegation, and the prefixLength element to define the size of the prefixes to allocate to requesting routers. For example:

<link>
    <name>Prefix Delegation Link</name>
    <address>2001:DB8:1::/48</address>
    <v6IaPdConfigOptions>
        <v6DnsServersOption>
            <ipAddress>2001:DB8:2::1</ipAddress>
        </v6DnsServersOption>
    </v6IaPdConfigOptions>
    <v6PrefixPools>
        <pool>
            <range>2001:DB8:2::/48</range>
            <prefixLength>64</prefixLength>
            <prefixConfigOptions>
                <sipServerAddressesOption>
                    <ipAddress>2001:DB8:2:1::1:1</ipAddress>
                </sipServerAddressesOption>
            </prefixConfigOptions>
        </pool>
    </v6PrefixPools>
</link>

DHCPv4 Pools

DHCPv4 address pools are defined by the v4AddressPool type. The address pool must contain a range element to define the addresses available for allocation in the pool. The range is specified using the start and end address of a range of addresses. For example:

<link>
    <name>DHCPv4 Client Subnet</name>
    <address>10.0.0.0/24</address>
    <v4ConfigOptions>
        <v4SubnetMaskOption>
            <ipAddress>255.255.255.0</ipAddress>s
        </v4SubnetMaskOption>
        <v4RoutersOption>
            <ipAddress>10.0.0.1</ipAddress>
            <ipAddress>10.0.0.2</ipAddress>
        </v4RoutersOption>
    <v4ConfigOptions>
    <v4AddrPools>
        <pool>
            <range>10.0.0.100-10.0.0.199</range>
            <v4ConfigOptions>
                <v4DomainNameOption>
                    <domainName>foo.com.</domainName>
                </v4DomainNameOption>
            </v4ConfigOptions>
        </pool>
        <pool>
            <range>10.0.0.200-10.0.0.254</range>
            <v4ConfigOptions>
                <v4DomainNameOption>
                    <domainName>bar.com.</domainName>
                </v4DomainNameOption>
            </v4ConfigOptions>
        </pool>
    </naAddrPools>
</link>

Static Bindings

Static bindings are used to reserve a specific IP address for a specific client. Bindings may be defined only within Links. The Jagornet DHCP Server supports four types of bindings.

  1. v6NaAddrBindings - DHCPv6 Non-temporary address (NA) bindings

  2. v6TaAddrBindings - DHCPv6 Temporary address (TA) bindings

  3. v6PrefixBindings - DHCPv6 Prefix delegation (PD) bindings

  4. v4AddrBindings - DHCPv4 address (V4) bindings

Address Bindings

Non-temporary and temporary static address bindings are defined by the addressBinding type. The address binding must contain the ipAddress element to specify the IP address reserved for the client. The address binding must also contain the duid element to identify the client. Note that the client's DUID is a calculated value which is generally not predictable in all situations. Therefore, static address bindings for DHCPv6 should be considered an experimental feature for controlled environments only. In addition to the DUID, a static address binding may further identify the client request by specifying the optional iaid element. Again, the client's IA_ID is generally unpredictable. However, if the IA_ID is not specified, then all client requests for the given DUID will be assigned the specified IP address. This may be acceptable if the clients are known to have a single network interface. If the administrator understands the inherent risks with this configuration feature, it may be used with caution. For example:

<v6NaAddrBindings>
  <binding>
    <ipAddress>2001:db8:1::100</ipAddress>
    <!-- DHCPv6 "binding" is not really supported yet
         because clients do not send a MAC address, but
         if the DUID is known, then a binding can be made. -->
    <duid>
      <hexValue>0a1b2c3d4e5f</hexValue>
    </duid>
    <!-- The IA_ID is almost definitely unpredictable, so
         it is an optional element for a DHCPv6 binding.  If
         left undefined, then ANY IA_ID will match.
    <iaid>0</iaid>
    -->
    ...
  </binding>
  ...
</v6NaAddrBindings>

Prefix Bindings

Prefix delegation static prefix bindings are defined by the prefixBinding type. The prefix binding must contain the prefix element to define the prefix available for delegation, and the prefixLength element to define the size of the prefixes to allocate to requesting router. The same caveats and cautions as DHCPv6 address bindings apply for prefix bindings as well. For example:

<v6PrefixBindings>
  <binding>
    <prefix>2001:db8:1::</prefix>
    <prefixLength>64</prefixLength>
    <!-- DHCPv6 "binding" is not really supported yet
         because clients do not send a MAC address, but
         if the DUID is known, then a binding can be made. -->
    <duid>
      <hexValue>0a1b2c3d4e5f</hexValue>
    </duid>
    ...
  </binding>
  ...
</v6PrefixBindings>

DHCPv4 Bindings

DHCPv4 static address bindings are defined by the v4AddressBinding type. The address binding must contain a ipAddress element to specify the IP address reserved for the client. The address binding must also contain the chAddr element to identify the client from the corresponding field in the DHCPv4 request header. For example:

<v4AddrBindings>
  <binding>
    <!-- Binding addresses should NOT be inside a pool -->
    <ipAddress>10.0.0.200</ipAddress>
    <chaddr>0a1b2c3d4e5f</chaddr>
    ...
  </binding>
  ...
</v4AddrBindings>

Chapter 4. DHCPv6 Operational Models

IPv6 capable hosts are notified via router advertisement (RA) flags when and how to use DHCPv6. These flags are defined in RFC 4861 as follows:

  1. Managed address configuration flag (M bit) - when set, it indicates that addresses are available via Dynamic Host Configuration Protocol [DHCPv6]. If the M flag is set, the O flag is redundant and can be ignored because DHCPv6 will return all available configuration information.

  2. Other configuration flag (O bit) - when set, it indicates that other configuration information is available via DHCPv6. Examples of such information are DNS-related information or information on other servers within the network.

The operation of the host with respect to these flags can be summarized as follows:

Table 4.1. DHCPv6 Operational Models

Flag

M=1

M=0

O=1

DHCPv6 for address and configuration information

DHCPv6 for configuration information only

O=0

DHCPv6 for address and configuration information

No DHCPv6

A host which is configured to use DHCPv6 as described above will send Solicit messages for address assignment and configuration requests or Information-Request messages for configuration-only requests to the All_DHCP_Relay_Agents_and_Servers(FF02::1:2) link-scoped multicast IPv6 address. The request message is handled either by a DHCPv6 server on the local link, or forwarded by a DHCPv6 relay agent to a DHCPv6 server on a separate network link. A DHCPv6 relay agent is available in most routers and layer 3 switches which support IPv6.

Operational model using a DHCPv6 Relay Agent

Most IPv6 networks will involve one or more IPv6 capable routers. Most IPv6 capable routers include an implementation of a DHCPv6 relay agent. Please consult your router vendor's documentation for details on enabling the DHCPv6 relay agent.

In this operational model, multicast request messages sent by the DHCPv6 clients are received by the DHCPv6 relay agent which wraps the request in a Relay-Forward message. The DHCPv6 relay agent may send the wrapped message via unicast to the address of one or more known DHCPv6 servers, or to the All_DHCP_Servers site-scoped multicast address. Typically, the DHCPv6 relay agent will be configured with a list of known DHCPv6 server addresses in order to minimize multicast traffic, and for security purposes to avoid malicious or rouge servers. The DHCPv6 server will wrap a Reply for the client in a Relay-Reply message and unicast the wrapped message to the DHCPv6 relay which forwarded the original client request. The relay agent will send the encapsulated Reply message to the DHCPv6 client via unicast to the source address of the original client request.

 ----------                  ----------                     ----------

|          |   Multicast    |          | Unicast/Multicast |          |

|          | -------------> |          | ----------------> |          |

|          |    Request     |          |  Relay-Forward    |          |

|  DHCPv6  |                |  DHCPv6  |    (Request)      |  DHCPv6  |

|  Client  |                |  Relay   |                   |  Server  |

|          |    Unicast     | (Router) |      Unicast      |          |

|          | <------------- |          | <---------------- |          |

|          |     Reply      |          |   Relay-Reply     |          |

 ----------                  ----------      (Reply)        ----------

Operational model without a DHCPv6 Relay Agent

Some IPv6 networks may not utilize a DHCPv6 relay agent.

In this operational model, multicast request messages sent by the DHCPv6 clients are received directly by one or more DHCPv6 servers which are configured on the same link as the clients. The DHCPv6 server(s) will send the Reply message to the source address of the original client request.

 ----------                  ----------

|          |   Multicast    |          |

|          | -------------> |          |

|          |    Request     |          |

|  DHCPv6  |                |  DHCPv6  |

|  Client  |                |  Server  |

|          |    Unicast     |          |

|          | <------------- |          |

|          |     Reply      |          |

 ----------                  ----------

Appendix A. Binding Database

The Jagornet DHCP server uses an embedded Apache Derby database server for managing the binding database by default. The database schema file is located in the db/jagornet-dhcp-schema-derby[-v2].sql file. At initial startup, the server will create the database in the db/derby directory using the schema. When the server is stopped, the db/derby directory can be deleted (do not delete db/*.sql), and upon restart, the Jagornet DHCP server will recreate the database. Please note that deleting the database should only be performed in test environments, or when a backup copy of the database is being restored.

Beginning with Jagornet DHCP v2.0rc, the server can be configured to use most any JDBC accessible database. Jagornet DHCP includes built-in support for the H2 Database and SQLite using the JDBC interface. The JDBC database configuration is maintained in the conf/jdbc.properties file. The default configuration sets the jdbc.user, jdbc.password, jdbc.driver, and jdbc.url properties for Derby. To switch to H2 or SQLite, simply comment out (insert a # at the line beginning) the default properties and uncomment the corresponding properties in the H2 or SQLite section. You must create the directory db/sqlite before using this configuration. When the server is stopped, the contents of the db/h2 or db/sqlite directory can be deleted (do not delete db/*.sql), and upon restart, the Jagornet DHCP server will recreate the database. Please note that deleting the database should only be performed in test environments, or when a backup copy of the database is being restored.

Also beginning with Jagornet DHCP v2.0rc, the server can be configured to use a Java Native Interface (JNI) wrapper to access the native SQLite interfaces. Due to the nature of SQLite, this interface requires the use of the version 2 database schema (db/jagornet-dhcp-schema-v2.sql). You must create the directory db/sqlite before using this configuration. When the server is stopped, the contents of the db/sqlite directory can be deleted (do not delete db/*.sql), and upon restart, the Jagornet DHCP server will recreate the database. Please note that deleting the database should only be performed in test environments, or when a backup copy of the database is being restored.

Beginning with Jagornet DHCP v2.0rc2, the server can be configured to use a Java library to access a native Mongo database. Although there is no schema used for Mongo DB, the data model is identical to the version 2 database schema. Note that Mongo DB is not provided with the Jagornet DHCP Server distribution. It must be downloaded and installed separately. Setting the database.schemaType policy to 'mongo' will cause the Jagornet DHCP server to attempt to connect to the Mongo DB on the localhost(127.0.0.1), using the default Mongo DB port(27017). Edit the conf/mongo.properties file to change the IP address and/or port of the Mongo database.

Appendix B. Logging

Logging for the Jagornet DHCP server is performed using the Apache Log4J logging service. The default Log4J configuration file is located in the conf/log4j.properties file. The server writes all initial startup messages to the standard output and error streams, which are redirected by the bin/dhcp script to the log/dhcpserver.out file. After the server initialization, all messages are created via Log4J and configured by the conf/log4j.properties file. The default file outputs all server messages to the log/dhcpserver.log rolling file. When the file reaches 10MB, it is "rolled" over to a new log/dhcpserver.log.# file up to ten files of logging history. These settings are controlled by the log4j.appender.Logfile properties.

Appendix C. Java Management Extensions (JMX)

The Jagornet DHCP Server supports Java Management Extensions (JMX) for dynamically configuring logging parameters and for monitoring server statistics. Support for JMX is available in Sun's JRE 6. For more information, please see the Java SE Management and Monitoring Guide .

Appendix D. DHCPv4 Limitation

The Jagornet DHCP Server supports Dynamic Host Configuration Protocol for IPv4 (DHCPv4) with the limitation that only one host interface can be used to service locally connected DHCPv4 clients. DHCPv4 clients will broadcast certain request messages, which are received by any DHCPv4 servers and relays attached to the client's network segment. Servers which receive the broadcast request will reply via broadcast to the client. Relays which receive the broadcast request will relay the request, via unicast, to one or more servers, and then relay the server reply, via broadcast, back to the client. The server will listen on the wildcard IP address (0.0.0.0) in order to receive broadcast requests. However, all broadcast replies will be sent on the interface designated with the -4b/--v4bcast startup option. Therefore, the administrator must ensure that local DHCPv4 clients are attached only to the designated interface, or that DHCPv4 clients are separated from the server by a DHCPv4 relay agent.