Port Gitlab MR !1887 to 2.2.x

ChangeLog

@@ -1,3 +1,12 @@
+2046.	[func]		marcin
+	New database connection parameters, "read-timeout" and
+	"write-timeout", control the timeouts in communication with the
+	MySQL database. The "tcp-user-timeout" controls the timeout in
+	communication with the PostgreSQL database. Setting these
+	timeouts can prevent occasional Kea hangs due to issues with
+	the database connectivity.
+	(Gitlab #2688)
+
 Kea 2.2.0 (stable) released on July 27, 2022
 
 2045.	[build]		tmark

doc/examples/kea4/all-keys.json

@@ -349,7 +349,11 @@
                 "type": "postgresql",
 
                 // User name to be used to access the database.
-                "user": "keatest"
+                "user": "keatest",
+
+                // TCP user timeout while communicating with the database.
+                // It is specified in seconds.
+                "tcp-user-timeout": 100
             },
             {
                 // Name of the database to connect to.
@@ -381,8 +385,14 @@
                 // serve-retry-continue
                 "on-fail": "stop-retry-exit",
 
-                // Connection connect timeout.
-                "connect-timeout": 100
+                // Connection connect timeout in seconds.
+                "connect-timeout": 100,
+
+                // Data read from the database timeout in seconds.
+                "read-timeout": 120,
+
+                // Data write to the database timeout in seconds.
+                "write-timeout": 180
             }
         ],
 

doc/examples/kea6/all-keys.json

@@ -308,7 +308,11 @@
                 "type": "postgresql",
 
                 // User name to be used to access the database.
-                "user": "keatest"
+                "user": "keatest",
+
+                // TCP user timeout while communicating with the database.
+                // It is specified in seconds.
+                "tcp-user-timeout": 100
             },
             {
                 // Name of the database to connect to.
@@ -340,8 +344,14 @@
                 // serve-retry-continue
                 "on-fail": "stop-retry-exit",
 
-                // Connection connect timeout.
-                "connect-timeout": 100
+                // Connection connect timeout in seconds.
+                "connect-timeout": 100,
+
+                // Data read from the database timeout in seconds.
+                "read-timeout": 120,
+
+                // Data write to the database timeout in seconds.
+                "write-timeout": 180
             }
         ],
 

doc/sphinx/arm/dhcp4-srv.rst

@@ -548,6 +548,57 @@ access the database should be set:
 If there is no password to the account, set the password to the empty
 string ``""``. (This is the default.)
 
+.. _tuning-database-timeouts4:
+
+Tuning Database Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In rare cases, reading or writing to the database may hang. It can be
+caused by a temporary network issue or misconfiguration of the proxy
+server switching the connection between different database instances.
+These situations are rare, but we have received reports from the users
+that Kea can sometimes hang while performing the database IO operations.
+Setting appropriate timeout values can mitigate such issues.
+
+MySQL exposes two distinct connection options to configure the read and
+write timeouts. Kea's corresponding ``read-timeout`` and  ``write-timeout``
+configuration parameters specify the timeouts in seconds. For example:
+
+::
+
+   "Dhcp4": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }
+
+
+Setting these parameters to 0 is equivalent to not specifying them and
+causes the Kea server to establish a connection to the database with the
+MySQL defaults. In this case, Kea waits infinitely for the completion of
+the read and write operations.
+
+MySQL versions earlier than 5.6 do not support setting timeouts for the
+read and write operations. Moreover, the ``read-timeout`` and ``write-timeout``
+parameters can only be specified for the MySQL backend. Setting them for
+any other backend type causes a configuration error.
+
+Use the ``tcp-user-timeout`` parameter to set a timeout for PostgreSQL
+in seconds. For example:
+
+::
+
+   "Dhcp4": { "lease-database": { "tcp-user-timeout" : 10, ... }, ... }
+
+
+Specifying this parameter for other backend types causes a configuration
+error.
+
+.. note::
+
+    The timeouts described here are only effective for TCP connections.
+    Please note that the MySQL client library used by the Kea servers
+    typically connects to the database via a UNIX domain socket when the
+    ``host`` parameter is ``localhost`` but establishes a TCP connection
+    for ``127.0.0.1``.
+
+
 .. _hosts4-storage:
 
 Hosts Storage
@@ -763,6 +814,12 @@ the parameter is not specified.
    The ``readonly`` parameter is only supported for MySQL and
    PostgreSQL databases.
 
+
+Tuning Database Timeouts for Hosts Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`tuning-database-timeouts4`.
+
 .. _dhcp4-interface-configuration:
 
 Interface Configuration

doc/sphinx/arm/dhcp6-srv.rst

@@ -505,6 +505,57 @@ access the database should be set:
 If there is no password to the account, set the password to the empty
 string ``""``. (This is the default.)
 
+.. _tuning-database-timeouts6:
+
+Tuning Database Timeouts
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In rare cases, reading or writing to the database may hang. It can be
+caused by a temporary network issue or misconfiguration of the proxy
+server switching the connection between different database instances.
+These situations are rare, but we have received reports from the users
+that Kea can sometimes hang while performing the database IO operations.
+Setting appropriate timeout values can mitigate such issues.
+
+MySQL exposes two distinct connection options to configure the read and
+write timeouts. Kea's corresponding ``read-timeout`` and  ``write-timeout``
+configuration parameters specify the timeouts in seconds. For example:
+
+::
+
+   "Dhcp6": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }
+
+
+Setting these parameters to 0 is equivalent to not specifying them and
+causes the Kea server to establish a connection to the database with the
+MySQL defaults. In this case, Kea waits infinitely for the completion of
+the read and write operations.
+
+MySQL versions earlier than 5.6 do not support setting timeouts for the
+read and write operations. Moreover, the ``read-timeout`` and ``write-timeout``
+parameters can only be specified for the MySQL backend. Setting them for
+any other backend type causes a configuration error.
+
+Use the ``tcp-user-timeout`` parameter to set a timeout for PostgreSQL
+in seconds. For example:
+
+::
+
+   "Dhcp6": { "lease-database": { "tcp-user-timeout" : 10, ... }, ... }
+
+
+Specifying this parameter for other backend types causes a configuration
+error.
+
+.. note::
+
+    The timeouts described here are only effective for TCP connections.
+    Please note that the MySQL client library used by the Kea servers
+    typically connects to the database via a UNIX domain socket when the
+    ``host`` parameter is ``localhost`` but establishes a TCP connection
+    for ``127.0.0.1``.
+
+
 .. _hosts6-storage:
 
 Hosts Storage
@@ -720,6 +771,13 @@ the parameter is not specified.
    The ``readonly`` parameter is only supported for MySQL and
    PostgreSQL databases.
 
+
+Tuning Database Timeouts for Hosts Storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See :ref:`tuning-database-timeouts6`.
+
+
 .. _dhcp6-interface-configuration:
 
 Interface Configuration

src/bin/agent/tests/parser_unittests.cc

@@ -11,6 +11,7 @@
 #include <cc/dhcp_config_error.h>
 #include <testutils/io_utils.h>
 #include <testutils/log_utils.h>
+#include <testutils/test_to_element.h>
 #include <testutils/user_context_utils.h>
 
 #include <gtest/gtest.h>
@@ -37,7 +38,11 @@ namespace test {
 void compareJSON(ConstElementPtr a, ConstElementPtr b) {
     ASSERT_TRUE(a);
     ASSERT_TRUE(b);
-    EXPECT_EQ(a->str(), b->str());
+    EXPECT_EQ(a->str(), b->str())
+#ifdef HAVE_CREATE_UNIFIED_DIFF
+        << "\nDiff:\n" << generateDiff(prettyPrint(a), prettyPrint(b)) << "\n"
+#endif
+    ;
 }
 
 /// @brief Tests if the input string can be parsed with specific parser

src/bin/d2/tests/parser_unittest.cc

@@ -10,6 +10,7 @@
 #include <d2/tests/parser_unittest.h>
 #include <testutils/io_utils.h>
 #include <testutils/log_utils.h>
+#include <testutils/test_to_element.h>
 #include <testutils/user_context_utils.h>
 
 #include <gtest/gtest.h>
@@ -38,7 +39,11 @@ namespace test {
 void compareJSON(ConstElementPtr a, ConstElementPtr b) {
     ASSERT_TRUE(a);
     ASSERT_TRUE(b);
-    EXPECT_EQ(a->str(), b->str());
+    EXPECT_EQ(a->str(), b->str())
+#ifdef HAVE_CREATE_UNIFIED_DIFF
+        << "\nDiff:\n" << generateDiff(prettyPrint(a), prettyPrint(b)) << "\n"
+#endif
+    ;
 }
 
 /// @brief Tests if the input string can be parsed with specific parser