1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.
/**
@page dhcpDatabaseBackends DHCP Database Back-Ends
All DHCP lease data is stored in some form of database, the interface
to this being through the Lease Manager.
All backend classes such as isc::dhcp::MySqlLeaseMgr are derived from
the abstract isc::dhcp::LeaseMgr class. This provides methods to
create, retrieve, modify and delete leases in the database.
There are currently three available Lease Managers, Memfile, MySQL and
PostgreSQL:
- Memfile is an in-memory lease database which can be configured to persist
its content to disk in a flat-file. Support for the Memfile database
backend is built into Kea DHCP.
- The MySQL lease manager uses the freely available MySQL as its backend
database. This is not included in Kea DHCP by default:
the \--with-dhcp-mysql switch must be supplied to "configure" for support
to be compiled into the software.
- The PostgreSQL lease manager uses the freely available PostgreSQL as its
backend database. This is not included in Kea DHCP by default:
the \--with-dhcp-pgsql switch must be supplied to "configure" for
support to be compiled into the software.
@section dhcpdb-instantiation Instantiation of Lease Managers
A lease manager is instantiated through the LeaseMgrFactory class. This
has three methods:
- isc::dhcp::LeaseMgrFactory::create - Creates a singleton Lease
Manager of the appropriate type.
- isc::dhcp::LeaseMgrFactory::instance - Returns a reference to the
the instance of the Lease Manager.
- isc::dhcp::LeaseMgrFactory::destroy - Destroys the singleton lease manager.
The selection of the Lease Manager (and thus the backend database) is
controlled by the connection string passed to
isc::dhcp::LeaseMgrFactory::create. This is a set of "keyword=value" pairs
(no embedded spaces), each pair separated by a space from the others, e.g.
\code
type=mysql user=keatest password=keatest name=keatest host=localhost
\endcode
The following keywords are used for all backends:
- <b>type</b> - specifies the type of database backend. The following values
for the type keyword are supported:
- <B>memfile</b> - In-memory database. Nothing is written to any
external storage, so this should not be used in production.
- <b>mysql</b> - Use MySQL as the database
The following sections list the database-specific keywords:
@subsection dhcpdb-keywords-mysql MySQL connection string keywords
- <b>host</b> - host on which the selected database is running. If not
supplied, "localhost" is assumed.
- <b>name</b> - name of the MySQL database to access. There is no default -
this must always be supplied.
- <b>password</b> - password for the selected user ID (see below). If not
specified, no password is used.
- <b>user</b> - database user ID under which the database is accessed. If not
specified, no user ID is used - the database is assumed to be open.
@subsection dhcpdb-keywords-pgsql PostgreSQL connection string keywords
- <b>host</b> - host on which the selected database is running. If not
supplied, "localhost" is assumed.
- <b>name</b> - name of the PostgreSQL database to access. There is no
default - this must always be supplied.
- <b>password</b> - password for the selected user ID (see below). If not
specified, no password is used.
- <b>user</b> - database user ID under which the database is accessed. If not
specified, no user ID is used - the database is assumed to be open.
@section dhcp-backend-unittest Running 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 dhcp-mysql-unittest MySQL Unit Tests
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 user 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>@endverbatim\n
-# Grant the created user permissions to access the <i>keatest</i> database
(again, the apostrophes around the words <i>keatest</i> and <i>localhost</i>
are required):
@verbatim
mysql> GRANT ALL ON keatest.* TO 'keatest'@'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 dhcp-pgsql-unittest PostgreSQL Unit Tests
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. 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 as
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
Now we are back to our regular, unprivileged user. Try to log into the newly
created database using keatest credentials:
@verbatim
$ psql -d keatest -U keatest
Password for user keatest:
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.
Alternatively, you may set up your environment, so the tests would be run from
unix account keatest. <tt>/etc/postgresql/9.1/main/pg_hba.conf</tt> config file
had to betweaked. 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
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>).
*/
|
