|
|
@@ -4,276 +4,366 @@
|
|
|
<!ENTITY mdash "—" >
|
|
|
]>
|
|
|
|
|
|
- <chapter id="admin">
|
|
|
- <title>Database administration</title>
|
|
|
+<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
|
|
|
+ introduced. For example, ithe addition of a new index. It is
|
|
|
+ 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> —
|
|
|
+ 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>
|
|
|
|
|
|
- <section id="kea-admin">
|
|
|
- <title>kea-admin tool</title>
|
|
|
+ <listitem>
|
|
|
+ <simpara>
|
|
|
+ <command>lease-version</command> —
|
|
|
+ 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>
|
|
|
|
|
|
- <para>
|
|
|
- Kea is able to store leases in one of several supported databases.
|
|
|
- Additional types of data, like host reservation details, will
|
|
|
- be supported in the near future. To manage those databases, a
|
|
|
- tool called <command>kea-admin</command> was introduced. Currently
|
|
|
- it is able to initialize new database, check its version
|
|
|
- and perform database upgrade, if needed.
|
|
|
- </para>
|
|
|
+ <listitem>
|
|
|
+ <simpara>
|
|
|
+ <command>lease-upgrade</command> —
|
|
|
+ Conducts a lease database upgrade. This is useful when
|
|
|
+ upgrading Kea.
|
|
|
+ </simpara>
|
|
|
+ </listitem>
|
|
|
+ </itemizedlist>
|
|
|
|
|
|
- <para>
|
|
|
- Kea mantains separate version numbering for its database backends. These
|
|
|
- are independent of the Kea version. It is possible that the backend
|
|
|
- revision will stay the same through several Kea revisions. Likewise, it
|
|
|
- is possible that a backend may go up several times between two Kea
|
|
|
- revisions, if there were several changes introduced that required database
|
|
|
- schema change. Versions for each backend are independent, so a bump
|
|
|
- in MySQL version does not imply bump in the Postgres version.
|
|
|
- </para>
|
|
|
+ <command>backend</command> specifies the backend type. Currently
|
|
|
+ supported types are:
|
|
|
|
|
|
- <para>
|
|
|
- Backend versions are specified in major.minor format. Minor number is
|
|
|
- increased when there are backward compatibile changes introduced. For
|
|
|
- example, a new index is added. It is desirable, but not mandatory to
|
|
|
- have it. You can run on older database version if you want to. On
|
|
|
- the other hand, major number is increased when there's an incompatible
|
|
|
- change introduced, for example an extra column is added. If you try
|
|
|
- to run Kea software on a database that is too old (which is signified
|
|
|
- by mismatched major backend version number), Kea will refuse to run
|
|
|
- and an administrative action will be required to upgrade the database.
|
|
|
- </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> —
|
|
|
- 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>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <simpara>
|
|
|
- <command>lease-version</command> —
|
|
|
- Reports lease database version. This is not necessarily
|
|
|
- equal to Kea version as each backend has its own versioning
|
|
|
- scheme.
|
|
|
- </simpara>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <simpara>
|
|
|
- <command>lease-upgrade</command> —
|
|
|
- Conducts lease database upgrade. This is useful when
|
|
|
- migrating between old and new Kea versions.
|
|
|
- </simpara>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- </itemizedlist>
|
|
|
-
|
|
|
- The <command>backend</command> specified backend type. Currently
|
|
|
- allowed backends are: memfile, mysql and pgsql. There are additional
|
|
|
- parameters that may be needed, depending on your setup and specific
|
|
|
- operation: specify 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>
|
|
|
+ <itemizedlist>
|
|
|
+ <listitem>
|
|
|
+ <simpara>
|
|
|
+ <command>memfile</command> — Lease information is
|
|
|
+ stored on disk in a text file.
|
|
|
+ </simpara>
|
|
|
+ </listitem>
|
|
|
|
|
|
- </section>
|
|
|
+ <listitem>
|
|
|
+ <simpara>
|
|
|
+ <command>mysql</command> —
|
|
|
+ Lease information is stored in a MySQL relational
|
|
|
+ database.
|
|
|
+ </simpara>
|
|
|
+ </listitem>
|
|
|
+
|
|
|
+ <listitem>
|
|
|
+ <simpara>
|
|
|
+ <command>pgsql</command> —
|
|
|
+ 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>
|
|
|
|
|
|
<section>
|
|
|
<title>memfile</title>
|
|
|
|
|
|
- <para>There are no special initialization steps necessary for memfile
|
|
|
- backend. During the first run, both <command>kea-dhcp4</command> and
|
|
|
- <command>kea-dhcp6</command> will create an empty lease file, if it is not
|
|
|
- present. Necessary disk write permission is required.
|
|
|
+ <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.
|
|
|
</para>
|
|
|
-
|
|
|
-
|
|
|
<!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
|
|
|
-
|
|
|
</section>
|
|
|
|
|
|
<section>
|
|
|
<title>MySQL</title>
|
|
|
|
|
|
<para>
|
|
|
- MySQL database must be properly set up if you want Kea to store lease
|
|
|
- and other information in MySQL. This step can be safely skipped if you
|
|
|
- chose to store the data in other backends, like memfile or PosgreSQL.
|
|
|
+ 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.
|
|
|
</para>
|
|
|
|
|
|
- <section id="mysql-database-create">
|
|
|
- <title>Initialize the MySQL Database using kea-admin</title>
|
|
|
|
|
|
- <para>
|
|
|
- There are two ways to initialize the database. The first one involves
|
|
|
- running <command>kea-admin</command> tool, which attempts to automate
|
|
|
- the process. It is convenient to use, but may not cover more complex
|
|
|
- cases. The second alternative is to run all the commands
|
|
|
- manually.
|
|
|
- </para>
|
|
|
+ <section id="mysql-database-create">
|
|
|
+ <title>First Time Creation of Kea Database</title>
|
|
|
|
|
|
- <para>
|
|
|
- When <command>kea-admin</command> is told to initialize the database, it
|
|
|
- assumes that the database and database user has been created. If not,
|
|
|
- please follow the necessary instructions in <xref
|
|
|
- linkend="mysql-database-create-manual" />.
|
|
|
- </para>
|
|
|
-
|
|
|
- <para>
|
|
|
- To initialize new MySQL database using <command>kea-admin</command>, use the
|
|
|
- following command:
|
|
|
- <screen>$ <userinput>kea-admin lease-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
|
|
|
-</screen>
|
|
|
-
|
|
|
- <command>kea-admin</command> has rudimentary checks implemented. It will
|
|
|
- refuse to initialize a database that has any existing tables. If you want
|
|
|
- to start from scratch, you must remove existing data manually. This process
|
|
|
- is left manual on purpose to avoid mistakes that could not be undone.
|
|
|
- </para>
|
|
|
+ <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>
|
|
|
|
|
|
- </section>
|
|
|
+ <para>
|
|
|
+ To create the database:
|
|
|
|
|
|
- <section id="mysql-upgrade">
|
|
|
- <title>Upgrading MySQL database from earlier Kea versions</title>
|
|
|
+ <orderedlist>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ Log into MySQL as "root":
|
|
|
+<screen>
|
|
|
+$ <userinput>mysql -u root -p</userinput>
|
|
|
+Enter password:
|
|
|
+mysql>
|
|
|
+</screen>
|
|
|
+ </para>
|
|
|
+ </listitem>
|
|
|
|
|
|
- <para>Sometime a new Kea version may use newer database schema and there may
|
|
|
- be a need to upgrade existing database. This can be done using <command>kea-admin</command>.
|
|
|
- It is possible to check existing database version:
|
|
|
- <screen>$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ Create the MySQL database:
|
|
|
+<screen>
|
|
|
+mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
|
|
|
</screen>
|
|
|
- See <xref linkend="kea-admin"/> for a discussion about versioning.</para>
|
|
|
- <para>It may be required to run database upgrade. This process is designed
|
|
|
- to not discard any data, but depending on the nature of the changes, it
|
|
|
- may be impossible to downgrade to earlier Kea version. Please back up your
|
|
|
- database if you consider reverting to an earlier Kea version. To conduct
|
|
|
- an upgrade, the following command should be used:
|
|
|
- <screen>$ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
|
|
|
+ (<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>
|
|
|
</screen>
|
|
|
- </para>
|
|
|
+ (<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>
|
|
|
+mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.mysql</userinput>
|
|
|
+</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>
|
|
|
|
|
|
- </section>
|
|
|
+ <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 mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <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="mysql-database-create-manual">
|
|
|
- <title>Manually create the MySQL Database and the Kea User</title>
|
|
|
+ <section id="mysql-upgrade">
|
|
|
+ <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
|
|
|
|
|
|
- <note>
|
|
|
- <simpara>
|
|
|
- This paragraph explains how to create and initialize MySQL database
|
|
|
- manually. See <xref linkend="mysql-database-create" /> for a kea-admin,
|
|
|
- a tool that automates most of those steps.
|
|
|
- </simpara>
|
|
|
- </note>
|
|
|
<para>
|
|
|
- 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:
|
|
|
+ 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>
|
|
|
- 1. Log into MySQL as "root":
|
|
|
- <screen>$ <userinput>mysql -u root -p</userinput>
|
|
|
-Enter password:<userinput/>
|
|
|
- :<userinput/>
|
|
|
-mysql></screen>
|
|
|
+ To check the current version of the database, use the following command:
|
|
|
+<screen>
|
|
|
+$ <userinput>kea-admin lease-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <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>
|
|
|
- 2. Create the database:
|
|
|
- <screen>mysql> <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 by running the dhcpdb_create.mysql script supplied as part of Kea:
|
|
|
- <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
|
|
|
-mysql> <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.mysql</userinput></screen>
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 4. 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></screen>
|
|
|
+ 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 mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -d <replaceable>database-name</replaceable></userinput>
|
|
|
+</screen>
|
|
|
</para>
|
|
|
- <para>
|
|
|
- 5. Exit MySQL:
|
|
|
- <screen>mysql> <userinput>quit</userinput>
|
|
|
-Bye<userinput/>
|
|
|
-$</screen>
|
|
|
- </para>
|
|
|
- </section>
|
|
|
-
|
|
|
+ </section>
|
|
|
</section> <!-- end of MySQL sections -->
|
|
|
|
|
|
<section>
|
|
|
<title>PostgreSQL</title>
|
|
|
|
|
|
<para>
|
|
|
- PostgreSQL database must be properly set up if you want Kea to store lease
|
|
|
- and other information in PostgreSQL. This step can be safely skipped if you
|
|
|
- chose to store the data in other backends, like memfile or MySQL.
|
|
|
+ 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.
|
|
|
</para>
|
|
|
|
|
|
- <section>
|
|
|
- <title>Initialize the PostgreSQL Database using kea-admin</title>
|
|
|
+ <section id="pgsql-database-create">
|
|
|
+ <title>Manually Create the PostgreSQL Database and the Kea User</title>
|
|
|
|
|
|
<para>
|
|
|
- Support for PostgreSQL in kea-admin is currently not implemented.
|
|
|
- </para>
|
|
|
- <!-- @todo: document PgSQL upgrade once they are implemented in kea-admin -->
|
|
|
-
|
|
|
- </section>
|
|
|
-
|
|
|
+ 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>
|
|
|
|
|
|
- <section id="pgsql-database-create">
|
|
|
- <title>Create PostgreSQL Database and Kea User</title>
|
|
|
- <para>
|
|
|
- The next task is to create both the lease database and the user under which the servers will
|
|
|
- access it. A number of steps are required:
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 1. Log into PostgreSQL as "root":
|
|
|
- <screen>$ <userinput>sudo -u postgres psql postgres</userinput>
|
|
|
-Enter password:<userinput/>
|
|
|
- :<userinput/>
|
|
|
-postgres=#</screen>
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 2. Create the database:
|
|
|
+ <listitem>
|
|
|
+ <para>
|
|
|
+ Create the database:
|
|
|
<screen>
|
|
|
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
|
|
|
CREATE DATABASE
|
|
|
postgres=#
|
|
|
</screen>
|
|
|
- (<replaceable>database-name</replaceable> is the name you
|
|
|
- have chosen for the database.)
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 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>
|
|
|
+ (<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>
|
|
|
CREATE ROLE
|
|
|
postgres=#
|
|
|
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
|
|
|
GRANT
|
|
|
postgres=#
|
|
|
</screen>
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 4. Exit PostgreSQL:
|
|
|
- <screen>postgres=# <userinput>\q</userinput>
|
|
|
-Bye<userinput/>
|
|
|
-$</screen>
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- 5. 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>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.pgsql</userinput>
|
|
|
+ </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>
|
|
|
+$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/dhcpdb_create.pgsql</userinput>
|
|
|
Password for user <replaceable>user-name</replaceable>:
|
|
|
CREATE TABLE
|
|
|
CREATE INDEX
|
|
|
@@ -292,36 +382,56 @@ INSERT 0 1
|
|
|
COMMIT
|
|
|
$
|
|
|
</screen>
|
|
|
- </para>
|
|
|
- <para>
|
|
|
- If instead you encounter an error like:
|
|
|
- </para>
|
|
|
+ (<replaceable>path-to-kea</replaceable> is the location
|
|
|
+ where you installed Kea.)
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ If instead you encounter an error like:
|
|
|
<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>
|
|
|
- ... 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>.
|
|
|
- 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:
|
|
|
- </para>
|
|
|
+ ... 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:
|
|
|
<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>
|
|
|
+ </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>
|
|
|
</section>
|
|
|
|
|
|
- </section> <!-- end of postgres sections -->
|
|
|
+ <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 -->
|
|
|
|
|
|
- </chapter>
|
|
|
+</chapter>
|
Stephen Morris