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

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

    <para>
14 15 16 17 18 19 20
      Kea supports storing leases and host reservations (i.e. static
      assignments of addresses, prefixes and options) in one of
      the 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
      and host reservations: in the future, additional
      data - such as subnet definitions - will also be stored.
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
    </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
39
      number is increased when there are backward compatible changes
Tomek Mrugalski's avatar
Tomek Mrugalski committed
40
      introduced.  For example, the addition of a new index. It is
Jeremy C. Reed's avatar
Jeremy C. Reed committed
41
      desirable, but not mandatory to apply such a change; you
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
      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
59 60
      a new database, check its version number, perform a
      database upgrade, and dump lease data to a text file.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
    </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>
78

79 80 81 82 83 84 85 86
        <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>
87

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

        <listitem>
          <simpara>
            <command>lease-dump</command> &mdash;
99 100 101 102
            Dumps the contents of the lease database (for MySQL, PostgreSQL or
            CQL backends) to CSV text file. The first line of the file contains
            the column names.  This is meant to be used as a diagnostic tool
            that provides a portable, human-readable form of lease data.
103 104
          </simpara>
        </listitem>
105
      </itemizedlist>
106

107 108
      <command>backend</command> specifies the backend type. Currently
      supported types are:
109

110 111 112 113 114 115 116
      <itemizedlist>
        <listitem>
          <simpara>
            <command>memfile</command> &mdash; Lease information is
            stored on disk in a text file.
          </simpara>
        </listitem>
117

118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
        <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>
133 134 135 136 137 138 139 140

        <listitem>
          <simpara>
            <command>cql</command> &mdash;
            Lease information is stored in a CQL database.
          </simpara>
        </listitem>

141 142 143 144 145 146 147 148 149
      </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>

150
  <section id="supported-databases">
151
    <title>Supported Databases</title>
152

153 154 155
    <para>The following table presents the capabilities of available
    backends. Please refer to the specific sections dedicated to each backend to
    better understand their capabilities and limitations. Choosing the right
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
    backend may be essential for success or failure of your deployment.</para>

    <para>
      <table frame="all" id="backends">
        <title>List of available backends</title>
        <tgroup cols='2'>
          <colspec colname='feature'/>
          <colspec colname='memfile'/>
          <colspec colname='mysql'/>
          <colspec colname='pgsql'/>
          <colspec colname='cql'/>
          <thead>
            <row>
              <entry>Feature</entry>
              <entry>Memfile</entry>
              <entry>MySQL</entry>
              <entry>PostgreSQL</entry>
              <entry>CQL(Cassandra)</entry>
            </row>
          </thead>
          <tbody>
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
            <row>
              <entry>Status</entry>
              <entry>Stable</entry>
              <entry>Stable</entry>
              <entry>Stable</entry>
              <entry>Experimental</entry>
            </row>

            <row>
              <entry>Data format</entry>
              <entry>coma separated file</entry>
              <entry>SQL RMDB</entry>
              <entry>SQL RMDB</entry>
              <entry>NoSQL database (CQL)</entry>
            </row>

            <row>
              <entry>Leases</entry>
              <entry>yes</entry>
              <entry>yes</entry>
              <entry>yes</entry>
              <entry>yes</entry>
            </row>

            <row>
              <entry>Host Reservations</entry>
              <entry>no</entry>
              <entry>yes</entry>
206
              <entry>yes</entry>
207 208 209 210 211 212 213
              <entry>no</entry>
            </row>

            <row>
              <entry>Options defined on per host basis</entry>
              <entry>no</entry>
              <entry>yes</entry>
214
              <entry>yes</entry>
215 216 217 218 219 220 221 222
              <entry>no</entry>
            </row>

          </tbody>
          </tgroup>
       </table>
    </para>

223 224 225
    <section>
      <title>memfile</title>

226
      <para>
227
        Memfile backend is able to store lease information, but is not able to
228 229 230 231 232
        store host reservation details. There are no plans to add the
        reservations storage capability to memfile. Host reservations can be
        defined in the configuration file.
      </para>

233 234 235 236 237 238
      <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.
239
      </para>
240

241 242 243 244
      <section id="memfile-upgrade">
        <title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
        <para>
        There are no special steps required to upgrade memfile lease files
245 246 247 248 249
        from an earlier version of Kea to a new version of Kea.

        During startup the servers will check the schema version of the lease
        files against their own.  If there is a mismatch, the servers will
        automatically launch the LFC process to convert the files to the
