Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
Sebastian Schrader
Kea
Commits
51637af1
Commit
51637af1
authored
Feb 10, 2015
by
Marcin Siodelski
Browse files
[3604] Updated Kea user guide with the new config structure for interfaces.
parent
6eaf7f0c
Changes
3
Hide whitespace changes
Inline
Side-by-side
doc/guide/config.xml
View file @
51637af1
...
...
@@ -56,7 +56,10 @@
# DHCPv4 specific configuration starts here.
"Dhcp4": {
"interfaces": [ "eth0" ],
"interfaces-config": {
"interfaces": [ "eth0" ],
"socket-type": "raw"
},
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
...
...
@@ -70,7 +73,9 @@
# DHCPv6 specific configuration starts here.
"Dhcp6": {
"interfaces": [ "eth1" ],
"interfaces-config": {
"interfaces": [ "eth1" ]
},
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
...
...
@@ -119,8 +124,7 @@
If there is an array, a specific instance within that array is referenced by
a number in square brackets (with numbering starting at zero). For example, in the above configuration the
valid-lifetime in the Dhcp6 component can be referred to as
Dhcp6/valid-lifetime, the first interface for the DHCPv4 server as
Dhcp4/interfaces[0] and the pool in the first subnet defined in the DHCPv6
Dhcp6/valid-lifetime and the pool in the first subnet defined in the DHCPv6
configuration as Dhcp6/subnet6[0]/pool.
</para>
<!-- @todo Add a reference here after #3422 is done -->
...
...
doc/guide/dhcp4-srv.xml
View file @
51637af1
...
...
@@ -92,12 +92,16 @@
"Dhcp4": {
# First we set up global values
"interfaces": [ "eth0" ],
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# Next we specify the type of lease database
# Next we setup the interfaces to be used by the server.
"interfaces-config": {
"interfaces": [ "eth0" ]
},
# And we specify the type of lease database
"lease-database": {
"type": "memfile",
"persist": true,
...
...
@@ -154,19 +158,8 @@ ignored. This is unlikely to cause any confusion as there are no real life
reasons to keep multiple copies of the same parameter in your configuration
file.
</para>
<para>
Moving onto the DHCPv4 configuration elements,
the line defining
<command>
interfaces
</command>
parameter specifies a list
of network interfaces on which the server should listen.
Lists are opened and closed with square brackets, with elements
separated by commas. Had we wanted to listen on two interfaces, the line could
look like this:
<screen>
"interfaces": [ "eth0", "eth1" ],
</screen>
As "
<command>
interfaces
</command>
" is not the last parameter in the configuration,
a trailing comma is required.
</para>
<para>
A number of other parameters
follow.
<command>
valid-lifetime
</command>
defines for how long the addresses (leases) given out by the
<para>
Moving onto the DHCPv4 configuration elements, the very first few elements
define some global parameters.
<command>
valid-lifetime
</command>
defines for how long the addresses (leases) given out by the
server are valid. If nothing changes, a client that got an address is allowed to
use it for 4000 seconds. (Note that integer numbers are specified as is,
without any quotes around them.)
<command>
renew-timer
</command>
and
...
...
@@ -177,6 +170,20 @@ rebind procedures. Note that <command>renew-timer</command> and
client will select values for T1 and T2 timers according to the
<ulink
url=
"http://tools.ietf.org/html/rfc2131"
>
RFC 2131
</ulink>
.
</para>
<para>
The
<command>
interfaces-config
</command>
map specifies the server
configuration concerning the network interfaces, on which the server should
listen to the DHCP messages. The
<command>
interfaces
</command>
parameter
specifies a list of network interfaces on which the server should listen.
Lists are opened and closed with square brackets, with elements separated
by commas. Had we wanted to listen on two interfaces, the
<command>
interfaces-config
</command>
would look like this:
<screen>
"interfaces-config": {
"interfaces": [ "eth0", "eth1" ]
},
</screen>
</para>
<para>
The next couple of lines define the lease database, the place where the server
stores its lease information. This particular example tells the server to use
<command>
memfile
</command>
, which is the simplest (and fastest) database
...
...
@@ -332,22 +339,40 @@ url="http://jsonviewer.stack.hu/"/>.
</section>
</section>
<section
id=
"dhcp4-interface-
selec
tion"
>
<title>
Interface
selec
tion
</title>
<section
id=
"dhcp4-interface-
configura
tion"
>
<title>
Interface
configura
tion
</title>
<para>
The DHCPv4 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration tells the server to
listen on all available interfaces:
<screen>
"Dhcp4": {
<userinput>
"interfaces": ["*"]
</userinput>
, ... }
</screen>
"Dhcp4": {
"interfaces-config": {
"interfaces": [
<userinput>
"*"
</userinput>
]
}
...
},
</screen>
The asterisk plays the role of a wildcard and means "listen on all interfaces".
However, it is usually a good idea to explicitly specify interface names:
<screen>
"Dhcp4": {
<userinput>
"interfaces": [ "eth1", "eth3" ]
</userinput>
, ... }
</screen>
"Dhcp4": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1", "eth3"
</userinput>
]
},
...
}
</screen>
</para>
<para>
It is possible to use wildcard interface name (asterisk) concurrently
with explicit interface names:
<screen>
"Dhcp4": {
<userinput>
"interfaces": [ "eth1", "eth3", "*" ]
</userinput>
, ... }
</screen>
"Dhcp4": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1", "eth3", "*"
</userinput>
]
},
...
}
</screen>
It is anticipated that this form of usage will only be used when it is desired to
temporarily override a list of interface names and listen on all interfaces.
</para>
...
...
@@ -357,10 +382,60 @@ temporarily override a list of interface names and listen on all interfaces.
instance should be bound to a different address on the particular interface.
In these situations, the address to use can be selected by
appending an IPv4 address to the interface name in the following manner:
<screen>
"Dhcp4": {
<userinput>
"interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ]
</userinput>
, ... }
</screen>
<screen>
"Dhcp4": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1/10.0.0.1", "eth3/192.0.2.3"
</userinput>
]
},
...
}
</screen>
Note that only one address can be specified on each interface.
</para>
<para>
Kea supports responding to directly connected clients which don't have
an address configured on the interface yet. This requires that the server
injects the hardware address of the destination into the data link layer
of the packet being sent to the client. The DHCPv4 server utilizes the
raw sockets to achieve this, and builds the entire IP/UDP stack for the
outgoing packets. The down side of raw socket use, however, is that incoming
and outgoing packets bypass the firewalls (e.g. iptables). It is also
troublesome to handle traffic on multiple IPv4 addresses assigned to the
same interface, as raw sockets are bound to the interface and advanced
packet filtering techniques (e.g. using the BPF) have to be used to
receive unicast traffic on the desired addresses assigned to the interface,
rather than capturing whole traffic reaching the interface to which the raw
socket is bound. Therefore, in the deployments where the server doesn't
have to provision the directly connected clients and only receives the
unicast packets from the relay agents, it is desired to configure the
DHCP server to utilize the IP/UDP datagram sockets, instead of raw sockets.
The following configuration demonstrates how this can be achieved:
<screen>
"Dhcp4": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1", "eth3"
</userinput>
],
"socket-type": "datagram"
},
...
}
</screen>
The
<command>
socket-type
</command>
specifies that the datagram sockets will
be opened on all interfaces on which the server listens, i.e. "eth1" and
"eth3" in our case. If the
<command>
socket-type
</command>
is set to
<userinput>
raw
</userinput>
, it configures the server to use raw sockets
instead. If the
<command>
socket-type
</command>
value is not specified, the
default value
<userinput>
raw
</userinput>
is used.
</para>
<note>
<para>
Specifying the value
<userinput>
raw
</userinput>
as the socket type,
doesn't guarantee that the raw sockets will be used! The use of raw sockets
to handle the traffic from the directly connected clients is currently
supported on Linux and BSD systems only. If the raw sockets are not
supported on the particular OS, the server will issue a warning and
fall back to use the datagram sockets.
</para>
</note>
</section>
<section
id=
"ipv4-subnet-id"
>
...
...
doc/guide/dhcp6-srv.xml
View file @
51637af1
...
...
@@ -92,13 +92,17 @@
"Dhcp6": {
# First we set up global values
"interfaces": [ "eth0" ],
"renew-timer": 1000,
"rebind-timer": 2000,
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
# Next we specify the type of lease database
# Next we setup the interfaces to be used by the server.
"interfaces-config": {
"interfaces": [ "eth0" ]
},
# And we specify the type of a lease database
"lease-database": {
"type": "memfile",
"persist": true,
...
...
@@ -156,19 +160,8 @@ ignored. This is unlikely to cause any confusion as there are no real life
reasons to keep multiple copies of the same parameter in your configuration
file.
</para>
<para>
Moving onto the DHCPv6 configuration elements,
the line defining
<command>
interfaces
</command>
parameter specifies a list
of network interfaces on which the server should listen.
Lists are opened and closed with square brackets, with elements
separated by commas. Had we wanted to listen on two interfaces, the line could
look like this:
<screen>
"interfaces": [ "eth0", "eth1" ],
</screen>
As "
<command>
interfaces
</command>
" is not the last parameter in the
configuration, a trailing comma is required.
</para>
<para>
A number of other parameters follow.
<command>
valid-lifetime
</command>
<para>
Moving onto the DHCPv6 configuration elements, the very first few elements
define some global parameters.
<command>
valid-lifetime
</command>
defines for how long the addresses (leases) given out by the server are valid. If
nothing changes, a client that got an address is allowed to use it for 4000
seconds. (Note that integer numbers are specified as is, without any quotes
...
...
@@ -178,6 +171,20 @@ connections). <command>renew-timer</command> and <command>
rebind-timer
</command>
are values that define T1 and T2 timers that govern when
the client will begin the renewal and rebind procedures.
</para>
<para>
The
<command>
interfaces-config
</command>
map specifies the server
configuration concerning the network interfaces, on which the server should
listen to the DHCP messages. The
<command>
interfaces
</command>
parameter
specifies a list of network interfaces on which the server should listen.
Lists are opened and closed with square brackets, with elements separated
by commas. Had we wanted to listen on two interfaces, the
<command>
interfaces-config
</command>
would look like this:
<screen>
"interfaces-config": {
"interfaces": [ "eth0", "eth1" ]
},
</screen>
</para>
<para>
The next couple of lines define the lease database, the place where the server
stores its lease information. This particular example tells the server to use
<command>
memfile
</command>
, which is the simplest (and fastest) database
...
...
@@ -339,19 +346,37 @@ JSON validator is available at <ulink url="http://jsonviewer.stack.hu/"/>.
<section
id=
"dhcp6-interface-selection"
>
<title>
Interface selection
</title>
<para>
The DHCPv6 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration
tell
s the server to
interfaces. The simplest network interface configuration
instruct
s the server to
listen on all available interfaces:
<screen>
"Dhcp6": {
<userinput>
"interfaces": ["*"]
</userinput>
, ... }
</screen>
"Dhcp6": {
"interfaces-config": {
"interfaces": [
<userinput>
"*"
</userinput>
]
}
...
}
</screen>
The asterisk plays the role of a wildcard and means "listen on all interfaces".
However, it is usually a good idea to explicitly specify interface names:
<screen>
"Dhcp6": {
<userinput>
"interfaces": [ "eth1", "eth3" ]
</userinput>
, ... }
</screen>
</para>
"Dhcp6": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1", "eth3"
</userinput>
]
},
...
}
</screen>
</para>
<para>
It is possible to use wildcard interface name (asterisk) concurrently
with
explicit
interface names:
with
the actual
interface names:
<screen>
"Dhcp6": {
<userinput>
"interfaces": [ "eth1", "eth3", "*" ]
</userinput>
, ... }
</screen>
"Dhcp6": {
"interfaces-config": {
"interfaces": [
<userinput>
"eth1", "eth3", "*"
</userinput>
]
},
...
}
</screen>
It is anticipated that this will form of usage only be used where it is desired to
temporarily override a list of interface names and listen on all interfaces.
</para>
...
...
@@ -413,23 +438,26 @@ temporarily override a list of interface names and listen on all interfaces.
notation to specify interfaces has been extended. An interface name can be
optionally followed by a slash, followed by the global unicast address on which
the server should listen. This will be done in addition to normal
link-local binding + listening on ff02::1:2 address. The sample co
mmands
listed
below show how to listen on 2001:db8::1 (a global address)
link-local binding + listening on ff02::1:2 address. The sample co
nfiguration
below show
s
how to listen on 2001:db8::1 (a global address)
configured on the eth1 interface.
</para>
<para>
<screen>
"Dhcp6": {
<userinput>
"interfaces": [ "eth1/2001:db8::1"],
</userinput>
"interfaces-config": {
"interfaces": [
<userinput>
"eth1/2001:db8::1"
</userinput>
]
},
...
}
</screen>
}
</screen>
When t
his configuration
gets committed, the server will start
to listen on
T
his configuration
will cause the server
to listen on
eth1 on link-local address, multicast group (ff02::1:2) and 2001:db8::1.
</para>
<para>
It is possible to mix interface names, wildcards and interface name/addresses
on the
Dhcp6/
interface
list
. It is not possible to specify more than one
on the
list of
interface
s
. It is not possible to specify more than one
unicast address on a given interface.
</para>
<para>
...
...
@@ -1771,7 +1799,9 @@ should include options from the isc option space:
such a configuration:
<screen>
"Dhcp6": {
"interfaces": [ "ethX" ],
"interfaces-config": {
"interfaces": [ "ethX" ]
},
<userinput>
"option-data": [ {
"name": "dns-servers",
"data": "2001:db8::1, 2001:db8::2"
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment