Commit fe0424b0 authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[4489] Updated documentation for "readonly" database parameter.

parent 4e0e41f0
......@@ -11,11 +11,13 @@
<title>Databases and Database Version Numbers</title>
<para>
Kea stores leases in one of 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: in the future, additional data - such as host
reservation details - will also be stored.
Kea supports storing leases and host reservations (i.e. static
assignments of addresses, prefixes and options) in one of
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.
</para>
<para>
......@@ -705,6 +707,18 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</section>
</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,
Kea must be explicitly configured to operate on the database in
the read only mode.
Sections <xref linkend="read-only-database-configuration4"/> and
<xref linkend="read-only-database-configuration6"/> describe when
such configuration may be desired and how to configure Kea to
operate using read only host database.
</para>
</section>
<section>
<title>Limitations related to the use of the SQL databases</title>
......@@ -721,6 +735,7 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
2147483647 seconds since the beginning of the epoch (around year 2038).
</para>
</section>
</section> <!-- End of Database sections -->
</chapter>
......@@ -539,6 +539,38 @@ If a timeout is given though, it should be an integer greater than zero.
If there is no password to the account, set the password to the empty string
"". (This is also the default.)</para>
</section>
<section id="read-only-database-configuration4">
<title>Using Read Only Databases for Host Reservations</title>
<para>
In some deployments the database user, which name is specified in the database backend
configuration, may not have write privileges to the database. This is often
required by the policy within a given network to secure the data from being
unintentionally modified. In many cases administrators have inventory databases
deployed, which contain substantially more information about the hosts than
static reservations assigned to them. Such database can be used to create
a view of a Kea hosts database and such view is often read only.
</para>
<para>
Kea host database backends operate with implicit configuration to both read
and write from the database. If the host database is read only for the
particular user, the backend will fail to start and consequently the server
will refuse to start/reconfigure. If the administrator intends to use the
read only host database for retrieving reservations for clients, to assign
specific addresses and options, it is possible to explicitly configure
Kea to start in "read-only" mode. This is controlled by the
<command>readonly</command> boolean parameter as follows:
<screen>
"Dhcp4": { "hosts-database": { <userinput>"readonly": true</userinput>, ... }, ... }
</screen>
Setting this parameter to <userinput>false</userinput> would configure the
database backend to operate in "read-write" mode, which is also a default
configuration if the parameter is not specified.
</para>
<note><para>The <command>readonly</command> parameter is currently only supported
for MySQL and PostgreSQL databases.</para></note>
</section>
</section>
<section id="dhcp4-interface-configuration">
......
......@@ -477,6 +477,7 @@ If a timeout is given though, it should be an integer greater than zero.
If there is no password to the account, set the password to the empty string
"". (This is also the default.)</para>
</section>
</section>
<section id="hosts6-storage">
......@@ -539,8 +540,40 @@ If a timeout is given though, it should be an integer greater than zero.
If there is no password to the account, set the password to the empty string
"". (This is also the default.)</para>
</section>
<section id="read-only-database-configuration6">
<title>Using Read Only Databases for Host Reservations</title>
<para>
In some deployments the database user, which name is specified in the database backend
configuration, may not have write privileges to the database. This is often
required by the policy within a given network to secure the data from being
unintentionally modified. In many cases administrators have inventory databases
deployed, which contain substantially more information about the hosts than
static reservations assigned to them. Such database can be used to create
a view of a Kea hosts database and such view is often read only.
</para>
<para>
Kea host database backends operate with implicit configuration to both read
and write from the database. If the host database is read only for the
particular user, the backend will fail to start and consequently the server
will refuse to start/reconfigure. If the administrator intends to use the
read only host database for retrieving reservations for clients, to assign
specific addresses and options, it is possible to explicitly configure
Kea to start in "read-only" mode. This is controlled by the
<command>readonly</command> boolean parameter as follows:
<screen>
"Dhcp4": { "hosts-database": { <userinput>"readonly": true</userinput>, ... }, ... }
</screen>
Setting this parameter to <userinput>false</userinput> would configure the
database backend to operate in "read-write" mode, which is also a default
configuration if the parameter is not specified.
</para>
<note><para>The <command>readonly</command> parameter is currently only supported
for MySQL and PostgreSQL databases.</para></note>
</section>
</section>
-->
<section id="dhcp6-interface-selection">
<title>Interface selection</title>
......
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