250
        server's schema version.  While this mechanism is primarily meant to
251 252 253 254 255 256 257 258 259
        ease the process of upgrading to newer versions of Kea, it can also
        be used for downgrading should the need arise.  When upgrading, any
        values not present in the original lease files will be assigned
        appropriate default values.  When downgrading, any data present in
        the files but not in the server's schema will be dropped.

        If you wish to convert the files manually, prior to starting the
        servers you may do so by running the LFC process yourself.
        See <xref linkend="kea-lfc"/> for more information.
260 261
        </para>
      </section>
262 263 264 265 266 267
      <!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
    </section>

    <section>
      <title>MySQL</title>

268 269 270 271 272
      <para>
        MySQL is able to store leases, host reservations and options defined on
        a per host basis.
      </para>

273
      <para>
274 275 276
        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.
277 278
      </para>

279 280
      <section id="mysql-database-create">
        <title>First Time Creation of Kea Database</title>
281

282 283 284 285 286 287 288
        <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>
289

290 291
        <para>
          To create the database:
292

293 294 295 296 297 298 299 300 301 302 303
          <orderedlist>
            <listitem>
              <para>
                Log into MySQL as "root":
<screen>
$ <userinput>mysql -u root -p</userinput>
Enter password:
mysql>
</screen>
              </para>
            </listitem>
304

305 306 307 308 309
            <listitem>
              <para>
                Create the MySQL database:
