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

doc/guide/admin.xml

@@ -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>

doc/guide/dhcp4-srv.xml

@@ -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">

doc/guide/dhcp6-srv.xml

@@ -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>