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
ISC Open Source Projects
Kea
Commits
a4ca9897
Commit
a4ca9897
authored
Sep 18, 2016
by
Stephen Morris
Browse files
[4844] Editing pass over first seven chapters of the Kea guide
parent
79d4f00a
Changes
7
Expand all
Hide whitespace changes
Inline
Side-by-side
doc/guide/admin.xml
View file @
a4ca9897
...
...
@@ -16,17 +16,19 @@
the several supported databases. As future versions of Kea
are released, the structure of those databases will change.
For example, Kea currently only stores lease information
and host reservations: in the future, additional
data - such as subnet definitions - will also be stored.
and host reservations. Future versions of Kea will store
additional data such as subnet definitions: the database
structure will need to be updated to accomdate the extra
information.
</para>
<para>
A given version of Kea expects a particular structure in
the database
. It ensures
this by
check
ing the version of
the
the database
and checks for
this by
examin
ing the version of
database it is using. Separate version numbers are maintained for
backend databases, independent of the version of Kea itself. It
is possible that the backend database version will stay the same
through several Kea revisions
. Likewise
, it is possible that the
through several Kea revisions
: similarly
, it is possible that the
version of backend database may go up several revisions during a
Kea upgrade. Versions for each database are independent, so an
increment in the MySQL database version does not imply an increment
...
...
@@ -70,9 +72,10 @@
<listitem>
<simpara>
<command>
lease-init
</command>
—
Initializes a new lease database.
U
seful during
first
Initializes a new lease database.
This is u
seful during
a new
Kea installation. The database is initialized to the
latest version supported by the version of the software.
latest version supported by the version of the software being
installed.
</simpara>
</listitem>
...
...
@@ -97,9 +100,10 @@
<simpara>
<command>
lease-dump
</command>
—
Dumps the contents of the lease database (for MySQL, PostgreSQL or
CQL backends) to CSV text file. The first line of the file contains
the column names. This is meant to be used as a diagnostic tool
that provides a portable, human-readable form of lease data.
CQL backends) to a CSV (comma separated values) text file. The first
line of the file contains the column names. This is meant to be
used as a diagnostic tool, so provides a portable, human-readable
form of the lease data.
</simpara>
</listitem>
</itemizedlist>
...
...
@@ -118,16 +122,14 @@
<listitem>
<simpara>
<command>
mysql
</command>
—
Lease information is stored in a MySQL relational
database.
Lease information is stored in a MySQL relational database.
</simpara>
</listitem>
<listitem>
<simpara>
<command>
pgsql
</command>
—
Lease information is stored in a PostgreSQL relational
database.
Lease information is stored in a PostgreSQL relational database.
</simpara>
</listitem>
...
...
@@ -142,7 +144,7 @@
Additional parameters may be needed, depending on your setup
and specific operation: username, password and database name or
the directory where specific files are located. See appropriate
the directory where specific files are located. See
the
appropriate
manual page for details (
<command>
man 8 kea-admin
</command>
).
</para>
</section>
...
...
@@ -185,7 +187,7 @@
<row>
<entry>
Data format
</entry>
<entry>
coma separated
file
</entry>
<entry>
CSV
file
</entry>
<entry>
SQL RMDB
</entry>
<entry>
SQL RMDB
</entry>
<entry>
NoSQL database (CQL)
</entry>
...
...
@@ -224,14 +226,14 @@
<title>
memfile
</title>
<para>
M
emfile backend is able to store lease information, but is not able to
store host reservation details
. T
he
r
e
are no plans to add the
reservations storage capability to
memfile. Host reservations can be
defined in the configuration file.
The m
emfile backend is able to store lease information, but is not able to
store host reservation details
: t
he
s
e
must be stored in the configuration
file. (There are no plans to add a host
reservations storage capability to
this backend.)
</para>
<para>
There are n
o special initialization steps necessary
N
o special initialization steps
are
necessary
for the memfile backend. During the first run, both
<command>
kea-dhcp4
</command>
and
<command>
kea-dhcp6
</command>
will create an empty lease file if one is not
...
...
@@ -267,17 +269,12 @@
<para>
MySQL is able to store leases, host reservations and options defined on
a per host basis.
</para>
<para>
The MySQL database must be properly set up if you want Kea to
store information in MySQL. This section can be safely ignored
a per host basis. This section can be safely ignored
if you chose to store the data in other backends.
</para>
<section
id=
"mysql-database-create"
>
<title>
First Time Creation of
Kea
Database
</title>
<title>
First Time Creation of
the MySQL
Database
</title>
<para>
If you are setting the MySQL database for the first time,
...
...
@@ -418,7 +415,7 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
</para>
<section
id=
"pgsql-database-create"
>
<title>
Manually Create
the PostgreSQL Database
and the Kea User
</title>
<title>
First Time Creation of
the PostgreSQL Database
</title>
<para>
The first task is to create both the lease database and the
...
...
@@ -458,7 +455,6 @@ postgres=#
<screen>
postgres=#
<userinput>
CREATE USER
<replaceable>
user-name
</replaceable>
WITH PASSWORD '
<replaceable>
password
</replaceable>
';
</userinput>
CREATE ROLE
postgres=#
postgres=#
<userinput>
GRANT ALL PRIVILEGES ON DATABASE
<replaceable>
database-name
</replaceable>
TO
<replaceable>
user-name
</replaceable>
;
</userinput>
GRANT
postgres=#
...
...
@@ -594,8 +590,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
<para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend
added to Kea. Since it was added recently and has not undergone as much
testing as other backends, it is considered experimental
. P
lease use
with caution. CQL backend is currently able to store leases only. The
testing as other backends, it is considered experimental
: p
lease use
with caution.
The
CQL backend is currently able to store leases only. The
ability to store host reservations will likely be added some time in the
future.
</para>
...
...
@@ -607,7 +603,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
</para>
<section
id=
"cql-database-create"
>
<title>
First Time Creation of
Ke
a Database
</title>
<title>
First Time Creation of
the Cassandr
a Database
</title>
<para>
If you are setting up the CQL database for the first time, you need to
...
...
@@ -713,19 +709,19 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</section>
<!-- end of CQL sections -->
<section>
<title>
Using
r
ead
o
nly
d
atabases with
h
ost
r
eservations
</title>
<para>
If read
only database is used for storing host reservations,
<title>
Using
R
ead
-O
nly
D
atabases with
H
ost
R
eservations
</title>
<para>
If
a
read
-
only database is used for storing host reservations,
Kea must be explicitly configured to operate on the database in
the
read
only mode.
read
-
only mode.
Sections
<xref
linkend=
"read-only-database-configuration4"
/>
and
<xref
linkend=
"read-only-database-configuration6"
/>
describe when
such configuration may be reqired and how to configure Kea to
operate using read
only host database.
operate using
a
read
-
only host database.
</para>
</section>
<section>
<title>
Limitations
r
elated to the use of
the
SQL
d
atabases
</title>
<title>
Limitations
R
elated to the use of SQL
D
atabases
</title>
<para>
The lease expiration time is stored in the SQL database for each lease
...
...
@@ -738,6 +734,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
maximum signed 32-bit number. This effectively means that the current
Kea version can't store the leases which expiration time is later than
2147483647 seconds since the beginning of the epoch (around year 2038).
This will be fixed when the database support for longer timestamps
is available.
</para>
</section>
...
...
doc/guide/config.xml
View file @
a4ca9897
...
...
@@ -4,7 +4,7 @@
<!ENTITY mdash "—" >
]>
<chapter
id=
"kea-config"
>
<title>
Kea
c
onfiguration
</title>
<title>
Kea
C
onfiguration
</title>
<para>
Kea is designed to allow different methods by which it can be
configured, each method being implemented by a component known as a
...
...
@@ -12,7 +12,7 @@
available, that allowing configuration by means of a JSON file.
</para>
<section
id=
"json-backend"
>
<title>
JSON
c
onfiguration
b
ackend
</title>
<title>
JSON
C
onfiguration
B
ackend
</title>
<para>
JSON is the default configuration backend.
It assumes that the servers are started from the command line
(either directly or using a script, e.g.
<filename>
keactrl
</filename>
).
...
...
@@ -20,11 +20,11 @@
configuration file is specified upon startup using the -c parameter.
</para>
<section
id=
"json-format"
>
<title>
JSON
s
yntax
</title>
<title>
JSON
S
yntax
</title>
<para>
Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in
<ulink
url=
"http://tools.ietf.org/html/rfc4627"
>
RFC 4627
</ulink>
. Kea components
use a slightly modified JSON
,
in that they allow shell-style
use a slightly modified
form of
JSON in that they allow shell-style
comments in the file: lines with the hash (#) character in the first column
are comment lines and are ignored.
</para>
...
...
@@ -38,8 +38,8 @@
Logging object to configure logging parameters; it will ignore the Dhcp6
object.
</para>
<para>
For example, a
very simple configuration for both DHCPv4 and
DHCPv6
could look like this:
<para>
A
very simple configuration for both DHCPv4 and
DHCPv6
could look like this:
<screen>
# The whole configuration starts here.
{
...
...
@@ -56,8 +56,7 @@
"subnet4": [{
"pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
"subnet": "192.0.2.0/24"
}],
...
}]
},
# DHCPv4 specific configuration ends here.
...
...
@@ -73,8 +72,7 @@
"subnet6": [{
"pools": [ { "pool": "2001:db8::/80" } ],
"subnet": "2001:db8::/64"
}],
...
}]
},
# DHCPv6 specific configuration ends here.
...
...
@@ -84,8 +82,7 @@
"loggers": [{
"name": "*",
"severity": "DEBUG"
}],
...
}]
}
# Logger parameters end here.
...
...
@@ -103,7 +100,7 @@
DHCPv6, only subnet6 parameters will be mentioned. It is implied that
the remaining elements (the global map that holds Dhcp6, Logging and possibly
DhcpDdns) are present, but they are omitted for clarity. Usually, locations
where extra parameters may appear are denoted
with
an ellipsis.
</para>
where extra parameters may appear are denoted
by
an ellipsis.
</para>
</section>
<section>
...
...
doc/guide/dhcp4-srv.xml
View file @
a4ca9897
This diff is collapsed.
Click to expand it.
doc/guide/install.xml
View file @
a4ca9897
This diff is collapsed.
Click to expand it.
doc/guide/intro.xml
View file @
a4ca9897
...
...
@@ -55,13 +55,13 @@
<listitem>
<simpara>
Kea supports two crypto libraries: Botan and OpenSSL. Only one of
them
is required to be installed during compilation.
Kea uses the
Botan
crypto library for C++ (
<ulink
url=
"http://botan.randombit.net/"
/>
),
version 1.8, 1.9 or 1.10. As an alternative to Botan, Kea can use the
OpenSSL
crypto library
(
<ulink
url=
"http://www.openssl.org/"
/>
),
version 1.0.*. Support for later versions of Botan and OpenSSL will
be added in future releases of Kea.
Kea supports two crypto
graphic
libraries: Botan and OpenSSL. Only one of
them
is required to be installed during compilation.
If using
Botan
, Kea
requires the Botan cryptographic library for C++ (
<ulink
url=
"http://botan.randombit.net/"
/>
), version 1.8, 1.9 or 1.10. If
OpenSSL
is used,
(
<ulink
url=
"http://www.openssl.org/"
/>
),
then Kea
requires the OpenSSL C++ library version 1.0.*. Support for later
versions of Botan and OpenSSL will
be added in future releases of Kea.
</simpara>
</listitem>
...
...
@@ -69,7 +69,7 @@
<simpara>
Kea uses the log4cplus C++ logging library
(
<ulink
url=
"http://log4cplus.sourceforge.net/"
/>
).
It requires
at least
log4cplus version 1.0.3.
It requires log4cplus version 1.0.3
or later
.
</simpara>
</listitem>
...
...
@@ -123,7 +123,7 @@
<listitem>
<simpara>
<command>
kea-dhcp4
</command>
—
DHCPv4 server process.
The
DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
...
...
@@ -131,7 +131,7 @@
<listitem>
<simpara>
<command>
kea-dhcp6
</command>
—
DHCPv6 server process.
The
DHCPv6 server process.
This process responds to DHCPv6 queries from clients.
</simpara>
</listitem>
...
...
@@ -139,9 +139,9 @@
<listitem>
<simpara>
<command>
kea-dhcp-ddns
</command>
—
DHCP-D
DNS process.
The DHCP Dynamic
DNS process.
This process acts as an intermediary between the DHCP servers
and DNS server. It receives name update requests from the DHCP
and DNS server
s
. It receives name update requests from the DHCP
servers and sends DNS Update messages to the DNS servers.
</simpara>
</listitem>
...
...
@@ -149,7 +149,7 @@
<listitem>
<simpara>
<command>
kea-admin
</command>
—
A
tool
useful for database backend maintenance (creating new
A usefu
l too
l for database backend maintenance (creating
a
new
database, checking versions, upgrading etc.)
</simpara>
</listitem>
...
...
@@ -159,17 +159,16 @@
<command>
kea-lfc
</command>
—
This process removes redundant information from the files used
to provide persistent storage for the memfile data base backend.
The service is written to run as a stand alone process. While it
can be started externally it should be started by the Kea DHCP
servers.
While it can be run standalone, it is normally run as and when
required by the Kea DHCP servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>
perfdhcp
</command>
—
DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 server
s
performance.
A
DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 server performance.
</simpara>
</listitem>
...
...
doc/guide/keactrl.xml
View file @
a4ca9897
...
...
@@ -139,8 +139,7 @@ kea_verbose=no
<section
id=
"keactrl-commands"
>
<title>
Commands
</title>
<para>
The following commands are supported by
<command>
keactrl
</command>
to perform specific operations on the Kea servers:
<para>
The following commands are supported by
<command>
keactrl
</command>
:
<itemizedlist>
<listitem><simpara>
<command>
start
</command>
- starts selected servers.
...
...
doc/guide/quickstart.xml
View file @
a4ca9897
...
...
@@ -7,16 +7,16 @@
]>
<chapter
id=
"quickstart"
>
<title>
Quick
s
tart
</title>
<title>
Quick
S
tart
</title>
<para>
This
quickly covers the standard steps for installing and deploying Kea
.
This
section describes the basic steps needed to get Kea up and running
.
For further details, full customizations, and troubleshooting, see the
respective chapters in the Kea guide.
</para>
<section
id=
"quick-start"
>
<title>
Quick
s
tart
g
uide for DHCPv4 and DHCPv6
s
ervices
</title>
<title>
Quick
S
tart
G
uide for DHCPv4 and DHCPv6
S
ervices
</title>
<orderedlist>
...
...
@@ -54,8 +54,9 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
</listitem>
<listitem>
<para>
Install it (by default the installation prefix is
<filename>
/usr/local/
</filename>
,
so you likely need root privileges for that step):
<para>
Install it (by default it will be placed in
<filename>
/usr/local/
</filename>
,
so it is likely that you will need root privileges for this step):
<screen>
#
<userinput>
make install
</userinput></screen>
</para>
</listitem>
...
...
@@ -64,7 +65,8 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<para>
Edit the configuration file which by default is installed in
<filename>
[kea-install-dir]/etc/kea/kea.conf
</filename>
and contains
configuration for all Kea services. Configuration choices for DHCPv4
and DHCPv6 services are described in
<xref
linkend=
"dhcp4-configuration"
/>
and
<xref
linkend=
"dhcp6-configuration"
/>
, respectively.
</para>
and DHCPv6 services are described in
<xref
linkend=
"dhcp4-configuration"
/>
and
<xref
linkend=
"dhcp6-configuration"
/>
:w
respectively.
</para>
</listitem>
<listitem>
...
...
@@ -81,10 +83,11 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem>
<para>
Verify that Kea server(s) are running:
<screen>
#
<userinput>
keactrl status
</userinput></screen>
If the server status is "inactive" may indicate a configuration
error. Please check a log file (by default located in
<filename>
[kea-install-dir]/var/kea/kea.log
</filename>
) for the
details of the error.
A server status of "inactive" may indicate a configuration
error. Please check the log file (by default named
<filename>
[kea-install-dir]/var/kea/kea-dhcp4.log
</filename>
or
<filename>
[kea-install-dir]/var/kea/kea-dhcp6.log
</filename>
)
for the details of the error.
</para>
</listitem>
...
...
@@ -99,15 +102,15 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem>
<para>
Stop running server(s):
Stop running
the
server(s):
<screen>
#
<userinput>
keactrl stop
</userinput></screen>
</para>
</listitem>
</orderedlist>
<para>
For
more system specific installation procedures, you may want to visit
<ulink
url=
"http://kea.isc.org/wiki/SystemSpecificNotes"
>
S
ystem specific notes
</ulink>
,
available on
<ulink
url=
"http://kea.isc.org/"
>
Kea
homepag
e
</ulink>
.
For
instructions specific to your system, please read the
<ulink
url=
"http://kea.isc.org/wiki/SystemSpecificNotes"
>
s
ystem specific notes
</ulink>
,
available on
the
<ulink
url=
"http://kea.isc.org/"
>
Kea
web sit
e
</ulink>
.
</para>
<para>
The details of
<command>
keactrl
</command>
script usage can be found
...
...
@@ -115,12 +118,12 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
</section>
<section
id=
"quick-start-direct-run"
>
<title>
Running Kea
s
ervers
d
irectly
</title>
<para>
Kea servers can be started directly
(
without
a
need to use
<command>
keactrl
</command>
)
. To start DHCPv4 server run the following
<title>
Running
the
Kea
S
ervers
D
irectly
</title>
<para>
The
Kea servers can be started directly
,
without
the
need to use
the
<command>
keactrl
</command>
. To start
the
DHCPv4 server run the following
command:
<screen>
#
<userinput>
kea-dhcp4 -c /path/to/your/kea4/config/file.json
</userinput></screen>
And
, to start the DHCPv6 server run the following command:
Similarly
, to start the DHCPv6 server run the following command:
<screen>
#
<userinput>
kea-dhcp6 -c /path/to/your/kea6/config/file.json
</userinput></screen>
</para>
</section>
...
...
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