<screen>
mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
310
</screen>
311 312 313 314 315 316 317 318 319 320 321 322 323
                (<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>
324
</screen>
325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340
                (<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>
341
mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput>
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359
</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>
360

361 362 363 364
        <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>
365
$ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
366 367 368 369 370 371 372 373 374 375
</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>
376

377 378
      <section id="mysql-upgrade">
        <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
379 380

        <para>
381 382 383 384
          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.
385
        </para>
386

387
        <para>
388 389
          To check the current version of the database, use the following command:
<screen>
390
$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
391 392 393 394 395
</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.
396
        </para>
397

398
        <para>
399 400 401 402 403 404
          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>
405
$ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
406
</screen>
407
        </para>
408
      </section>
409 410 411 412 413 414
    </section> <!-- end of MySQL sections -->

    <section>
      <title>PostgreSQL</title>

      <para>
415 416 417
        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.
418 419
      </para>

420 421
      <section id="pgsql-database-create">
        <title>Manually Create the PostgreSQL Database and the Kea User</title>
422 423

        <para>
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438
          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>
439

440 441 442
            <listitem>
              <para>
                Create the database:
443 444 445 446 447
<screen>
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
CREATE DATABASE
postgres=#
</screen>
448 449 450 451 452 453 454 455 456 457 458 459
                (<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>
460 461 462 463 464 465
CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481
              </para>
            </listitem>

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

            <listitem>
              <para>
482 483 484 485 486 487 488 489
                At this point you are ready to create the database tables.
                This can be done using the <command>kea-admin</command> tool
                as explained in the next section (recommended), or manually.
                To create the tables manually enter the following command.
                Note that PostgreSQL will prompt you to enter the new user's
                password you specified in Step 3. When the command completes
                you will be returned to the shell prompt. You should see output
                similar to following:
490
<screen>
491
$ <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>
492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509
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>
510 511 512 513 514 515
                (<replaceable>path-to-kea</replaceable> is the location
                where you installed Kea.)
              </para>

              <para>
                If instead you encounter an error like:
516 517 518
<screen>
psql: FATAL:  no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
</screen>
519 520 521 522 523 524 525 526 527 528 529 530 531 532
                ... 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:
533 534 535 536 537
<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>
538 539 540
              </para>

              <para>
541 542 543 544 545 546
                These edits are primarily intended as a starting point
                not a definitive reference on PostgreSQL administration or
                database security.  Please consult your PostgreSQL user
                manual before making these changes as they may expose
                other databases that you run.  It may be necessary to
                restart PostgreSQL in order for these changes to take effect.
547 548 549 550
              </para>
            </listitem>
          </orderedlist>
        </para>
551 552
      </section>

553 554 555
      <section>
        <title>Initialize the PostgreSQL Database Using kea-admin</title>
        <para>
556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572
          If you elected not to create the tables manually, you can do
          so now by running the <command>kea-admin</command> tool:
<screen>
$ <userinput>kea-admin lease-init pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
          Do not do this if you already created the tables in manually.
          <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>
      <section id="pgsql-upgrade">
        <title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title>
        <para>
573 574
          The PostgreSQL database schema can be upgraded using the same tool and
          commands as described in <xref linkend="mysql-upgrade"/>, with the
575
          exception that the "pgsql" database backend type must be used in
576
          the commands.
577 578
        </para>
        <para>
579
          Use the following command to check the current schema version:
580 581 582 583 584 585 586
<screen>
$ <userinput>kea-admin lease-version pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
          Use the following command to perform an upgrade:
<screen>
$ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
587 588 589
        </para>
      </section>
    </section> <!-- end of PostgreSQL sections -->
590 591

    <section>
592
      <title>CQL (Cassandra)</title>
593

594 595
      <para>
        Cassandra, or Cassandra Query Language (CQL), is the newest backend
596
        added to Kea. Since it was added recently and has not undergone as much
597 598 599 600 601 602
        testing as other backends, it is considered experimental. Please use
        with caution. CQL backend is currently able to store leases only. The
        ability to store host reservations will likely be added some time in the
        future.
      </para>

603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714
      <para>
        The CQL database must be properly set up if you want Kea to store
        information in CQL. This section can be safely ignored if you chose to
        store the data in other backends.
      </para>

    <section id="cql-database-create">
      <title>First Time Creation of Kea Database</title>

      <para>
        If you are setting up the CQL database for the first time, you need to
        create the keyspace area within CQL. This needs to be done manually:
        <command>kea-admin</command> is not able to do this for you.
      </para>

      <para>
        To create the database:
        <orderedlist>
          <listitem>
            <para>
              Export CQLSH_HOST environemnt variable:
<screen>
$ <userinput>export CQLSH_HOST=localhost</userinput>
</screen>
              </para>
            </listitem>
          <listitem>
            <para>
              Log into CQL:
<screen>
$ <userinput>cqlsh</userinput>
cql>
</screen>
              </para>
            </listitem>

          <listitem>
            <para>
              Create the CQL keyspace:
<screen>
cql> <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};</userinput>
</screen>
              (<replaceable>keyspace-name</replaceable> is the name you have
              chosen for the keyspace)
            </para>
          </listitem>

         <listitem>
            <para>
              At this point, you may elect to create the database tables.
              (Alternatively, you can exit CQL and create the tables using the
              <command>kea-admin</command> tool, as explained below)  To do this:
<screen>
<userinput>cqslh -k <replaceable>keyspace-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/cql/dhcpdb_create.cql</userinput>
</screen>
              (<replaceable>path-to-kea</replaceable> is the location where you
              installed Kea)
            </para>
          </listitem>
        </orderedlist>
      </para>

      <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>
$ <userinput>kea-admin lease-init cql -n <replaceable>database-name</replaceable></userinput>
</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>

    <section id="cql-upgrade">
      <title>Upgrading a CQL Database from an Earlier Version of Kea</title>

      <para>
        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.
      </para>

      <para>
        To check the current version of the database, use the following command:
<screen>
$ <userinput>kea-admin lease-version cql -n <replaceable>database-name</replaceable></userinput>
</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.
      </para>

      <para>
        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>
$ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replaceable></userinput>
</screen>
      </para>
    </section>
  </section> <!-- end of CQL sections -->

715 716 717 718 719 720 721
    <section>
      <title>Using read only databases with host reservations</title>
      <para>If read only database is used for storing host reservations,
      Kea must be explicitly configured to operate on the database in
      the read only mode.
      Sections <xref linkend="read-only-database-configuration4"/> and
      <xref linkend="read-only-database-configuration6"/> describe when
722
      such configuration may be reqired and how to configure Kea to
723 724 725 726
      operate using read only host database.
      </para>
    </section>

727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742
    <section>
      <title>Limitations related to the use of the SQL databases</title>

      <para>
        The lease expiration time is stored in the SQL database for each lease
        as a timestamp value. Kea developers observed that MySQL database doesn't
        accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number)
        from the beginning of the epoch. At the same time, some versions of PostgreSQL
        do accept greater values but the value is altered when it is read back.
        For this reason the lease database backends put the restriction for the
        maximum timestamp to be stored in the database, which is equal to the
        maximum signed 32-bit number. This effectively means that the current
        Kea version can't store the leases which expiration time is later than
        2147483647 seconds since the beginning of the epoch (around year 2038).
      </para>
    </section>
743

744
  </section> <!-- End of Database sections -->
745

746
</chapter>