admin.xml 15.9 KB
Newer Older
1
2
3
4
5
6
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY mdash  "&#x2014;" >
]>

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
<chapter id="admin">
  <title>Kea Database Administration</title>

  <section id="kea-database-version">
    <title>Databases and Database Version Numbers</title>

    <para>
      Kea stores leases in one of several supported databases.
      As future versions of Kea are released, the structure of those
      databases will change. For example, Kea currently only stores
      lease information: in the future, additional data - such as host
      reservation details - will also be stored.
    </para>

    <para>
      A given version of Kea expects a particular structure in
      the database.  It ensures this by checking the version of the
      database it is using.  Separate version numbers are maintained for
      backend databases, independent of the version of Kea itself. It
      is possible that the backend database version will stay the same
      through several Kea revisions. Likewise, it is possible that the
      version of backend database may go up several revisions during a
      Kea upgrade.  Versions for each database are independent, so an
      increment in the MySQL database version does not imply an increment
      in that of PostgreSQL.
    </para>

    <para>
      Backend versions are specified in
      a <replaceable>major.minor</replaceable> format. The minor
      number is increased when there are backward compatibile changes
Tomek Mrugalski's avatar
Tomek Mrugalski committed
38
      introduced.  For example, the addition of a new index. It is
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
      desirable, but not mandatory to to apply such a change; you
      can run on older database version if you want to. (Although, in
      the example given, running without the new index may be at the
      expense of a performance penalty.) On the other hand, the major
      number is increased when an incompatible change is introduced,
      for example an extra column is added to a table. If you try to
      run Kea software on a database that is too old (as signified by
      mismatched backend major version number), Kea will refuse to run:
      administrative action will be required to upgrade the database.
    </para>
  </section>

  <section id="kea-admin">
    <title>The kea-admin Tool</title>

    <para>
      To manage the databases, Kea provides the
      <command>kea-admin</command> tool. It is able to initialize
      a new database, check its version number, and perform a
      database upgrade.
    </para>

    <para>
      <command>kea-admin</command> takes two mandatory
      parameters: <command>command</command> and
      <command>backend</command>. Additional, non-mandatory options
      may be specified. Currently supported commands are:

      <itemizedlist>
        <listitem>
          <simpara>
            <command>lease-init</command> &mdash;
            Initializes a new lease database. Useful during first
            Kea installation. The database is initialized to the
            latest version supported by the version of the software.
          </simpara>
        </listitem>
76

77
78
79
80
81
82
83
84
        <listitem>
          <simpara>
            <command>lease-version</command> &mdash;
            Reports the lease database version number. This is
            not necessarily equal to the Kea version number as
            each backend has its own versioning scheme.
          </simpara>
        </listitem>
85

86
87
88
89
90
91
92
93
        <listitem>
          <simpara>
            <command>lease-upgrade</command> &mdash;
            Conducts a lease database upgrade. This is useful when
            upgrading Kea.
          </simpara>
        </listitem>
      </itemizedlist>
94

95
96
      <command>backend</command> specifies the backend type. Currently
      supported types are:
97

98
99
100
101
102
103
104
      <itemizedlist>
        <listitem>
          <simpara>
            <command>memfile</command> &mdash; Lease information is
            stored on disk in a text file.
          </simpara>
        </listitem>
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
        <listitem>
          <simpara>
            <command>mysql</command> &mdash;
            Lease information is stored in a MySQL relational
            database.
          </simpara>
        </listitem>

        <listitem>
          <simpara>
            <command>pgsql</command> &mdash;
            Lease information is stored in a PostgreSQL relational
            database.
          </simpara>
        </listitem>
      </itemizedlist>

      Additional parameters may be needed, depending on your setup
      and specific operation: username, password and database name or
      the directory where specific files are located. See appropriate
      manual page for details (<command>man 8 kea-admin</command>).
    </para>
  </section>

  <section>
    <title>Supported Databases</title>
132
133
134
135

    <section>
      <title>memfile</title>

136
137
138
139
140
141
      <para>
        There are no special initialization steps necessary
        for the memfile backend.  During the first run, both
        <command>kea-dhcp4</command> and <command>kea-dhcp6</command>
        will create an empty lease file if one is not
        present. Necessary disk write permission is required.
142
143
144
145
146
147
148
149
      </para>
      <!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
    </section>

    <section>
      <title>MySQL</title>

      <para>
150
151
152
        The MySQL database must be properly set up if you want Kea to
        store information in MySQL. This section can be safely ignored
        if you chose to store the data in other backends.
153
154
155
      </para>


156
157
      <section id="mysql-database-create">
        <title>First Time Creation of Kea Database</title>
158

159
160
161
162
163
164
165
        <para>
          If you are setting the MySQL database for the first time,
          you need to create the database area within MySQL and set up
          the MySQL user ID under which Kea will access the database.
          This needs to be done manually: <command>kea-admin</command>
          is not able to do this for you.
        </para>
166

167
168
        <para>
          To create the database:
169

170
171
172
173
174
175
176
177
178
179
180
          <orderedlist>
            <listitem>
              <para>
                Log into MySQL as "root":
<screen>
$ <userinput>mysql -u root -p</userinput>
Enter password:
mysql>
</screen>
              </para>
            </listitem>
181

182
183
184
185
186
            <listitem>
              <para>
                Create the MySQL database:
<screen>
mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
187
</screen>
188
189
190
191
192
193
194
195
196
197
198
199
200
                (<replaceable>database-name</replaceable> is the name
                you have chosen for the database.)
              </para>
            </listitem>

            <listitem>
              <para>
                Create the user under which Kea will access the database
                (and give it a password), then grant it access to the
                database tables:
<screen>
mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput>
201
</screen>
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
                (<replaceable>user-name</replaceable> and
                <replaceable>password</replaceable> are the user ID
                and password you are using to allow Keas access to the
                MySQL instance. All apostrophes in the command lines
                above are required.)
              </para>
            </listitem>

            <listitem>
              <para>
                At this point, you may elect to create the database
                tables. (Alternatively, you can exit MySQL and create
                the tables using the <command>kea-admin</command> tool,
                as explained below.)  To do this:
<screen>
mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
218
mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput>
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
</screen>
                (<replaceable>path-to-kea</replaceable> is the
                location where you installed Kea.)
              </para>
            </listitem>

            <listitem>
              <para>
                Exit MySQL:
<screen>
mysql> <userinput>quit</userinput>
Bye
$
</screen>
              </para>
            </listitem>
          </orderedlist>
        </para>
237

238
239
240
241
        <para>
          If you elected not to create the tables in step 4, you can do
          so now by running the <command>kea-admin</command> tool:
<screen>
242
$ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
243
244
245
246
247
248
249
250
251
252
</screen>
          (Do not do this if you did create the tables in step 4.)
          <command>kea-admin</command> implements rudimentary checks:
          it will refuse to initialize a database that contains any
          existing tables. If you want to start from scratch, you
          must remove all data manually. (This process is a manual
          operation on purpose to avoid possibly irretrievable mistakes
          by <command>kea-admin</command>.)
        </para>
      </section>
253

254
255
      <section id="mysql-upgrade">
        <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
256
257

        <para>
258
259
260
261
          Sometimes a new Kea version may use newer database schema, so
          there will be a need to upgrade the existing database. This can
          be done using the <command>kea-admin lease-upgrade</command>
          command.
262
        </para>
263

264
        <para>
265
266
          To check the current version of the database, use the following command:
<screen>
267
$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
268
269
270
271
272
</screen>
          (See <xref linkend="kea-database-version"/> for a discussion
          about versioning.)  If the version does not match the minimum
          required for the new version of Kea (as described in the
          release notes), the database needs to be upgraded.
273
        </para>
274

275
        <para>
276
277
278
279
280
281
          Before upgrading, please make sure that the database is
          backed up.  The upgrade process does not discard any data but,
          depending on the nature of the changes, it may be impossible
          to subsequently downgrade to an earlier version.  To perform
          an upgrade, issue the following command:
<screen>
282
$ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
283
</screen>
284
        </para>
285
      </section>
286
287
288
289
290
291
    </section> <!-- end of MySQL sections -->

    <section>
      <title>PostgreSQL</title>

      <para>
292
293
294
        A PostgreSQL database must be set up if you want Kea to store
        lease and other information in PostgreSQL. This step can be
        safely ignored if you are using other database backends.
295
296
      </para>

297
298
      <section id="pgsql-database-create">
        <title>Manually Create the PostgreSQL Database and the Kea User</title>
299
300

        <para>
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
          The first task is to create both the lease database and the
          user under which the servers will access it. A number of steps
          are required:

          <orderedlist>
            <listitem>
              <para>
                Log into PostgreSQL as "root":
<screen>
$ <userinput>sudo -u postgres psql postgres</userinput>
Enter password:
postgres=#
</screen>
              </para>
            </listitem>
316

317
318
319
            <listitem>
              <para>
                Create the database:
320
321
322
323
324
<screen>
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
CREATE DATABASE
postgres=#
</screen>
325
326
327
328
329
330
331
332
333
334
335
336
                (<replaceable>database-name</replaceable> is the name
                you have chosen for the database.)
              </para>
            </listitem>

            <listitem>
              <para>
                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>
337
338
339
340
341
342
CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
              </para>
            </listitem>

            <listitem>
              <para>
                Exit PostgreSQL:
<screen>
postgres=# <userinput>\q</userinput>
Bye
$
</screen>
              </para>
            </listitem>

            <listitem>
              <para>
                Create the database tables using the new user's
                credentials and the dhcpdb_create.pgsql script supplied
                with Kea.  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 similar to following:
<screen>
366
$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/pgsql/dhcpdb_create.pgsql</userinput>
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
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>
385
386
387
388
389
390
                (<replaceable>path-to-kea</replaceable> is the location
                where you installed Kea.)
              </para>

              <para>
                If instead you encounter an error like:
391
392
393
<screen>
psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
</screen>
394
395
396
397
398
399
400
401
402
403
404
405
406
407
                ... you will need to alter the PostgreSQL configuration.
                Kea uses password authentication when connecting to
                the database and must have the appropriate entries
                added to PostgreSQL'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 PostgreSQL 9.3 on Centos 6.5 is:
                <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
              </para>

              <para>
                Assuming Kea is running on the same host as PostgreSQL,
                adding lines similar to following should be sufficient to
                provide password-authenticated access to Kea's database:
408
409
410
411
412
<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>
413
414
415
416
417
418
419
420
421
422
              </para>

              <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>
            </listitem>
          </orderedlist>
        </para>
423
424
      </section>

425
426
427
428
429
430
431
432
433
434
435
      <section>
        <title>Initialize the PostgreSQL Database Using kea-admin</title>

        <para>
          Support for PostgreSQL in <command>kea-admin</command> is
          currently not implemented.
        </para>
        <!-- @todo: document PgSQL upgrade once they are implemented in kea-admin -->
      </section>
    </section> <!-- end of PostgreSQL sections -->
  </section> <!-- End of Database sections -->
436

437
</chapter>