[3080] Updated bind10-guide, corrected minor logging issues

The procedure for configuring Postgresql backend in bind10-guide
was updated such that database tables are created and thus owned
by the Kea user rather than the postgres user.

Cleaned up some logging issues and minor cosmetics.

doc/guide/bind10-guide.xml

@@ -3631,7 +3631,7 @@ $</screen>
           PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch,
           i.e.
           <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
-          ...if MySQL was installed in the default location, or:
+          ...if Postgresql was installed in the default location, or:
           <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
           ...if not.
         </para>
@@ -3654,47 +3654,70 @@ postgres=#</screen>
           <screen>postgres=# <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
           ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
         </para>
+
          <para>
-          3. Create the database tables:
-          <screen>postgres=# <userinput>\connect <replaceable>database-name</replaceable></userinput>
-postgres=#> <userinput>\i <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.pgsql</userinput></screen>
+          3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
+          <screen>postgres=# <userinput>CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD <replaceable>password</replaceable>;</userinput>
+postgres=#> <userinput>GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput></screen>
         </para>
+
          <para>
-          4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
-          <screen>postgres=# <userinput>CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
-postgres=#> <userinput>GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO '<replaceable>user-name</replaceable>;</userinput></screen>
-        </para>
-        <para>
-          5. Exit PostgreSQL:
+          4. Exit PostgreSQL:
           <screen>postgres=# <userinput>\q</userinput>
 Bye<userinput/>
 $</screen>
        </para>
-
-       <para>Try to log into the newly created database using keatest credentials:
-       <screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>keatest</replaceable></userinput>
-Password for user keatest:
-psql (9.1.12)
-Type "help" for help.
-
-keatest=>
+       <para>
+        5. Create the database tables using the new user's credentials.
+        After entering the following command, you will be prompted for the new
+        user's password. When the command completes you will be returned to
+        the shell prompt. You should see output similiar to following:
+<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.pgsql;</userinput>
+Password for user <replaceable>user-name</replaceable>:
+CREATE TABLE
+CREATE INDEX
+CREATE INDEX
+CREATE TABLE
+CREATE INDEX
+CREATE TABLE
+START TRANSACTION
+INSERT 0 1
+INSERT 0 1
+INSERT 0 1
+COMMIT
+CREATE TABLE
+START TRANSACTION
+INSERT 0 1
+COMMIT
+$
 </screen>
   </para>
   <para>
-  If instead of seeing keatest=> prompt, your login will be refused
-  with error code about failed peer or indent authentication, it means
-  that PostgreSQL is configured to check unix username and reject
-  login attepts if PostgreSQL names are different. To alter that,
-  PostgreSQL configuration must be changed. That file is located at
-  <filename>/etc/postgresql/9.1/main/pg_hba.conf</filename> on Ubuntu
-  13.10. Its location may be different on your system. Please consult
-  your PostgreSQL user manual before applying those changes as those
-  changes may expose your other databases that you run on the same
-  system.
+  If instead you encounter an error such as shown below:
+  </para>
+<screen>
+psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
+</screen>
+  <para>
+  This indicates that the Postgresql configuration needs to be modified.
+  Kea uses password authentication when connecting to the database and must
+  have the appropriate entries added to Posgresql's pg_hba.conf file.  This
+  file is normally located in the primary data directory for your Postgresql
+  server. The precise path may vary but the default location for Postgres 9.3
+  on Centos 6.5 is:
+  <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
+  Adding lines similiar to following should be sufficient:
+  </para>
+<screen>
+local   <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>                                 password
+host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          127.0.0.1/32           password
+host    <replaceable>database-name</replaceable>    <replaceable>user-name</replaceable>          ::1/128                password
+</screen>
+  <para>
+  Please consult your PostgreSQL user manual before making these changes as they
+  may expose your other databases that you run on the same system.
   </para>
       </section>
-
-
    </section>
 
   </chapter>
@@ -5826,7 +5849,7 @@ should include options from the isc option space:
         field in RELAY-FORW message) to select appropriate subnet.
       </para>
       <para>
-        However, that is not always the case. The relay 
+        However, that is not always the case. The relay
         address may not match the subnet in certain deployments. This
         usually means that there is more than one subnet allocated for a given
         link. Two most common examples where this is the case are long lasting

src/lib/dhcpsrv/dhcpsrv_messages.mes

@@ -383,6 +383,13 @@ with the specified address to the PostgreSQL backend database.
 A debug message issued when the server is about to add an IPv6 lease
 with the specified address to the PostgreSQL backend database.
 
+% DHCPSRV_PGSQL_DEALLOC_ERROR An error occured deallocating SQL statements while closing the PostgreSQL lease database: %1
+This is an error message issued when a DHCP server (either V4 or V6) exprienced
+and error freeing database SQL resources as part of closing its connection to
+ the Postgresql database.  The connection is closed as part of normal server
+shutdown.  This error is most likely a programmatic issue that is highly
+unlikely to occur or negatively impact server operation.
+
 % DHCPSRV_PGSQL_COMMIT committing to MySQL database
 The code has issued a commit call.  All outstanding transactions will be
 committed to the database.  Note that depending on the PostgreSQL settings,
@@ -421,7 +428,7 @@ A debug message issued when the server is attempting to obtain a set of
 IPv6 lease from the PostgreSQL database for a client with the specified IAID
 (Identity Association ID) and DUID (DHCP Unique Identifier).
 
-% DHCPSRV_PGSQL_GET_IAID_SUBID_DUID obtaining IPv4 leases for IAID %1, Subnet ID %2 and DUID %3
+% DHCPSRV_PGSQL_GET_IAID_SUBID_DUID obtaining IPv4 leases for IAID %1, Subnet ID %2, DUID %3, and lease type %4
 A debug message issued when the server is attempting to obtain an IPv6
 lease from the PostgreSQL database for a client with the specified IAID
 (Identity Association ID), Subnet ID and DUID (DHCP Unique Identifier).

src/lib/dhcpsrv/pgsql_lease_mgr.cc

@@ -201,11 +201,12 @@ protected:
     /// expressed as base-10 integer string.
     time_t convertFromDatabaseTime(const std::string& db_time_val) {
         // Convert string time value to time_t
-        istringstream tmp;
-        time_t db_time_t;
-        tmp.str(db_time_val);
-        tmp >> db_time_t;
-        return (db_time_t);
+        try  {
+            return (boost::lexical_cast<time_t>(db_time_val));
+        } catch (const std::exception& ex) {
+            isc_throw(BadValue, "Database time value is invalid: "
+                                << db_time_val);
+        }
     }
 
     /// Converts Postgres text boolean representations to bool
@@ -575,9 +576,9 @@ PgSqlLeaseMgr::~PgSqlLeaseMgr() {
         // Deallocate the prepared queries.
         PGresult* r = PQexec(conn_, "DEALLOCATE all");
         if(PQresultStatus(r) != PGRES_COMMAND_OK) {
-            /// @todo log it for posterity but go on
-            std::cout << "deallocate error: "
-                      << PQerrorMessage(conn_) << std::endl;
+            // Highly unlikely but we'll log it and go on.
+            LOG_ERROR(dhcpsrv_logger, DHCPSRV_PGSQL_DEALLOC_ERROR)
+                      .arg(PQerrorMessage(conn_));
         }
 
         PQclear(r);
@@ -664,10 +665,6 @@ PgSqlLeaseMgr::openDatabase() {
 bool
 PgSqlLeaseMgr::addLeaseCommon(StatementIndex stindex,
                               BindParams& params) {
-
-    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL,
-              DHCPSRV_PGSQL_ADD_ADDR4).arg(statements_[stindex].stmt_name);
-
     vector<const char *> out_values;
     vector<int> out_lengths;
     vector<int> out_formats;
@@ -900,19 +897,20 @@ PgSqlLeaseMgr::getLease4(const ClientId& clientid, SubnetID subnet_id) const {
 }
 
 Lease4Ptr
-PgSqlLeaseMgr::getLease4(const ClientId& /*client_id*/,
-                         const HWAddr& /*hwaddr*/,
-                         SubnetID /*subnet_id*/) const {
-    /// @todo
-    Lease4Ptr result;
-    return (result);
+PgSqlLeaseMgr::getLease4(const ClientId&, const HWAddr&, SubnetID) const {
+    /// This function is currently not implemented because allocation engine
+    /// searches for the lease using HW address or client identifier.
+    /// It never uses both parameters in the same time. We need to
+    /// consider if this function is needed at all.
+    isc_throw(NotImplemented, "The PgSqlLeaseMgr::getLease4 function was"
+              " called, but it is not implemented");
 }
 
 Lease6Ptr
 PgSqlLeaseMgr::getLease6(Lease::Type lease_type,
                          const isc::asiolink::IOAddress& addr) const {
     LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_PGSQL_GET_ADDR6)
-        .arg(addr.toText()).arg(lease_type);
+              .arg(addr.toText()).arg(lease_type);
 
     // Set up the WHERE clause value
     BindParams inparams;
@@ -964,10 +962,11 @@ PgSqlLeaseMgr::getLeases6(Lease::Type type, const DUID& duid,
 }
 
 Lease6Collection
-PgSqlLeaseMgr::getLeases6(Lease::Type lease_type, const DUID& duid, uint32_t iaid,
-                          SubnetID subnet_id) const {
-    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_MYSQL_GET_IAID_SUBID_DUID)
-        .arg(iaid).arg(subnet_id).arg(duid.toText()).arg(lease_type);
+PgSqlLeaseMgr::getLeases6(Lease::Type lease_type, const DUID& duid,
+                          uint32_t iaid, SubnetID subnet_id) const {
+    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL,
+              DHCPSRV_PGSQL_GET_IAID_SUBID_DUID)
+              .arg(iaid).arg(subnet_id).arg(duid.toText()).arg(lease_type);
 
     // Set up the WHERE clause value
     BindParams inparams;
@@ -1045,11 +1044,11 @@ PgSqlLeaseMgr::updateLease4(const Lease4Ptr& lease) {
     LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL,
               DHCPSRV_PGSQL_UPDATE_ADDR4).arg(lease->addr_.toText());
 
-    // Create the MYSQL_BIND array for the data being updated
+    // Create the BIND array for the data being updated
     ostringstream tmp;
     BindParams params = exchange4_->createBindForSend(lease);
 
-    // Set up the WHERE clause and append it to the MYSQL_BIND array
+    // Set up the WHERE clause and append it to the SQL_BIND array
     tmp << static_cast<uint32_t>(lease->addr_);
     params.push_back(PgSqlParam(tmp.str()));
 
@@ -1064,10 +1063,10 @@ PgSqlLeaseMgr::updateLease6(const Lease6Ptr& lease) {
     LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL,
               DHCPSRV_PGSQL_UPDATE_ADDR6).arg(lease->addr_.toText());
 
-    // Create the MYSQL_BIND array for the data being updated
+    // Create the BIND array for the data being updated
     BindParams params = exchange6_->createBindForSend(lease);
 
-    // Set up the WHERE clause and append it to the MYSQL_BIND array
+    // Set up the WHERE clause and append it to the BIND array
     params.push_back(PgSqlParam(lease->addr_.toText()));
 
     // Drop to common update code
@@ -1181,7 +1180,7 @@ PgSqlLeaseMgr::getVersion() const {
 
 void
 PgSqlLeaseMgr::commit() {
-    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_MYSQL_COMMIT);
+    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_PGSQL_COMMIT);
     PGresult * r = PQexec(conn_, "COMMIT");
     if (PQresultStatus(r) != PGRES_COMMAND_OK) {
         isc_throw(DbOperationError, "commit failed: " << PQerrorMessage(conn_));
@@ -1192,7 +1191,7 @@ PgSqlLeaseMgr::commit() {
 
 void
 PgSqlLeaseMgr::rollback() {
-    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_MYSQL_ROLLBACK);
+    LOG_DEBUG(dhcpsrv_logger, DHCPSRV_DBG_TRACE_DETAIL, DHCPSRV_PGSQL_ROLLBACK);
     PGresult * r = PQexec(conn_, "ROLLBACK");
     if (PQresultStatus(r) != PGRES_COMMAND_OK) {
         isc_throw(DbOperationError, "rollback failed: "