mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
[4489] Updated dev-guide with database prerequisites for unit tests.
This commit is contained in:
Marcin Siodelski
277
doc/devel/unit-tests.dox
Normal file
277
doc/devel/unit-tests.dox
Normal file
@@ -0,0 +1,277 @@
|
||||
// Copyright (C) 2015-2016 Internet Systems Consortium, Inc. ("ISC")
|
||||
//
|
||||
// This Source Code Form is subject to the terms of the Mozilla Public
|
||||
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
||||
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
/**
|
||||
|
||||
@page unitTests Building Kea with Unit Tests
|
||||
|
||||
@section unitTestsIntroduction Introduction
|
||||
|
||||
Kea uses the Google C++ Testing Framework (also called googletest or gtest) as a
|
||||
base for our C++ unit-tests. See http://code.google.com/p/googletest/ for
|
||||
details. We used to have Python unit-tests that were inherited from BIND10
|
||||
days. Those tests are removed now, so please do not develop any new Python
|
||||
tests in Kea. If you want to write DHCP tests in Python, we encourage you to
|
||||
take a look at ISC Forge: http://kea.isc.org/wiki/IscForge. You must have \c
|
||||
gtest installed or at least extracted in a directory before compiling Kea
|
||||
unit-tests. To enable unit-tests in Kea, use:
|
||||
|
||||
@code
|
||||
./configure --with-gtest=/path/to/your/gtest/dir
|
||||
@endcode
|
||||
|
||||
or
|
||||
|
||||
@code
|
||||
./configure --with-gtest-source=/path/to/your/gtest/dir
|
||||
@endcode
|
||||
|
||||
Depending on how you compiled or installed \c gtest (e.g. from sources
|
||||
or using some package management system) one of those two switches will
|
||||
find \c gtest. After that you make run unit-tests:
|
||||
|
||||
@code
|
||||
make check
|
||||
|
||||
@endcode
|
||||
|
||||
@section unitTestsEnvironmentVariables Environment Variables
|
||||
|
||||
The following environment variable can affect unit-tests:
|
||||
|
||||
- KEA_LOCKFILE_DIR - Specifies a directory where the logging system should
|
||||
create its lock file. If not specified, it is prefix/var/run/kea, where prefix
|
||||
defaults to /usr/local. This variable must not end with a slash. There is one
|
||||
special value: "none", which instructs Kea to not create lock file at
|
||||
all. This may cause issues if several processes log to the same file.
|
||||
Also see Kea User's Guide, section 15.3.
|
||||
|
||||
- KEA_LOGGER_DESTINATION - Specifies logging destination. If not set, logged
|
||||
messages will not be recorded anywhere. There are 3 special values:
|
||||
stdout, stderr and syslog. Any other value is interpreted as a filename.
|
||||
Also see Kea User's Guide, section 15.3.
|
||||
|
||||
- KEA_PIDFILE_DIR - Specifies the directory which should be used for PID files
|
||||
as used by dhcp::Daemon or its derivatives. If not specified, the default is
|
||||
prefix/var/run/kea, where prefix defaults to /usr/local. This variable must
|
||||
not end with a slash.
|
||||
|
||||
- KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix
|
||||
sockets are created. There's OS limitation on how long a Unix socket
|
||||
path can be. It is typcially slightly over 100 characters. If you
|
||||
happen to build and run unit-tests in deeply nested directories, this
|
||||
may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct
|
||||
unit-test to use a different directory. Must not end with slash (e.g.
|
||||
/tmp).
|
||||
|
||||
@section unitTestsDatabaseConfig Databases Configuration for Unit Tests
|
||||
|
||||
With the use of databases requiring separate authorisation, there are
|
||||
certain database-specific pre-requisites for successfully running the unit
|
||||
tests. These are listed in the following sections.
|
||||
|
||||
@subsection unitTestsDatabaseUsers Database Users Required for Unit Tests
|
||||
|
||||
Unit tests validating database backends require that <i>keatest</i> database
|
||||
is created. This database should be empty (should not include any relations).
|
||||
Unit tests will create required tables for each test case, and drop these tables
|
||||
when the test case ends. The unit tests also require that <i>keatest</i> user
|
||||
is created and that this user is configured to access <i>keatest</i>
|
||||
database with a <i>keatest</i> password.
|
||||
|
||||
Unit tests use these credentials to create database schema, run test cases
|
||||
and drop the schema. Thus, the <i>keatest</i> user must have sufficiently
|
||||
high privileges to create and drop tables, as well as insert and modify the
|
||||
data within those tables.
|
||||
|
||||
The database backends, which support read only access to the host reservations
|
||||
databases (currently MySQL and PostgreSQL), include unit tests verifying that
|
||||
a database user, with read-only privileges, can be used to retrieve host
|
||||
reservations. Those tests require that a user <i>keatest_readonly</i>, with
|
||||
SQL SELECT privilege to the <i>keatest</i> database (without INSERT, UPDATE etc.),
|
||||
is also created.
|
||||
|
||||
The following sections provide step-by-step guidelines how to setup the
|
||||
databases for running unit tests.
|
||||
|
||||
@subsection mysqlUnitTestsPrerequisites MySQL Database
|
||||
|
||||
A database called <i>keatest</i> must be created. A database user, also called
|
||||
<i>keatest</i> (and with a password <i>keatest</i>) must also be created and
|
||||
be given full privileges in that database. The unit tests create the schema
|
||||
in the database before each test and delete it afterwards.
|
||||
|
||||
In detail, the steps to create the database and user are:
|
||||
|
||||
-# Log into MySQL as root:
|
||||
@verbatim
|
||||
% mysql -u root -p
|
||||
Enter password:
|
||||
:
|
||||
mysql>@endverbatim\n
|
||||
-# Create the test database. This must be called "keatest":
|
||||
@verbatim
|
||||
mysql> CREATE DATABASE keatest;
|
||||
mysql>@endverbatim\n
|
||||
-# Create the users under which the test client will connect to the database
|
||||
(the apostrophes around the words <i>keatest</i> and <i>localhost</i> are
|
||||
required):
|
||||
@verbatim
|
||||
mysql> CREATE USER 'keatest'@'localhost' IDENTIFIED BY 'keatest';
|
||||
mysql> CREATE USER 'keatest_readonly'@'localhost' IDENTIFIED BY 'keatest';
|
||||
mysql>@endverbatim\n
|
||||
-# Grant the created users permissions to access the <i>keatest</i> database
|
||||
(again, the apostrophes around the user names and <i>localhost</i>
|
||||
are required):
|
||||
@verbatim
|
||||
mysql> GRANT ALL ON keatest.* TO 'keatest'@'localhost';
|
||||
mysql> GRANT SELECT ON keatest.* TO 'keatest_readonly'@'localhost';
|
||||
mysql>@endverbatim\n
|
||||
-# Exit MySQL:
|
||||
@verbatim
|
||||
mysql> quit
|
||||
Bye
|
||||
%@endverbatim
|
||||
|
||||
The unit tests are run automatically when "make check" is executed (providing
|
||||
that Kea has been build with the \--with-dhcp-mysql switch (see the installation
|
||||
section in the <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
|
||||
Reference Manual</a>).
|
||||
|
||||
@subsection pgsqlUnitTestsPrerequisites PostgreSQL Database
|
||||
|
||||
Conceptually, the steps required to run PostgreSQL unit-tests are the same as
|
||||
in MySQL. First, a database called <i>keatest</i> must be created. A database
|
||||
user, also called <i>keatest</i> (that will be allowed to log in using password
|
||||
<i>keatest</i>) must be created and given full privileges in that database. A
|
||||
database user, called <i>keatest_readonly</i> (using password <i>keatest</i>)
|
||||
must be created with SELECT privilege on all tables.
|
||||
The unit tests create the schema in the database before each test and delete it
|
||||
afterwards.
|
||||
|
||||
PostgreSQL set up differs from system to system. Please consult your OS-specific
|
||||
PostgreSQL documentation. The remainder of that section uses Ubuntu 13.10 x64
|
||||
(with PostgreSQL 9.0+) as an example. On Ubuntu, after installing PostgreSQL
|
||||
(with <tt>sudo apt-get install postgresql</tt>), it is installed as user
|
||||
<i>postgres</i>. To create new databases or add new users, initial commands
|
||||
must be issued as user postgres:
|
||||
|
||||
@verbatim
|
||||
$ sudo -u postgres psql postgres
|
||||
[sudo] password for thomson:
|
||||
psql (9.1.12)
|
||||
Type "help" for help.
|
||||
postgres=# CREATE USER keatest WITH PASSWORD 'keatest';
|
||||
CREATE ROLE
|
||||
postgres=# CREATE DATABASE keatest;
|
||||
CREATE DATABASE
|
||||
postgres=# GRANT ALL PRIVILEGES ON DATABASE keatest TO keatest;
|
||||
GRANT
|
||||
postgres=# \q
|
||||
@endverbatim
|
||||
|
||||
PostgreSQL versions earlier than 9.0 don't provide an SQL statement for granting
|
||||
privileges on all tables in a database. In newer PostgreSQL versions, it is
|
||||
possible to grant specific privileges on all tables within a schema.
|
||||
However, this only affects tables which exist when the privileges are granted.
|
||||
To ensure that the user has specific privileges to tables dynamically created
|
||||
by the unit tests, the default schema privileges must be altered.
|
||||
|
||||
The following example demonstrates how to create user <i>keatest_readonly</i>,
|
||||
which has SELECT privilege to the tables within the <i>keatest</i> database,
|
||||
in Postgres 9.0+. For earlier versions of Postgres, it is recommended to
|
||||
simply grant full privileges to <i>keatest_readonly</i> user, using the
|
||||
same steps as for the <i>keatest</i> user.
|
||||
|
||||
@verbatim
|
||||
$ psql -U postgres
|
||||
Password for user postgres:
|
||||
psql (9.1.12)
|
||||
Type "help" for help.
|
||||
|
||||
postgres=# CREATE USER keatest_readonly WITH PASSWORD 'keatest';
|
||||
CREATE ROLE
|
||||
postgres=# \q
|
||||
|
||||
$ psql -U keatest
|
||||
Password for user keatest:
|
||||
psql (9.1.12)
|
||||
Type "help" for help.
|
||||
|
||||
keatest=> ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES to keatest_readonly;
|
||||
ALTER DEFAULT PRIVILEGES
|
||||
keatest=> \q
|
||||
@endverbatim
|
||||
|
||||
Note that <i>keatest</i> user (rather than <i>postgres</i>) is used to grant
|
||||
privileges to the <i>keatest_readonly</i> user. This ensures that the SELECT
|
||||
privilege is granted only on the tables that the <i>keatest</i> user can access
|
||||
within the public schema.
|
||||
|
||||
Now we should be able to log into the newly created database using both user
|
||||
names:
|
||||
@verbatim
|
||||
$ psql -d keatest -U keatest
|
||||
Password for user keatest:
|
||||
psql (9.1.12)
|
||||
Type "help" for help.
|
||||
|
||||
keatest=> \q
|
||||
|
||||
$ psql -d keatest -U keatest_readonly
|
||||
Password for user keatest_readonly:
|
||||
psql (9.1.12)
|
||||
Type "help" for help.
|
||||
|
||||
keatest=>
|
||||
@endverbatim
|
||||
|
||||
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.
|
||||
<tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> config file
|
||||
has to be tweaked. It may be in a different location in your system. The following
|
||||
lines:
|
||||
|
||||
@verbatim
|
||||
local all all peer
|
||||
host all all 127.0.0.1/32 md5
|
||||
host all all ::1/128 md5
|
||||
@endverbatim
|
||||
|
||||
were replaced with:
|
||||
|
||||
@verbatim
|
||||
local all all password
|
||||
host all all 127.0.0.1/32 password
|
||||
host all all ::1/128 password
|
||||
@endverbatim
|
||||
|
||||
Another possible problem is to get no password prompt, in general because
|
||||
you have no <tt>pg_hba.conf</tt> config file and everybody is by default
|
||||
trusted. As it has a very bad effect on the security you should have
|
||||
been warned it is a highly unsafe config. The solution is the same,
|
||||
i.e., require password or md5 authentication method. If you lose
|
||||
the postgres user access you can add first:
|
||||
@verbatim
|
||||
local all postgres trust
|
||||
@endverbatim
|
||||
to trust only the local postgres user. Note the postgres user can
|
||||
be pgsql on some systems.
|
||||
|
||||
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.
|
||||
In general case, it is a poor idea to run anything of value on a system
|
||||
that runs tests. Use caution!
|
||||
|
||||
The unit tests are run automatically when "make check" is executed (providing
|
||||
that Kea has been build with the \--with-dhcp-pgsql switch (see the installation
|
||||
section in the <a href="http://kea.isc.org/docs/kea-guide.html">Kea Administrator
|
||||
Reference Manual</a>).
|
||||
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user