Commit 0228c239 authored by Suzanne Goldlust's avatar Suzanne Goldlust Committed by Michal Nowikowski
Browse files

Converting from docbook to sphinx: fixing links, editing grammar and style as needed

parent edfeb3f4
......@@ -124,7 +124,7 @@ backend may be essential for the success of your deployment.
| | | | | |
+---------------+----------------+----------------+---------------+--------------+
memfile
Memfile
-------
The memfile backend is able to store lease information, but cannot
......@@ -538,7 +538,7 @@ Year 2038 Issue
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that the MySQL database
doesn't accept timestamps beyond 2147483647 seconds (the maximum signed
32-bit number) from the beginning of the Unix epoch (00:00:00 on 1
32-bit number) from the beginning of the UNIX epoch (00:00:00 on 1
January 1970). 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 a restriction on the maximum timestamp to be
......
......@@ -26,7 +26,7 @@ client class to receive common options.
An incoming packet can be associated with a client class in several
ways:
- Implicitly, using a vendor class option or another builtin condition.
- Implicitly, using a vendor class option or another built-in condition.
- Using an expression which evaluates to true.
......@@ -49,7 +49,7 @@ The classification process is conducted in several steps:
2. Vendor class options are processed.
3. Classes with matching expressions and not marked for later evaluation ("on
request" or depending on the KNOWN/UNKNOWN builtin classes)
request" or depending on the KNOWN/UNKNOWN built-in classes)
are processed in the order they are defined in the
configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the
......@@ -74,7 +74,7 @@ The classification process is conducted in several steps:
packet is assigned to the UNKNOWN class.
7. Classes with matching expressions - directly, or indirectly using the
KNOWN/UNKNOWN builtin classes and not marked for later evaluation ("on
KNOWN/UNKNOWN built-in classes and not marked for later evaluation ("on
request") - are processed in the order they are defined
in the configuration; the boolean expression is evaluated and, if it
returns true ("match"), the incoming packet is associated with the
......@@ -128,10 +128,10 @@ value is obtained is unspecified.
.. _classification-using-vendor:
Builtin Client Classes
Built-in Client Classes
======================
Some classes are builtin, so they do not need to be defined. The main
Some classes are built-in, so they do not need to be defined. The main
example uses Vendor Class information: the server checks whether an
incoming DHCPv4 packet includes the vendor class identifier option (60)
or an incoming DHCPv6 packet includes the vendor class option (16). If
......@@ -150,13 +150,13 @@ be found in :ref:`high-availability-library`.
Other examples are the ALL class, which all incoming packets belong to,
and the KNOWN class, assigned when host reservations exist for a
particular client. By convention, builtin classes' names begin with all
particular client. By convention, built-in classes' names begin with all
capital letters.
Currently recognized builtin class names are ALL, KNOWN and UNKNOWN, and the
Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
prefix can be freely used; builtin classes are implicitly defined so
prefix can be freely used; built-in classes are implicitly defined so
they never raise warnings if they do not appear in the configuration.
.. _classification-using-expressions:
......@@ -186,7 +186,7 @@ in the operator returning an empty string.
Dependencies between classes are also checked. For instance, forward
dependencies are rejected when the configuration is parsed; an
expression can only depend on already-defined classes (including builtin
expression can only depend on already-defined classes (including built-in
classes) which are evaluated in a previous or the same evaluation phase.
This does not apply to the KNOWN or UNKNOWN classes.
......@@ -339,7 +339,7 @@ Notes:
- "member('foobar')" checks whether the packet belongs to the client
class "foobar". To avoid dependency loops, the configuration file
parser verifies whether client classes were already defined or are
builtin, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
built-in, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
"UNKNOWN", etc.
......
......@@ -280,12 +280,12 @@ information in a CSV file rather than a database. As well as requiring
less administration, an advantage of using a file for storage is that it
eliminates a dependency on third-party database software.
The configuration of the file backend (Memfile) is controlled through
The configuration of the file backend (memfile) is controlled through
the Dhcp4/lease-database parameters. The ``type`` parameter is mandatory
and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the
storage. The following list gives additional optional parameters that
can be used to configure the Memfile backend.
can be used to configure the memfile backend.
- ``persist``: controls whether the new leases and updates to existing
leases are written to the file. It is strongly recommended that the
......@@ -310,7 +310,7 @@ can be used to configure the Memfile backend.
value of the ``lfc-interval`` is ``3600``. A value of 0 disables the
LFC.
An example configuration of the Memfile backend is presented below:
An example configuration of the memfile backend is presented below:
::
......@@ -3944,7 +3944,7 @@ which belong to them.
}
Static class assignments, as shown above, can be used in conjunction
with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin
with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated.
......
......@@ -266,12 +266,12 @@ information in a CSV file rather than a database. As well as requiring
less administration, an advantage of using a file for storage is that it
eliminates a dependency on third-party database software.
The configuration of the file backend (Memfile) is controlled through
The configuration of the file backend (memfile) is controlled through
the Dhcp6/lease-database parameters. The ``type`` parameter is mandatory
and it specifies which storage for leases the server should use. The
value of ``"memfile"`` indicates that the file should be used as the
storage. The following list gives additional optional parameters that
can be used to configure the Memfile backend.
can be used to configure the memfile backend.
- ``persist``: controls whether the new leases and updates to existing
leases are written to the file. It is strongly recommended that the
......@@ -296,7 +296,7 @@ can be used to configure the Memfile backend.
default value of the ``lfc-interval`` is ``3600``. A value of 0
disables the LFC.
An example configuration of the Memfile backend is presented below:
An example configuration of the memfile backend is presented below:
::
......@@ -3433,7 +3433,7 @@ which belong to them.
}
Static class assignments, as shown above, can be used in conjunction
with classification, using expressions. The "KNOWN" or "UNKNOWN" builtin
with classification, using expressions. The "KNOWN" or "UNKNOWN" built-in
class is added to the packet and any class depending on it (directly or
indirectly) and not only-if-required is evaluated.
......@@ -4411,7 +4411,7 @@ configuration:
This very simple configuration provides DNS server information to
all clients in the network, regardless of their location. Note the
specification of the Memfile lease database; this is needed as Kea
specification of the memfile lease database; this is needed as Kea
requires a lease database to be specified even if it is not used.
.. _dhcp6-rfc7550:
......
This diff is collapsed.
......@@ -11,20 +11,20 @@ list client classes configured for a given server.
**Note**
This library may only be loaded by the ``kea-dhcp4`` or the
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
The Class Commands hooks library is available to premium Kea customers
only.
The Class Commands hooks library is currently available only to ISC
customers with a paid support contract.
.. _command-class-add:
class-add Command
-----------------
The class-add Command
---------------------
The ``class-add`` command adds a new client class to the DHCP server
configuration. This class is appended at the end of the list of classes
used by the server and may depend on any of the already configured
used by the server and may depend on any of the already-configured
client classes.
The following example demonstrates how to add a new client class to the
......@@ -61,12 +61,12 @@ Here is the response to the ``class-add`` command in our example:
.. _command-class-update:
class-update Command
--------------------
The class-update Command
------------------------
The ``class-update`` command updates an existing client class in the
DHCP server configuration. If the client class with the given name
doesn't exist, the server returns the result code of 3, which means that
does not exist, the server returns the result code of 3, which means that
the server configuration is not modified and the client class does not
exist. The ``class-add`` command must be used instead to create the new
client class.
......@@ -110,10 +110,10 @@ the new name will be added at the end of the list of configured classes.
.. _command-class-del:
class-del Command
-----------------
The class-del Command
---------------------
The ``class-del`` is used to remove a particular class from the server
The ``class-del`` command is used to remove a particular class from the server
configuration. The class to be removed is identified by name. The class
is not removed if there are other classes depending on it; to remove
such a class, the dependent classes must be removed first.
......@@ -145,8 +145,8 @@ If the class doesn't exist, the result of 3 is returned.
.. _command-class-list:
class-list Command
------------------
The class-list Command
----------------------
``class-list`` is used to retrieve a list of all client classes. This
command includes no arguments:
......@@ -183,8 +183,8 @@ merely class names. To retrieve full class information, the
.. _command-class-get:
class-get Command
-----------------
The class-get Command
---------------------
``class-get`` is used to retrieve detailed information about a specified
class. The command structure is very simple:
......
This diff is collapsed.
......@@ -5,12 +5,12 @@ lease_cmds: Lease Commands
This section describes the hook library with commands used to manage
leases. Kea provides a way to store lease information in several
backends (memfile, MySQL, PostgreSQL and Cassandra), and this library
provides a interface that can manipulate leases in a unified, safe way.
backends (memfile, MySQL, PostgreSQL, and Cassandra), and this library
provides an interface that can manipulate leases in a unified, safe way.
In particular, it allows things previously impossible: lease
manipulation in memfile while Kea is running, sanity check changes,
lease existence checks, and removal of all leases belonging to a
specific subnet. It can also catch more obscure errors, like an attempt
specific subnet. The hook library can also catch more obscure errors, like an attempt
to add a lease with a subnet-id that does not exist in the
configuration, or configuring a lease to use an address that is outside
of the subnet to which it is supposed to belong. The library also
......@@ -25,57 +25,57 @@ leases.
There are many use cases where an administrative command may be useful;
for example, during migration between servers or different vendors, when
a certain network is being retired, or when a device has been
disconnected and the sysadmin knows for sure that it will not be coming
disconnected and the system administrator knows that it will not be coming
back. The "get" queries may be useful for automating certain management
and monitoring tasks. They can also act as preparatory steps for lease
updates and removals.
This library provides the following commands:
- ``lease4-add`` - adds a new IPv4 lease;
- ``lease4-add`` - adds a new IPv4 lease.
- ``lease6-add`` - adds a new IPv6 lease;
- ``lease6-add`` - adds a new IPv6 lease.
- ``lease4-get`` - checks whether an IPv4 lease with the specified
parameters exists and returns it if it does;
parameters exists and returns it if it does.
- ``lease6-get`` - checks whether an IPv6 lease with the specified
parameters exists and returns it if it does;
parameters exists and returns it if it does.
- ``lease4-get-all`` - returns all IPv4 leases or all IPv4 leases for
the specified subnets;
the specified subnets.
- ``lease6-get-all`` - returns all IPv6 leases or all IPv6 leases for
the specified subnets;
the specified subnets.
- ``lease4-get-page`` - returns a set ("page") of leases from the list
of all IPv4 leases in the database. By iterating through the pages it
is possible to retrieve all the leases;
is possible to retrieve all the leases.
- ``lease6-get-page`` - returns a set ("page") of leases from the list
of all IPv6 leases in the database. By iterating through the pages it
is possible to retrieve all the leases;
is possible to retrieve all the leases.
- ``lease4-del`` - deletes an IPv4 lease with the specified parameters;
- ``lease4-del`` - deletes an IPv4 lease with the specified parameters.
- ``lease6-del`` - deletes an IPv6 lease with the specified parameters;
- ``lease6-del`` - deletes an IPv6 lease with the specified parameters.
- ``lease4-update`` - updates an IPv4 lease;
- ``lease4-update`` - updates an IPv4 lease.
- ``lease6-update`` - updates an IPv6 lease;
- ``lease6-update`` - updates an IPv6 lease.
- ``lease4-wipe`` - removes all leases from a specific IPv4 subnet or
from all subnets;
from all subnets.
- ``lease6-wipe`` - removes all leases from a specific IPv6 subnet or
from all subnets;
from all subnets.
The lease commands library is part of the open source code and is
available to every Kea user.
All commands use JSON syntax and can be issued either using control
channel (see `??? <#ctrl-channel>`__) or Control Agent (see
`??? <#kea-ctrl-agent>`__).
All commands use JSON syntax and can be issued either using the control
channel (see :ref:`ctrl-channel`) or Control Agent (see
:ref:`kea-ctrl-agent`).
The library can be loaded in the same way as other hook libraries, and
it does not take any parameters. It supports both DHCPv4 and DHCPv6
......@@ -83,19 +83,19 @@ servers.
::
"Dhcp6": {
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_lease_cmds.so"
}
...
]
]
}
.. _command-lease4-add:
lease4-add, lease6-add Commands
-------------------------------
The lease4-add, lease6-add Commands
-----------------------------------
The ``lease4-add`` and ``lease6-add`` commands allow for the creation of
a new lease. Typically Kea creates a lease when it first sees a new
......@@ -141,7 +141,7 @@ subnet. For example:
``lease6-add`` can also be used to add leases for IPv6 prefixes. In this
case there are three additional parameters that must be specified:
subnet-id, type (set to value of "IA_PD"), and prefix length. The actual
prefix is set using ip-address field. Note that Kea cannot guess
prefix is set using the ip-address field. Note that Kea cannot guess
subnet-id values for prefixes; they must be specified explicitly. For
example, to configure a lease for prefix 2001:db8:abcd::/48, the
following command can be used:
......@@ -160,19 +160,19 @@ following command can be used:
}
}
The commands can take a number of additional optional parameters:
The commands can take several additional optional parameters:
- ``valid-lft`` - specifies the lifetime of the lease, expressed in
seconds. If not specified, the value configured in the subnet related
to the specified subnet-id is used.
- ``expire`` - creates a timestamp of the lease expiration time,
expressed in unix format (seconds since 1 Jan 1970). If not
expressed in UNIX format (seconds since 1 Jan 1970). If not
specified, the default value is now + the lease lifetime (the value
of valid-lft).
- ``fqdn-fwd`` - specifies whether the lease should be marked as if a
forward DNS update were conducted. Note this only affects the the
forward DNS update were conducted. Note this only affects the
data stored in the lease database, and no DNS update will be
performed. If configured, a DNS update to remove the A or AAAA
records will be conducted when the lease is removed due to expiration
......@@ -228,8 +228,8 @@ Here is an example of a more complex lease addition:
}
}
The command returns a status that indicates either a success (result 0)
or a failure (result 1). A failed command always includes a text
The command returns a status that indicates either success (result 0)
or failure (result 1). A failed command always includes a text
parameter that explains the cause of failure. For example:
::
......@@ -244,14 +244,14 @@ Example failure:
.. _command-lease4-get:
lease4-get, lease6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-get, lease6-get Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-get`` or ``lease6-get`` can be used to query the lease database
and retrieve existing leases. There are two types of parameters the
``lease4-get`` command supports: (address) or (subnet-id,
identifier-type, identifier). There are also two types for
``lease6-get``: (address,type) or (subnet-id, identifier-type,
``lease6-get``: (address, type) or (subnet-id, identifier-type,
identifier, IAID, type). The first type of query is used when the
address (either IPv4 or IPv6) is known, but the details of the lease are
not; one common use case of this type of query is to find out whether a
......@@ -359,8 +359,8 @@ An example result returned when the host was found:
.. _command-lease4-get-all:
lease4-get-all, lease6-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-get-all, lease6-get-all Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-get-all`` and ``lease6-get-all`` are used to retrieve all IPv4
or IPv6 leases, or all leases for the specified set of subnets. All
......@@ -373,7 +373,7 @@ command, as in the following example:
"command": "lease4-get-all"
}
If the arguments are provided, it is expected that they contain the
If arguments are provided, it is expected that they contain the
"subnets" parameter, which is a list of subnet identifiers for which the
leases should be returned. For example, in order to retrieve all IPv6
leases belonging to the subnets with identifiers 1, 2, 3, and 4:
......@@ -444,8 +444,8 @@ following format:
.. _lease-get-page-cmds:
lease4-get-page, lease6-get-page Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-get-page, lease6-get-page Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease4-get-all`` and ``lease6-get-all`` commands may result in
very large responses; generating such a response may consume CPU
......@@ -567,11 +567,11 @@ leases were found.
.. _command-lease4-del:
lease4-del, lease6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-del, lease6-del Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``leaseX-del`` can be used to delete a lease from the lease database.
There are two types of parameters this command supports, similar to
There are two types of parameters this command supports, similar to the
leaseX-get commands: (address) for both v4 and v6, (subnet-id,
identifier-type, identifier) for v4, and (subnet-id, identifier-type,
identifier, type, IAID) for v6. The first type of query is used when the
......@@ -579,7 +579,7 @@ address (either IPv4 or IPv6) is known, but the details of the lease are
not. One common use case is where an administrator wants a specified
address to no longer be used. The second form of the command uses
identifiers. For maximum flexibility, this interface uses identifiers as
a pair of values: type and the actual identifier. The currently
a pair of values: the type and the actual identifier. The currently
supported identifiers are "hw-address" (IPv4 only), "client-id" (IPv4
only), and "duid" (IPv6 only).
......@@ -614,8 +614,8 @@ properly, but the object (a lease in this case) has not been found.
.. _command-lease4-update:
lease4-update, lease6-update Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-update, lease6-update Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``lease4-update`` and ``lease6-update`` commands can be used to
update existing leases. Since all lease database backends are indexed by
......@@ -629,8 +629,8 @@ subnet-selection procedure. If specified, however, its value must match
the existing subnet.
The optional boolean parameter "force-create" specifies whether the
lease should be created if it doesn't exist in the database. It defaults
to false, which indicates that the lease is not created if it doesn't
lease should be created if it does not exist in the database. It defaults
to false, which indicates that the lease is not created if it does not
exist. In such a case, an error is returned as a result of trying to
update a non-existing lease. If the "force-create" parameter is set to
true and the updated lease does not exist, the new lease is created as a
......@@ -669,13 +669,13 @@ An example of a command to update an IPv6 lease is:
.. _command-lease4-wipe:
lease4-wipe, lease6-wipe Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The lease4-wipe, lease6-wipe Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-wipe`` and ``lease6-wipe`` are designed to remove all leases
associated with a given subnet. This administrative task is expected to
be used when an existing subnet is being retired. Note that the leases
are not properly expired: no DNS updates are carried out, no log
are not properly expired; no DNS updates are carried out, no log
messages are created, and hooks are not called for the leases being
removed.
......
This diff is collapsed.
.. _installation:
************
Installation
************
......@@ -365,9 +367,9 @@ DHCP Database Installation and Configuration
Kea stores its leases in a lease database. The software has been written
in a way that makes it possible to choose which database product should
be used to store the lease information. Kea supports four
database backends: MySQL, PostgreSQL, Cassandra, and Memfile. To limit
database backends: MySQL, PostgreSQL, Cassandra, and memfile. To limit
external dependencies, MySQL, PostgreSQL, and Cassandra support are
disabled by default and only Memfile is available. Support for the
disabled by default and only memfile is available. Support for the
optional external database backend must be explicitly included when Kea
is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database.
......
......@@ -14,7 +14,7 @@ Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administr
.. toctree::
:numbered:
:maxdepth: 3
:maxdepth: 5
intro
quickstart
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment