Skip to content

GitLab

Commit a4ca9897 authored by Stephen Morris's avatar Stephen Morris
Browse files
Options

[4844] Editing pass over first seven chapters of the Kea guide

parent 79d4f00a
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 464 additions and 475 deletions
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 checking the version of the
the database and checks for this by examining 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> &mdash;
Initializes a new lease database. Useful during first
Initializes a new lease database. This is useful 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> &mdash;
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> &mdash;
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> &mdash;
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>
Memfile backend is able to store lease information, but is not able to
store host reservation details. There are no plans to add the
reservations storage capability to memfile. Host reservations can be
defined in the configuration file.
The memfile backend is able to store lease information, but is not able to
store host reservation details: these 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 no special initialization steps necessary
No 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. Please use
with caution. CQL backend is currently able to store leases only. The
testing as other backends, it is considered experimental: please 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 Kea Database</title>
<title>First Time Creation of the Cassandra 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 read only databases with host reservations</title>
<para>If read only database is used for storing host reservations,
<title>Using Read-Only Databases with Host Reservations</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 related to the use of the SQL databases</title>
<title>Limitations Related to the use of SQL Databases</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 "&#x2014;" >
]>
<chapter id="kea-config">
<title>Kea configuration</title>
<title>Kea Configuration</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 configuration backend</title>
<title>JSON Configuration Backend</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 syntax</title>
<title>JSON Syntax</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.
doc/guide/install.xml
View file @ a4ca9897
This diff is collapsed.
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 cryptographic 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> &mdash;
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> &mdash;
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> &mdash;
DHCP-DDNS 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 servers. 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> &mdash;
A tool useful for database backend maintenance (creating new
A useful tool for database backend maintenance (creating a new
database, checking versions, upgrading etc.)
</simpara>
</listitem>
......@@ -159,17 +159,16 @@
<command>kea-lfc</command> &mdash;
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> &mdash;
DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 servers 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 start</title>
<title>Quick Start</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 start guide for DHCPv4 and DHCPv6 services</title>
<title>Quick Start Guide for DHCPv4 and DHCPv6 Services</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">System specific notes</ulink>,
available on <ulink url="http://kea.isc.org/">Kea homepage</ulink>.
For instructions specific to your system, please read the
<ulink url="http://kea.isc.org/wiki/SystemSpecificNotes">system specific notes</ulink>,
available on the <ulink url="http://kea.isc.org/">Kea web site</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 servers directly</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 Servers Directly</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>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment