From: Thomas Markwalder <tmark@isc.org>
Date: Mon, 26 Aug 2019 12:55:03 +0000 (-0400)
Subject: [#853, !26-p] Updated ARM
X-Git-Tag: Kea-1.6.0~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2d57ebe640fb844b167abdf1b5368e645b908b3b;p=thirdparty%2Fkea.git

[#853, !26-p] Updated ARM

    doc/sphinx/arm/admin.rst
---

diff --git a/doc/sphinx/arm/admin.rst b/doc/sphinx/arm/admin.rst
index b434715974..060d2e753a 100644
--- a/doc/sphinx/arm/admin.rst
+++ b/doc/sphinx/arm/admin.rst
@@ -211,17 +211,67 @@ To create the database:
    allow Kea access to the MySQL instance. All apostrophes in the
    command lines above are required.)
 
-4. At this point, administrators may elect to create the database tables.
-   (Alternatively, the tables can be created by exiting MySQL and using the
-   ``kea-admin`` tool, as explained below.) To do this:
+4. Create the database.
 
-   .. code-block:: mysql
+    You'll need to exit mysql client
+
+    .. code-block:: mysql
+
+      mysql> quit
+      Bye
+
+    and then use the  ``kea-admin`` tool to create the database.
+
+    .. code-block:: console
+
+        $ kea-admin db-init mysql -u database-user -p database-password -n database-name
+
+    While it is possible to create the database from within mysql client, we recommend you
+    use the kea-admin tool as it performs some necessary validations to ensure Kea can
+    access the database at runtime.  Among those checks is that the schema does not contain
+    any pre-existing tables.  If there are any pre-existing tables they must be removed
+    manaully.  An additional check examines the user's ability to create functions and
+    triggers.  If you encounter the following error
+
+    .. code-block:: console
+
+        ERROR 1419 (HY000) at line 1: You do not have the SUPER privilege and binary logging is
+        enabled (you *might* want to use the less safe log_bin_trust_function_creators variable)
+        ERROR/kea-admin: mysql_can_create cannot trigger, check user permissions, mysql status = 1
+        mysql: [Warning] Using a password on the command line interface can be insecure.
+        ERROR/kea-admin: Create failed, the user, keatest, has insufficient privileges.
+
+    Then user does not have the necessary permissions to create functions or triggers.
+    The simplest way around this is to set the global MySQL variable, log_bin_trust_function_creators to 1
+    via mysql client. Note you must do this as a user with SUPER privileges:
+
+    .. code-block:: mysql
+
+        mysql> set @@global.log_bin_trust_function_creators = 1;
+        Query OK, 0 rows affected (0.00 sec)
+
+    If you choose to create the database with mysql directly, you may do as as follows:
+
+    .. code-block:: mysql
 
       mysql> CONNECT database-name;
       mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
 
    (path-to-kea is the location where Kea is installed.)
 
+    The database may also be dropped as manually as follows:
+
+    .. code-block:: mysql
+
+      mysql> CONNECT database-name;
+      mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_drop.mysql
+
+   (path-to-kea is the location where Kea is installed.)
+
+.. warning::
+    Dropping the database will result in the unrecoverable loss of any data it contains.
+
+
 5. Exit MySQL:
 
    .. code-block:: mysql