From: Michal Nowikowski Date: Mon, 15 Jul 2019 06:32:02 +0000 (+0200) Subject: many improvements to docs based on sphinx X-Git-Tag: Kea-1.6.1~10^2~89 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b5b87d1849dc9bf2ad2591d7310646d154e5456d;p=thirdparty%2Fkea.git many improvements to docs based on sphinx - improved code-blocks - improved json formatting: more compact, replaced // to # for comments to make them highlighted - improved tables proportions - fixed kea version: |release| should be used instead of KEAVERSION - changed them to 'Read The Docs' to align with BIND - cleaned up conf.py - improved building in Makefile.am, now there are 3 targets (pdf, html, singlehtml) and 'all' that depends on those 3 - added kea.css to make html content wider and tables narrow to fit into text column --- diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index d43c785d0d..660fab97f9 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -33,18 +33,32 @@ rst_sources+=stats.rst sphinxbuild = sphinx-build -sphinxopts = -E -kea-guide.pdf: $(rst_sources) - @$(sphinxbuild) -b latex $(srcdir) $(builddir)/_build $(sphinxopts) +sphinxopts= +sphinxopts+=-v +sphinxopts+=-E +sphinxopts+=-a +sphinxopts+=-c "${abs_srcdir}" +sphinxopts+=-D release="@PACKAGE_VERSION@" +sphinxopts+=-D version="@PACKAGE_VERSION@" -kea-guide.html: $(rst_sources) - @$(sphinxbuild) -b singlehtml $(srcdir) $(builddir)/_build $(sphinxopts) +sphinxbuilddir=$(builddir)/_build -pages: $(rst_sources) - @$(sphinxbuild) -b html $(srcdir) $(builddir)/_build2 $(sphinxopts) +all: pdf html singlehtml + +pdf: $(rst_sources) + $(sphinxbuild) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts) + +html singlehtml: $(rst_sources) + $(sphinxbuild) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts) EXTRA_DIST = $(rst_sources) # TODO: here should be added some stuff for DIST, etc to be consumed by automake/autoconf + +clean:: + -rm -rf $(sphinxbuilddir) + + +.PHONY: all pdf html singlehtml diff --git a/doc/guide/_static/kea.css b/doc/guide/_static/kea.css new file mode 100644 index 0000000000..dff6239c0a --- /dev/null +++ b/doc/guide/_static/kea.css @@ -0,0 +1,12 @@ +/* give more screen width to the content as by default it is too narrow + and many tables and boxes are squeezed */ +.wy-nav-content { + max-width: 1100px; +} + +/* by default table content is not wrapped and then the tables + are pretty wide so removing that + */ +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: normal; +} diff --git a/doc/guide/admin.rst b/doc/guide/admin.rst index b069dd23d3..7c4f07fa96 100644 --- a/doc/guide/admin.rst +++ b/doc/guide/admin.rst @@ -179,7 +179,7 @@ To create the database: 1. Log into MySQL as "root": - :: + .. code-block:: console $ mysql -u root -p Enter password: @@ -187,16 +187,16 @@ To create the database: 2. Create the MySQL database: - :: + .. code-block:: mysql - mysql> CREATE DATABASE database-name; + mysql> CREATE DATABASE database_name; - (database-name is the name chosen for the database.) + (database_name is the name chosen for the database.) 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables: - :: + .. code-block:: mysql mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; @@ -209,7 +209,7 @@ To create the database: (Alternatively, the tables can be created by exiting MySQL and using the ``kea-admin`` tool, as explained below.) To do this: - :: + .. code-block:: mysql mysql> CONNECT database-name; mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql @@ -218,7 +218,7 @@ To create the database: 5. Exit MySQL: - :: + .. code-block:: mysql mysql> quit Bye @@ -227,7 +227,7 @@ To create the database: If the tables were not created in Step 4, run the ``kea-admin`` tool to create them now: -:: +.. code-block:: console $ kea-admin lease-init mysql -u database-user -p database-password -n database-name @@ -248,7 +248,7 @@ existing database will need to be upgraded. This can be done using the To check the current version of the database, use the following command: -:: +.. code-block:: console $ kea-admin lease-version mysql -u database-user -p database-password -n database-name @@ -262,7 +262,7 @@ 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: -:: +.. code-block:: console $ kea-admin lease-upgrade mysql -u database-user -p database-password -n database-name @@ -285,7 +285,7 @@ which the servers will access it. A number of steps are required: 1. Log into PostgreSQL as "root": - :: + .. code-block:: console $ sudo -u postgres psql postgres Enter password: @@ -293,7 +293,7 @@ which the servers will access it. A number of steps are required: 2. Create the database: - :: + .. code-block:: psql postgres=# CREATE DATABASE database-name; CREATE DATABASE @@ -304,7 +304,7 @@ which the servers will access it. A number of steps are required: 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database: - :: + .. code-block:: psql postgres=# CREATE USER user-name WITH PASSWORD 'password'; CREATE ROLE @@ -314,7 +314,7 @@ which the servers will access it. A number of steps are required: 4. Exit PostgreSQL: - :: + .. code-block:: psql postgres=# \q Bye @@ -328,7 +328,7 @@ which the servers will access it. A number of steps are required: completes, Kea will return to the shell prompt. The output should be similar to the following: - :: + .. code-block:: console $ psql -d database-name -U user-name -f path-to-kea/share/kea/scripts/pgsql/dhcpdb_create.pgsql Password for user user-name: @@ -388,7 +388,7 @@ Initialize the PostgreSQL Database Using kea-admin If the tables were not created manually, do so now by running the ``kea-admin`` tool: -:: +.. code-block:: console $ kea-admin lease-init pgsql -u database-user -p database-password -n database-name @@ -409,13 +409,13 @@ database backend type must be used in the commands. Use the following command to check the current schema version: -:: +.. code-block:: console $ kea-admin lease-version pgsql -u database-user -p database-password -n database-name Use the following command to perform an upgrade: -:: +.. code-block:: console $ kea-admin lease-upgrade pgsql -u database-user -p database-password -n database-name @@ -447,13 +447,13 @@ To create the database: 1. Export CQLSH_HOST environment variable: - :: + .. code-block:: console $ export CQLSH_HOST=localhost 2. Log into CQL: - :: + .. code-block:: console $ cqlsh cql> @@ -479,7 +479,7 @@ To create the database: If the tables were not created in Step 4, do so now by running the ``kea-admin`` tool: -:: +.. code-block:: console $ kea-admin lease-init cql -n database-name @@ -500,7 +500,7 @@ existing database will need to be upgraded. This can be done using the To check the current version of the database, use the following command: -:: +.. code-block:: console $ kea-admin lease-version cql -n database-name @@ -514,7 +514,7 @@ 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: -:: +.. code-block:: console $ kea-admin lease-upgrade cql -n database-name diff --git a/doc/guide/agent.rst b/doc/guide/agent.rst index d17e3dc394..ca8ddaf0f4 100644 --- a/doc/guide/agent.rst +++ b/doc/guide/agent.rst @@ -259,7 +259,7 @@ Starting the Control Agent The CA is started by running its binary and specifying the configuration file it should use. For example: -:: +.. code-block:: console $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf diff --git a/doc/guide/conf.py b/doc/guide/conf.py index 020ff469c0..e8ef7d822f 100644 --- a/doc/guide/conf.py +++ b/doc/guide/conf.py @@ -19,16 +19,10 @@ # -- Project information ----------------------------------------------------- -project = 'Kea Administrator Reference Manual' +project = 'Kea' copyright = '2019, Internet Systems Consortium' author = 'Internet Systems Consortium' -# The short X.Y version -version = '1.6' -# The full version, including alpha/beta/rc tags -release = '1.6.0' - - # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. @@ -75,7 +69,8 @@ pygments_style = None # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +#html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -146,39 +141,14 @@ man_pages = [ ] -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'KeaAdministratorReferenceManual', 'Kea Administrator Reference Manual Documentation', - author, 'KeaAdministratorReferenceManual', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for Epub output ------------------------------------------------- - -# Bibliographic Dublin Core info. -epub_title = project - -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - -# A list of files that should not be packed into the epub file. -epub_exclude_files = ['search.html'] - - # -- Extension configuration ------------------------------------------------- # -- Options for todo extension ---------------------------------------------- # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True + + +# custom setup hook +def setup(app): + app.add_stylesheet('kea.css') diff --git a/doc/guide/ctrl-channel.rst b/doc/guide/ctrl-channel.rst index af353b29e7..3650964beb 100644 --- a/doc/guide/ctrl-channel.rst +++ b/doc/guide/ctrl-channel.rst @@ -183,14 +183,14 @@ common UNIX/Linux tools such as ``socat`` and ``curl``. In order to control the given Kea service via a UNIX domain socket, use ``socat`` in interactive mode as follows: -:: +.. code-block:: console $ socat UNIX:/path/to/the/kea/socket - or in batch mode, include the "ignoreeof" option as shown below to ensure ``socat`` waits long enough for the server to respond: -:: +.. code-block:: console $ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof @@ -208,7 +208,7 @@ section. To use Kea's RESTful API with ``curl``, use the following: -:: +.. code-block:: console $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/ diff --git a/doc/guide/dhcp4-srv.rst b/doc/guide/dhcp4-srv.rst index e05acaa76f..671f7be4ac 100644 --- a/doc/guide/dhcp4-srv.rst +++ b/doc/guide/dhcp4-srv.rst @@ -1707,91 +1707,90 @@ currently has no means to validate it. .. table:: List of Standard DHCP Option Types - +-----------------------------------+-------------------------------------------------------+ - | Name | Meaning | - +===================================+=======================================================+ - | binary | An arbitrary string of bytes, | - | | specified as a set of hexadecimal | - | | digits. | - +-----------------------------------+-------------------------------------------------------+ - | boolean | A boolean value with allowed | - | | values true or false. | - +-----------------------------------+-------------------------------------------------------+ - | empty | No value; data is carried in | - | | sub-options. | - +-----------------------------------+-------------------------------------------------------+ - | fqdn | Fully qualified domain name (e.g. | - | | www.example.com). | - +-----------------------------------+-------------------------------------------------------+ - | ipv4-address | IPv4 address in the usual | - | | dotted-decimal notation (e.g. | - | | 192.0.2.1). | - +-----------------------------------+-------------------------------------------------------+ - | ipv6-address | IPv6 address in the usual colon | - | | notation (e.g. 2001:db8::1). | - +-----------------------------------+-------------------------------------------------------+ - | ipv6-prefix | IPv6 prefix and prefix length | - | | specified using CIDR notation, | - | | e.g. 2001:db8:1::/64. This data | - | | type is used to represent an | - | | 8-bit field conveying a prefix | - | | length and the variable length | - | | prefix value. | - +-----------------------------------+-------------------------------------------------------+ - | psid | PSID and PSID length separated by | - | | a slash, e.g. 3/4 specifies | - | | PSID=3 and PSID length=4. In the | - | | wire format it is represented by | - | | an 8-bit field carrying PSID | - | | length (in this case equal to 4) | - | | and the 16-bits-long PSID value | - | | field (in this case equal to | - | | "0011000000000000b" using binary | - | | notation). Allowed values for a | - | | PSID length are 0 to 16. See `RFC | - | | 7597 `__ | - | | for details about the PSID wire | - | | representation. | - +-----------------------------------+-------------------------------------------------------+ - | record | Structured data that may be | - | | comprised of any types (except | - | | "record" and "empty"). The array | - | | flag applies to the last field | - | | only. | - +-----------------------------------+-------------------------------------------------------+ - | string | Any text. Please note that Kea | - | | will silently discard any | - | | terminating/trailing nulls from | - | | the end of 'string' options when | - | | unpacking received packets. This | - | | is in keeping with `RFC 2132, | - | | Section | - | | 2 `__. | - +-----------------------------------+-------------------------------------------------------+ - | tuple | A length encoded as an 8- (16- | - | | for DHCPv6) bit unsigned integer | - | | followed by a string of this | - | | length. | - +-----------------------------------+-------------------------------------------------------+ - | uint8 | 8-bit unsigned integer with | - | | allowed values 0 to 255. | - +-----------------------------------+-------------------------------------------------------+ - | uint16 | 16-bit unsigned integer with | - | | allowed values 0 to 65535. | - +-----------------------------------+-------------------------------------------------------+ - | uint32 | 32-bit unsigned integer with | - | | allowed values 0 to 4294967295. | - +-----------------------------------+-------------------------------------------------------+ - | int8 | 8-bit signed integer with allowed | - | | values -128 to 127. | - +-----------------------------------+-------------------------------------------------------+ - | int16 | 16-bit signed integer with | - | | allowed values -32768 to 32767. | - +-----------------------------------+-------------------------------------------------------+ - | int32 | 32-bit signed integer with | - | | allowed values -2147483648 to | - | | 2147483647. | - +-----------------------------------+-------------------------------------------------------+ + +-----------------+-------------------------------------------------------+ + | Name | Meaning | + +=================+=======================================================+ + | binary | An arbitrary string of bytes, specified as a set | + | | of hexadecimal digits. | + +-----------------+-------------------------------------------------------+ + | boolean | A boolean value with allowed | + | | values true or false. | + +-----------------+-------------------------------------------------------+ + | empty | No value; data is carried in | + | | sub-options. | + +-----------------+-------------------------------------------------------+ + | fqdn | Fully qualified domain name (e.g. | + | | www.example.com). | + +-----------------+-------------------------------------------------------+ + | ipv4-address | IPv4 address in the usual | + | | dotted-decimal notation (e.g. | + | | 192.0.2.1). | + +-----------------+-------------------------------------------------------+ + | ipv6-address | IPv6 address in the usual colon | + | | notation (e.g. 2001:db8::1). | + +-----------------+-------------------------------------------------------+ + | ipv6-prefix | IPv6 prefix and prefix length | + | | specified using CIDR notation, | + | | e.g. 2001:db8:1::/64. This data | + | | type is used to represent an | + | | 8-bit field conveying a prefix | + | | length and the variable length | + | | prefix value. | + +-----------------+-------------------------------------------------------+ + | psid | PSID and PSID length separated by | + | | a slash, e.g. 3/4 specifies | + | | PSID=3 and PSID length=4. In the | + | | wire format it is represented by | + | | an 8-bit field carrying PSID | + | | length (in this case equal to 4) | + | | and the 16-bits-long PSID value | + | | field (in this case equal to | + | | "0011000000000000b" using binary | + | | notation). Allowed values for a | + | | PSID length are 0 to 16. See `RFC | + | | 7597 `__ | + | | for details about the PSID wire | + | | representation. | + +-----------------+-------------------------------------------------------+ + | record | Structured data that may be | + | | comprised of any types (except | + | | "record" and "empty"). The array | + | | flag applies to the last field | + | | only. | + +-----------------+-------------------------------------------------------+ + | string | Any text. Please note that Kea | + | | will silently discard any | + | | terminating/trailing nulls from | + | | the end of 'string' options when | + | | unpacking received packets. This | + | | is in keeping with `RFC 2132, | + | | Section | + | | 2 `__. | + +-----------------+-------------------------------------------------------+ + | tuple | A length encoded as an 8- (16- | + | | for DHCPv6) bit unsigned integer | + | | followed by a string of this | + | | length. | + +-----------------+-------------------------------------------------------+ + | uint8 | 8-bit unsigned integer with | + | | allowed values 0 to 255. | + +-----------------+-------------------------------------------------------+ + | uint16 | 16-bit unsigned integer with | + | | allowed values 0 to 65535. | + +-----------------+-------------------------------------------------------+ + | uint32 | 32-bit unsigned integer with | + | | allowed values 0 to 4294967295. | + +-----------------+-------------------------------------------------------+ + | int8 | 8-bit signed integer with allowed | + | | values -128 to 127. | + +-----------------+-------------------------------------------------------+ + | int16 | 16-bit signed integer with | + | | allowed values -32768 to 32767. | + +-----------------+-------------------------------------------------------+ + | int32 | 32-bit signed integer with | + | | allowed values -2147483648 to | + | | 2147483647. | + +-----------------+-------------------------------------------------------+ .. _dhcp4-custom-options: @@ -2893,26 +2892,26 @@ table: .. table:: Default FQDN Flag Behavior - +-----------------+-----------------+-----------------+-----------------+ - | Client | Client Intent | Server Response | Server | - | Flags:N-S | | | Flags:N-S-O | - +=================+=================+=================+=================+ - | 0-0 | Client wants to | Server | 1-0-0 | - | | do forward | generates | | - | | updates, server | reverse-only | | - | | should do | request | | - | | reverse updates | | | - +-----------------+-----------------+-----------------+-----------------+ - | 0-1 | Server should | Server | 0-1-0 | - | | do both forward | generates | | - | | and reverse | request to | | - | | updates | update both | | - | | | directions | | - +-----------------+-----------------+-----------------+-----------------+ - | 1-0 | Client wants no | Server does not | 1-0-0 | - | | updates done | generate a | | - | | | request | | - +-----------------+-----------------+-----------------+-----------------+ + +------------+---------------------+-----------------+-------------+ + | Client | Client Intent | Server Response | Server | + | Flags:N-S | | | Flags:N-S-O | + +============+=====================+=================+=============+ + | 0-0 | Client wants to | Server | 1-0-0 | + | | do forward | generates | | + | | updates, server | reverse-only | | + | | should do | request | | + | | reverse updates | | | + +------------+---------------------+-----------------+-------------+ + | 0-1 | Server should | Server | 0-1-0 | + | | do both forward | generates | | + | | and reverse | request to | | + | | updates | update both | | + | | | directions | | + +------------+---------------------+-----------------+-------------+ + | 1-0 | Client wants no | Server does not | 1-0-0 | + | | updates done | generate a | | + | | | request | | + +------------+---------------------+-----------------+-------------+ The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and @@ -4142,8 +4141,8 @@ following can be used: :: "Dhcp4:" { - // This specifies global reservations. They will apply to all subnets that - // have global reservations enabled. + # This specifies global reservations. They will apply to all subnets that + # have global reservations enabled. "reservations": [ { @@ -4154,9 +4153,9 @@ following can be used: "hw-address": "01:02:03:04:05:06", "hostname": "hw-host-fixed", - // Use of IP address in global reservation is risky. If used outside of - // a matching subnet, such as 192.0.1.0/24, it will result in a broken - // configuration being handed to the client. + # Use of IP address in global reservation is risky. If used outside of + # a matching subnet, such as 192.0.1.0/24, it will result in a broken + # configuration being handed to the client. "ip-address": "192.0.1.77" }, { @@ -4249,17 +4248,17 @@ introduced: "Dhcp4": { "shared-networks": [ { - // Name of the shared network. It may be an arbitrary string - // and it must be unique among all shared networks. + # Name of the shared network. It may be an arbitrary string + # and it must be unique among all shared networks. "name": "my-secret-lair-level-1", - // The subnet selector can be specified at the shared network level. - // Subnets from this shared network will be selected for directly - // connected clients sending requests to server's "eth0" interface. + # The subnet selector can be specified at the shared network level. + # Subnets from this shared network will be selected for directly + # connected clients sending requests to server's "eth0" interface. "interface": "eth0", - // This starts a list of subnets in this shared network. - // There are two subnets in this example. + # This starts a list of subnets in this shared network. + # There are two subnets in this example. "subnet4": [ { "subnet": "10.0.0.0/8", @@ -4270,13 +4269,13 @@ introduced: "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] } ], - } ], // end of shared-networks + } ], # end of shared-networks - // It is likely that in the network there will be a mix of regular, - // "plain" subnets and shared networks. It is perfectly valid to mix - // them in the same configuration file. - // - // This is a regular subnet. It is not part of any shared network. + # It is likely that in the network there will be a mix of regular, + # "plain" subnets and shared networks. It is perfectly valid to mix + # them in the same configuration file. + # + # This is a regular subnet. It is not part of any shared network. "subnet4": [ { "subnet": "192.0.3.0/24", @@ -4285,7 +4284,7 @@ introduced: } ] - } // end of Dhcp4 + } # end of Dhcp4 } As demonstrated in the example, it is possible to mix shared and regular @@ -4315,12 +4314,12 @@ then override its value in the subnet scope. For example: "interface": "eth0", - // This applies to all subnets in this shared network, unless - // values are overridden on subnet scope. + # This applies to all subnets in this shared network, unless + # values are overridden on subnet scope. "valid-lifetime": 600, - // This option is made available to all subnets in this shared - // network. + # This option is made available to all subnets in this shared + # network. "option-data": [ { "name": "log-servers", "data": "1.2.3.4" @@ -4331,7 +4330,7 @@ then override its value in the subnet scope. For example: "subnet": "10.0.0.0/8", "pools": [ { "pool": "10.0.0.1 - 10.0.0.99" } ], - // This particular subnet uses different values. + # This particular subnet uses different values. "valid-lifetime": 1200, "option-data": [ { @@ -4347,8 +4346,8 @@ then override its value in the subnet scope. For example: "subnet": "192.0.2.0/24", "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ], - // This subnet does not specify its own valid-lifetime value, - // so it is inherited from shared network scope. + # This subnet does not specify its own valid-lifetime value, + # so it is inherited from shared network scope. "option-data": [ { "name": "routers", @@ -4389,8 +4388,8 @@ convenient to specify it once at the shared network level. { "name": "office-floor-2", - // This tells Kea that the whole shared network is reachable over a - // local interface. This applies to all subnets in this network. + # This tells Kea that the whole shared network is reachable over a + # local interface. This applies to all subnets in this network. "interface": "eth0", "subnet4": [ @@ -4403,9 +4402,9 @@ convenient to specify it once at the shared network level. "subnet": "192.0.2.0/24", "pools": [ { "pool": "192.0.2.100 - 192.0.2.199" } ] - // Specifying a different interface name is a configuration - // error: - // "interface": "eth1" + # Specifying a different interface name is a configuration + # error: + # "interface": "eth1" } ] } ] @@ -5390,29 +5389,25 @@ of LED devices could be configured in the following way: :: "Dhcp4": { - "subnet4": [ - { - "subnet": "192.0.2.0/24", - "pools": [ { - "pool": "192.0.2.10 - 192.0.2.20", - // This is pool specific user context - "user-context": { "color": "red" } - } ], - - // This is a subnet-specific user context. Any type - // of information can be entered here as long as it is valid JSON. - "user-context": { - "comment": "network on the second floor", - "last-modified": "2017-09-04 13:32", - "description": "you can put anything you like here", - "phones": [ "x1234", "x2345" ], - "devices-registered": 42, - "billing": false - } - }, - ... - ], - ... + "subnet4": [{ + "subnet": "192.0.2.0/24", + "pools": [{ + "pool": "192.0.2.10 - 192.0.2.20", + # This is pool specific user context + "user-context": { "color": "red" } + }], + + # This is a subnet-specific user context. Any type + # of information can be entered here as long as it is valid JSON. + "user-context": { + "comment": "network on the second floor", + "last-modified": "2017-09-04 13:32", + "description": "you can put anything you like here", + "phones": [ "x1234", "x2345" ], + "devices-registered": 42, + "billing": false + } + }], } Kea does not interpret or use the user context information; it simply stores it and makes it @@ -5605,31 +5600,23 @@ Consider the following configuration snippet: :: - { - "Dhcp4": { - "config-control": { - "config-databases": [ - { - "type": "mysql", - "name": "kea", - "user": "kea", - "password": "kea", - "host": "192.0.2.1", - "port": 3302 - } - ], - "config-fetch-wait-time": 20 - }, - "hooks-libraries": [ - { - "library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so" - }, - { - "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so" - } - ], - ... - } + "Dhcp4": { + "config-control": { + "config-databases": [{ + "type": "mysql", + "name": "kea", + "user": "kea", + "password": "kea", + "host": "192.0.2.1", + "port": 3302 + }], + "config-fetch-wait-time": 20 + }, + "hooks-libraries": [{ + "library": "/usr/local/lib/kea/hooks/libdhcp_mysql_cb.so" + }, { + "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so" + }], } The ``config-control`` command contains two parameters. ``config-databases`` diff --git a/doc/guide/dhcp6-srv.rst b/doc/guide/dhcp6-srv.rst index 6b5fd0e860..ca9b89d2a5 100644 --- a/doc/guide/dhcp6-srv.rst +++ b/doc/guide/dhcp6-srv.rst @@ -3635,8 +3635,9 @@ following can be used: :: "Dhcp6:" { - // This specifies global reservations. They will apply to all subnets that - // have global reservations enabled. + # This specifies global reservations. + # They will apply to all subnets that + # have global reservations enabled. "reservations": [ { @@ -3647,9 +3648,10 @@ following can be used: "hw-address": "01:02:03:04:05:06", "hostname": "hw-host-fixed", - // Use of IP address in global reservation is risky. If used outside of - // matching subnet, such as 3001::/64, it will result in a broken - // configuration being handed to the client. + # Use of IP address in global reservation is risky. + # If used outside of matching subnet, such as 3001::/64, + # it will result in a broken configuration being handed + # to the client. "ip-address": "2001:db8:ff::77" }, { @@ -3732,52 +3734,44 @@ introduced: :: - { "Dhcp6": { - "shared-networks": [ - { - // Name of the shared network. It may be an arbitrary string - // and it must be unique among all shared networks. - "name": "ipv6-lab-1", - - // The subnet selector can be specified on the shared network level. - // Subnets from this shared network will be selected for clients - // communicating via relay agent having the specified IP address. - "relay": { - "ip-addresses": [ "2001:db8:2:34::1" ] - }, - - // This starts a list of subnets in this shared network. - // There are two subnets in this example. - "subnet6": [ - { - "subnet": "2001:db8::/48", - "pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ] - }, - { - "subnet": "3ffe:ffe::/64", - "pools": [ { "pool": "3ffe:ffe::/64" } ] - } - ] - } ], // end of shared-networks + "shared-networks": [{ + # Name of the shared network. It may be an arbitrary string + # and it must be unique among all shared networks. + "name": "ipv6-lab-1", + + # The subnet selector can be specified on the shared network + # level. Subnets from this shared network will be selected + # for clients communicating via relay agent having + # the specified IP address. + "relay": { + "ip-addresses": [ "2001:db8:2:34::1" ] + }, - // It is likely that in the network there will be a mix of regular, - // "plain" subnets and shared networks. It is perfectly valid to mix - // them in the same configuration file. - // - // This is a regular subnet. It is not part of any shared-network. - "subnet6": [ - { - "subnet": "2001:db9::/48", - "pools": [ { "pool": "2001:db9::/64" } ], - "relay": { - "ip-addresses": [ "2001:db8:1:2::1" ] - } + # This starts a list of subnets in this shared network. + # There are two subnets in this example. + "subnet6": [{ + "subnet": "2001:db8::/48", + "pools": [{ "pool": "2001:db8::1 - 2001:db8::ffff" }] + }, { + "subnet": "3ffe:ffe::/64", + "pools": [{ "pool": "3ffe:ffe::/64" }] + }] + }], # end of shared-networks + + # It is likely that in the network there will be a mix of regular, + # "plain" subnets and shared networks. It is perfectly valid + # to mix them in the same configuration file. + # + # This is a regular subnet. It is not part of any shared-network. + "subnet6": [{ + "subnet": "2001:db9::/48", + "pools": [{ "pool": "2001:db9::/64" }], + "relay": { + "ip-addresses": [ "2001:db8:1:2::1" ] } - ] - - } // end of Dhcp6 - } + }] + } # end of Dhcp6 As demonstrated in the example, it is possible to mix shared and regular ("plain") subnets. Each shared network must have a unique name. This is @@ -3807,12 +3801,12 @@ then override its value in the subnet scope. For example: "ip-addresses": [ "2001:db8:2:34::1" ] }, - // This applies to all subnets in this shared network, unless - // values are overridden on subnet scope. + # This applies to all subnets in this shared network, unless + # values are overridden on subnet scope. "valid-lifetime": 600, - // This option is made available to all subnets in this shared - // network. + # This option is made available to all subnets in this shared + # network. "option-data": [ { "name": "dns-servers", "data": "2001:db8::8888" @@ -3823,7 +3817,7 @@ then override its value in the subnet scope. For example: "subnet": "2001:db8:1::/48", "pools": [ { "pool": "2001:db8:1::1 - 2001:db8:1::ffff" } ], - // This particular subnet uses different values. + # This particular subnet uses different values. "valid-lifetime": 1200, "option-data": [ { @@ -3839,8 +3833,8 @@ then override its value in the subnet scope. For example: "subnet": "2001:db8:2::/48", "pools": [ { "pool": "2001:db8:2::1 - 2001:db8:2::ffff" } ], - // This subnet does not specify its own valid-lifetime value, - // so it is inherited from shared network scope. + # This subnet does not specify its own valid-lifetime value, + # so it is inherited from shared network scope. "option-data": [ { "name": "dns-servers", @@ -3888,8 +3882,8 @@ convenient to specify it once at the shared network level. { "name": "office-floor-2", - // This tells Kea that the whole shared network is reachable over a - // local interface. This applies to all subnets in this network. + # This tells Kea that the whole shared network is reachable over a + # local interface. This applies to all subnets in this network. "interface": "eth0", "subnet6": [ @@ -3902,9 +3896,9 @@ convenient to specify it once at the shared network level. "subnet": "3ffe:abcd::/64", "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ] - // Specifying a different interface name is a configuration - // error: - // "interface": "eth1" + # Specifying a different interface name is a configuration + # error: + # "interface": "eth1" } ], } ] @@ -5410,7 +5404,7 @@ option is actually needed. An example configuration looks as follows: "prefix-len": 56, "delegated-len": 64, - // This is a pool specific context. + # This is a pool specific context. "user-context": { "threshold-percent": 85, "v4-network": "192.168.0.0/16", @@ -5423,8 +5417,8 @@ option is actually needed. An example configuration looks as follows: } ], "subnet": "2001:db8::/32", - // This is a subnet-specific context. Any type of - // information can be entered here as long as it is valid JSON. + # This is a subnet-specific context. Any type of + # information can be entered here as long as it is valid JSON. "user-context": { "comment": "Those v4-v6 migration technologies are tricky.", "experimental": true, diff --git a/doc/guide/hammer.rst b/doc/guide/hammer.rst index 3a9e2479f4..77e1ab755d 100644 --- a/doc/guide/hammer.rst +++ b/doc/guide/hammer.rst @@ -21,9 +21,9 @@ please do so with care. The first-time user is strongly encouraged to look at Hammer's built-in help: -:: +.. code-block:: console - ./hammer.py --help + $ ./hammer.py --help It will list available parameters. @@ -31,9 +31,9 @@ Hammer is able to set up various operating systems running either in LXC or in VirtualBox. To list of supported systems, use the ``supported-systems`` command: -:: +.. code-block:: console - $./hammer.py supported-systems + $ ./hammer.py supported-systems fedora: - 27: lxc, virtualbox - 28: lxc, virtualbox @@ -61,9 +61,9 @@ First, you must install the Hammer dependencies: Vagrant and either VirtualBox or LXC. To make life easier, Hammer can install Vagrant and the required Vagrant plugins using the command: -:: +.. code-block:: console - ./hammer.py ensure-hammer-deps + $ ./hammer.py ensure-hammer-deps VirtualBox and LXC need to be installed manually. @@ -71,9 +71,9 @@ The basic functions provided by Hammer are to prepare the build environment and perform the actual build, and to run the unit tests locally in the current system. This can be achieved by running the command: -:: +.. code-block:: console - ./hammer.py build -p local + $ ./hammer.py build -p local The scope of the process can be defined using --with (-w) and --without (-x) options. By default the build command will build Kea with @@ -81,9 +81,9 @@ documentation, install it locally, and run unit tests. To exclude the installation and generation of docs, type: -:: +.. code-block:: console - ./hammer.py build -p local -x install docs + $ ./hammer.py build -p local -x install docs The basic scope can be extended by: mysql, pgsql, cql, native-pkg, radius, shell, and forge. @@ -96,16 +96,16 @@ radius, shell, and forge. Hammer can be told to set up a new virtual machine with a specified operating system, without the build: -:: +.. code-block:: console - ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0 + $ ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0 This way we can prepare a system for our own use. To get to such a system using SSH, invoke: -:: +.. code-block:: console - ./hammer.py ssh -p virtualbox -s freebsd -r 12.0 + $ ./hammer.py ssh -p virtualbox -s freebsd -r 12.0 It is possible to speed up subsequent Hammer builds. To achieve this Hammer employs `ccache `__. During @@ -116,9 +116,9 @@ or LXC. To indicate the folder, you must indicate the --ccache-dir parameter for Hammer. In the indicated folder, there are separate stored objects for each target operating system. -:: +.. code-block:: console - ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache + $ ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache .. @@ -130,6 +130,6 @@ operating system. For more information check: -:: +.. code-block:: console - ./hammer.py --help + $ ./hammer.py --help diff --git a/doc/guide/hooks-ha.rst b/doc/guide/hooks-ha.rst index f1a9836593..e27ab9bc5b 100644 --- a/doc/guide/hooks-ha.rst +++ b/doc/guide/hooks-ha.rst @@ -341,80 +341,57 @@ with the only difference that ``this-server-name`` should be set to :: - { "Dhcp4": { - - ... - - "hooks-libraries": [ - { - "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", - "parameters": { } - }, - { - "library": "/usr/lib/kea/hooks/libdhcp_ha.so", - "parameters": { - "high-availability": [ { - "this-server-name": "server1", - "mode": "load-balancing", - "heartbeat-delay": 10000, - "max-response-delay": 10000, - "max-ack-delay": 5000, - "max-unacked-clients": 5, - "peers": [ - { - "name": "server1", - "url": "http://192.168.56.33:8080/", - "role": "primary", - "auto-failover": true - }, - { - "name": "server2", - "url": "http://192.168.56.66:8080/", - "role": "secondary", - "auto-failover": true - }, - { - "name": "server3", - "url": "http://192.168.56.99:8080/", - "role": "backup", - "auto-failover": false - } - ] - } ] - } + "hooks-libraries": [{ + "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, { + "library": "/usr/lib/kea/hooks/libdhcp_ha.so", + "parameters": { + "high-availability": [{ + "this-server-name": "server1", + "mode": "load-balancing", + "heartbeat-delay": 10000, + "max-response-delay": 10000, + "max-ack-delay": 5000, + "max-unacked-clients": 5, + "peers": [{ + "name": "server1", + "url": "http://192.168.56.33:8080/", + "role": "primary", + "auto-failover": true + }, { + "name": "server2", + "url": "http://192.168.56.66:8080/", + "role": "secondary", + "auto-failover": true + }, { + "name": "server3", + "url": "http://192.168.56.99:8080/", + "role": "backup", + "auto-failover": false + }] + }] } - ], - - "subnet4": [ - { - "subnet": "192.0.3.0/24", - "pools": [ - { - "pool": "192.0.3.100 - 192.0.3.150", - "client-class": "HA_server1" - }, - { - "pool": "192.0.3.200 - 192.0.3.250", - "client-class": "HA_server2" - } - ], - - "option-data": [ - { - "name": "routers", - "data": "192.0.3.1" - } - ], - - "relay": { "ip-address": "10.1.2.3" } - } - ], - - ... - - } - + }], + + "subnet4": [{ + "subnet": "192.0.3.0/24", + "pools": [{ + "pool": "192.0.3.100 - 192.0.3.150", + "client-class": "HA_server1" + }, { + "pool": "192.0.3.200 - 192.0.3.250", + "client-class": "HA_server2" + }], + + "option-data": [{ + "name": "routers", + "data": "192.0.3.1" + }], + + "relay": { "ip-address": "10.1.2.3" } + }] } Two hook libraries must be loaded to enable HA: @@ -566,90 +543,62 @@ HA hook library configuration has been removed from this example. :: - { "Dhcp4": { - - "client-classes": [ - { - "name": "phones", - "test": "substring(option[60].hex,0,6) == 'Aastra'", - }, - { - "name": "laptops", - "test": "not member('phones')" - }, - { - "name": "phones_server1", - "test": "member('phones') and member('HA_server1')" - }, - { - "name": "phones_server2", - "test": "member('phones') and member('HA_server2')" - }, - { - "name": "laptops_server1", - "test": "member('laptops') and member('HA_server1')" - }, - { - "name": "laptops_server2", - "test": "member('laptops') and member('HA_server2')" - } - ], - - "hooks-libraries": [ - { - "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", - "parameters": { } - }, - { - "library": "/usr/lib/kea/hooks/libdhcp_ha.so", - "parameters": { - "high-availability": [ { - - ... - - } ] - } + "client-classes": [{ + "name": "phones", + "test": "substring(option[60].hex,0,6) == 'Aastra'", + }, { + "name": "laptops", + "test": "not member('phones')" + }, { + "name": "phones_server1", + "test": "member('phones') and member('HA_server1')" + }, { + "name": "phones_server2", + "test": "member('phones') and member('HA_server2')" + }, { + "name": "laptops_server1", + "test": "member('laptops') and member('HA_server1')" + }, { + "name": "laptops_server2", + "test": "member('laptops') and member('HA_server2')" + }], + + "hooks-libraries": [{ + "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, { + "library": "/usr/lib/kea/hooks/libdhcp_ha.so", + "parameters": { + "high-availability": [{ + ... + }] } - ], - - "subnet4": [ - { - "subnet": "192.0.3.0/24", - "pools": [ - { - "pool": "192.0.3.100 - 192.0.3.125", - "client-class": "phones_server1" - }, - { - "pool": "192.0.3.126 - 192.0.3.150", - "client-class": "laptops_server1" - }, - { - "pool": "192.0.3.200 - 192.0.3.225", - "client-class": "phones_server2" - }, - { - "pool": "192.0.3.226 - 192.0.3.250", - "client-class": "laptops_server2" - } - ], - - "option-data": [ - { - "name": "routers", - "data": "192.0.3.1" - } - ], - - "relay": { "ip-address": "10.1.2.3" } - } - ], - - ... - - } - + }], + + "subnet4": [{ + "subnet": "192.0.3.0/24", + "pools": [{ + "pool": "192.0.3.100 - 192.0.3.125", + "client-class": "phones_server1" + }, { + "pool": "192.0.3.126 - 192.0.3.150", + "client-class": "laptops_server1" + }, { + "pool": "192.0.3.200 - 192.0.3.225", + "client-class": "phones_server2" + }, { + "pool": "192.0.3.226 - 192.0.3.250", + "client-class": "laptops_server2" + }], + + "option-data": [{ + "name": "routers", + "data": "192.0.3.1" + }], + + "relay": { "ip-address": "10.1.2.3" } + }], } The configuration provided above splits the address range into four @@ -677,76 +626,54 @@ hot-standby configuration: :: - { "Dhcp4": { - - ... - - "hooks-libraries": [ - { - "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", - "parameters": { } - }, - { - "library": "/usr/lib/kea/hooks/libdhcp_ha.so", - "parameters": { - "high-availability": [ { - "this-server-name": "server1", - "mode": "hot-standby", - "heartbeat-delay": 10000, - "max-response-delay": 10000, - "max-ack-delay": 5000, - "max-unacked-clients": 5, - "peers": [ - { - "name": "server1", - "url": "http://192.168.56.33:8080/", - "role": "primary", - "auto-failover": true - }, - { - "name": "server2", - "url": "http://192.168.56.66:8080/", - "role": "standby", - "auto-failover": true - }, - { - "name": "server3", - "url": "http://192.168.56.99:8080/", - "role": "backup", - "auto-failover": false - } - ] - } ] - } - } - ], - - "subnet4": [ - { - "subnet": "192.0.3.0/24", - "pools": [ - { - "pool": "192.0.3.100 - 192.0.3.250", - "client-class": "HA_server1" - } - ], - - "option-data": [ - { - "name": "routers", - "data": "192.0.3.1" - } - ], - - "relay": { "ip-address": "10.1.2.3" } + "hooks-libraries": [{ + "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, { + "library": "/usr/lib/kea/hooks/libdhcp_ha.so", + "parameters": { + "high-availability": [{ + "this-server-name": "server1", + "mode": "hot-standby", + "heartbeat-delay": 10000, + "max-response-delay": 10000, + "max-ack-delay": 5000, + "max-unacked-clients": 5, + "peers": [{ + "name": "server1", + "url": "http://192.168.56.33:8080/", + "role": "primary", + "auto-failover": true + }, { + "name": "server2", + "url": "http://192.168.56.66:8080/", + "role": "standby", + "auto-failover": true + }, { + "name": "server3", + "url": "http://192.168.56.99:8080/", + "role": "backup", + "auto-failover": false + }] + }] } - ], - - ... - - } - + }], + + "subnet4": [{ + "subnet": "192.0.3.0/24", + "pools": [{ + "pool": "192.0.3.100 - 192.0.3.250", + "client-class": "HA_server1" + }], + + "option-data": [{ + "name": "routers", + "data": "192.0.3.1" + }], + + "relay": { "ip-address": "10.1.2.3" } + }] } This configuration is very similar to the load-balancing configuration diff --git a/doc/guide/hooks-host-cache.rst b/doc/guide/hooks-host-cache.rst index 230acf67ae..44168316ae 100644 --- a/doc/guide/hooks-host-cache.rst +++ b/doc/guide/hooks-host-cache.rst @@ -31,14 +31,14 @@ any other hooks library; for example, this configuration could be used: "Dhcp4": { - // Your regular DHCPv4 configuration parameters here. + # Your regular DHCPv4 configuration parameters here. "hooks-libraries": [ { "library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so", "parameters": { - // Tells Kea to never cache more than 1000 hosts. + # Tells Kea to never cache more than 1000 hosts. "maximum": 1000 } diff --git a/doc/guide/hooks-radius.rst b/doc/guide/hooks-radius.rst index 59b6e65606..d2f20939fc 100644 --- a/doc/guide/hooks-radius.rst +++ b/doc/guide/hooks-radius.rst @@ -54,7 +54,7 @@ STEP 1: Install dependencies Several tools are needed to build the dependencies and Kea itself. The following commands should install them: -:: +.. code-block:: console $ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm $ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git @@ -74,7 +74,7 @@ until those are processed, it is strongly recommended to use the FreeRADIUS client with ISC's patches. To download and compile this version, please use the following steps: -:: +.. code-block:: console $ git clone https://github.com/fxdupont/freeradius-client.git $ cd freeradius-client/ @@ -100,7 +100,7 @@ compiled using the g++ 4.8 version in CentOS. To download and compile Boost 1.65, please use the following commands: -:: +.. code-block:: console $ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz $ tar zxvf boost_1_65_1.tar.gz @@ -116,30 +116,33 @@ compiled. STEP 4: Compile and install Kea Obtain the Kea sources either by downloading them from the git -repository or extracting the tarball: +repository or extracting the tarball. Use one of those commands +to obtain the Kea sources. -:: +Choice 1: get from github - # Use one of those commands to obtain the Kea sources: +.. code-block:: console - # Choice 1: get from github $ git clone https://github.com/isc-projects/kea - # Get a tarball and extract it - $ tar zxvf kea-KEAVERSION.tar.gz +Choice 2: get a tarball and extract it + +.. code-block:: console + + $ tar zxvf kea-|release|.tar.gz The next step is to extract the premium Kea package that contains the RADIUS repository into the Kea sources. After the tarball is extracted, the Kea sources should have a premium/ subdirectory. -:: +.. code-block:: console $ cd kea - $ tar zxvf ../kea-premium-radius-KEAVERSION.tar.gz + $ tar zxvf ../kea-premium-radius-|release|.tar.gz Once this is done, verify that the Kea sources look similar to this: -:: +.. code-block:: console $ ls -l total 952 @@ -168,7 +171,7 @@ is necessary to tell Kea where the FreeRADIUS client sources can be found. Also, since the non-standard Boost is used, the path to it must be specified. -:: +.. code-block:: console $ autoreconf -i $ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/to/boost --with-boost-lib-dir=/path/to/boost/state/lib @@ -178,11 +181,11 @@ directory (/usr/local) and the Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path should look as follows: -:: +.. code-block:: console - ./configure --with-freeradius=/usr/local \ - --with-boost-include=/home/thomson/devel/boost_1_65_1 \ - --with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib + $ ./configure --with-freeradius=/usr/local \ + --with-boost-include=/home/thomson/devel/boost_1_65_1 \ + --with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib After some checks, the configure script should print a report similar to the following: @@ -195,8 +198,8 @@ the following: Package: Name: kea - Version: KEAVERSION - Extended version: KEAVERSION (tarball) + Version: |release| + Extended version: |release| (tarball) OS Family: Linux Hooks directory: /usr/local/lib/kea/hooks @@ -280,7 +283,7 @@ Once the configuration is complete, compile Kea using make. If the system has more than one core, using the "-j N" option is recommended to speed up the build. -:: +.. code-block:: console $ make -j5 $ sudo make install @@ -298,25 +301,25 @@ takes many parameters. For example, this configuration could be used: "Dhcp4": { - // Your regular DHCPv4 configuration parameters here. + # Your regular DHCPv4 configuration parameters here. "hooks-libraries": [ { - // Note that RADIUS requires host-cache for proper operation, - // so that library is loaded as well. + # Note that RADIUS requires host-cache for proper operation, + # so that library is loaded as well. "library": "/usr/local/lib/kea/hooks/libdhcp_host_cache.so" }, { "library": "/usr/local/lib/kea/hooks/libdhc_radius.so", "parameters": { - // Specify where FreeRADIUS dictionary could be located + # Specify where FreeRADIUS dictionary could be located "dictionary": "/usr/local/etc/freeradius/dictionary", - // Specify which address to use to communicate with RADIUS servers + # Specify which address to use to communicate with RADIUS servers "bindaddr": "*", - // more RADIUS parameters here + # more RADIUS parameters here } } ] @@ -459,61 +462,61 @@ following snippet could be used: "parameters": { - // Other RADIUS parameters here + # Other RADIUS parameters here "access": { - // This starts the list of access servers + # This starts the list of access servers "servers": [ { - // These are parameters for the first (and only) access server + # These are parameters for the first (and only) access server "name": "127.0.0.1", "port": 1812, "secret": "xyz123" } - // Additional access servers could be specified here + # Additional access servers could be specified here ], - // This defines a list of additional attributes Kea will send to each - // access server in Access-Request. + # This defines a list of additional attributes Kea will send to each + # access server in Access-Request. "attributes": [ { - // This attribute is identified by name (must be present in the - // dictionary) and has static value (i.e. the same value will be - // sent to every server for every packet) + # This attribute is identified by name (must be present in the + # dictionary) and has static value (i.e. the same value will be + # sent to every server for every packet) "name": "Password", "data": "mysecretpassword" }, { - // It is also possible to specify an attribute using its type, - // rather than a name. 77 is Connect-Info. The value is specified - // using hex. Again, this is a static value. It will be sent the - // same for every packet and to every server. + # It is also possible to specify an attribute using its type, + # rather than a name. 77 is Connect-Info. The value is specified + # using hex. Again, this is a static value. It will be sent the + # same for every packet and to every server. "type": 77, "raw": "65666a6a71" }, { - // This example shows how an expression can be used to send dynamic - // value. The expression (see Section 13) may take any value from - // the incoming packet or even its metadata (e.g. the interface - // it was received over from) + # This example shows how an expression can be used to send dynamic + # value. The expression (see Section 13) may take any value from + # the incoming packet or even its metadata (e.g. the interface + # it was received over from) "name": "Configuration-Token", "expr": "hexstring(pkt4.mac,':')" } - ] // End of attributes - } // End of access + ] # End of attributes + } # End of access - // Accounting parameters. + # Accounting parameters. "accounting": { - // This starts the list of accounting servers + # This starts the list of accounting servers "servers": [ { - // These are parameters for the first (and only) accounting server + # These are parameters for the first (and only) accounting server "name": "127.0.0.1", "port": 1813, "secret": "sekret" } - // Additional accounting servers could be specified here + # Additional accounting servers could be specified here ] } diff --git a/doc/guide/hooks.rst b/doc/guide/hooks.rst index ed28efd97b..fee00b4601 100644 --- a/doc/guide/hooks.rst +++ b/doc/guide/hooks.rst @@ -65,32 +65,32 @@ For our users' convenience, the premium hooks installation procedure is describe 1. Download the package; detailed instructions are provided separately on how to get it. The package will be a file with a name similar to -kea-premium-KEAVERSION.tar.gz. (The name may vary depending on the package +kea-premium-|release|.tar.gz. (The name may vary depending on the package purchased.) 2. Administrators who still have the sources for the corresponding version of the open-source Kea package still on their system from the initial Kea installation should skip this step. Otherwise, extract the Kea source from the original -tarball that was downloaded. For example, with a download of Kea KEAVERSION., -there should be a tarball called kea-KEAVERSION.tar.gz on the system. +tarball that was downloaded. For example, with a download of Kea |release|., +there should be a tarball called kea-|release|.tar.gz on the system. Unpack this tarball: :: - $ tar zxvf kea-KEAVERSION.tar.gz + $ tar zxvf kea-|release|.tar.gz -This will unpack the tarball into the kea-KEAVERSION subdirectory of +This will unpack the tarball into the kea-|release| subdirectory of the current working directory. 3. Unpack the Kea premium tarball into the directory into which Kea was -unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION +unpacked. Once Kea |release| has been unpacked into a kea-|release| subdirectory and the Kea premium tarball is in the current directory, the following steps will unpack the premium tarball into the correct location: :: - $ cd kea-KEAVERSION - $ tar xvf ../kea-premium-KEAVERSION.tar.gz + $ cd kea-|release| + $ tar xvf ../kea-premium-|release|.tar.gz Note that unpacking the Kea premium package will put the files into a directory named "premium". Regardless of the name of the package, the @@ -114,13 +114,13 @@ first section of the output should look something like this: :: Package: - Name: kea - Version: KEAVERSION - Extended version:KEAVERSION (tarball) - OS Family: Linux - Using GNU sed: yes - Premium package: yes - Included Hooks: forensic_log flex_id host_cmds + Name: kea + Version: |release| + Extended version: |release| (tarball) + OS Family: Linux + Using GNU sed: yes + Premium package: yes + Included Hooks: forensic_log flex_id host_cmds The last line indicates which specific hooks were detected. Note that some hooks may require their own dedicated switches, e.g. the RADIUS hook @@ -285,50 +285,63 @@ loaded by the correct process per the table below. .. table:: List of Available Hooks Libraries - +-----------------+-----------------+-----------------+-----------------+ - | Name | Availability | Since | Load by process | - +=================+=================+=================+=================+ - | user_chk | Kea sources | Kea 0.8 | kea-dhcp4, | - | | | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Forensic | Support | Kea 1.1.0 | kea-dhcp4, | - | Logging | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Flexible | Support | Kea 1.2.0 | kea-dhcp4, | - | Identifier | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Host Commands | Support | Kea 1.2.0 | kea-dhcp4, | - | | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Subnet Commands | Support | Kea 1.3.0 | kea-dhcp4, | - | | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Lease Commands | Kea sources | Kea 1.3.0 | kea-dhcp4, | - | | | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | High | Kea sources | Kea 1.4.0 | kea-dhcp4, | - | Availability | | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, | - | Commands | | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | RADIUS | Support | Kea 1.4.0 | kea-dhcp4, | - | | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Host Cache | Support | Kea 1.4.0 | kea-dhcp4, | - | | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | Class Commands | Support | Kea 1.5.0 | kea-dhcp4, | - | | customers | | kea-dhcp6 | - +-----------------+-----------------+-----------------+-----------------+ - | MySQL | Kea sources | Kea 1.6.0 | kea-dhcp4, | - | Configuration | | | kea-dhcp6 | - | Backend | | | | - +-----------------+-----------------+-----------------+-----------------+ - | Configuration | Support | Kea 1.6.0 | kea-dhcp4, | - | Backend | customers | | kea-dhcp6 | - | Commands | | | | - +-----------------+-----------------+-----------------+-----------------+ + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Name | Availability | Since | Load by process | Description | + +=================+=================+=================+=================+======================================================+ + | user_chk | Kea sources | Kea 0.8 | kea-dhcp4, | Reads known users list from a file. Unknown users | + | | | | kea-dhcp6 | will be | + | | | | | assigned a lease | + | | | | | from the last subnet defined in the configuration | + | | | | | file, | + | | | | | e.g. to redirect | + | | | | | them a captive portal. This demonstrates how an | + | | | | | external | + | | | | | source of | + | | | | | information can be used to influence the Kea | + | | | | | allocation | + | | | | | engine. This hook | + | | | | | is part of the Kea source code and is available in | + | | | | | the | + | | | | | src/hooks/dhcp/user_chk directory. | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Forensic | Support | Kea 1.1.0 | kea-dhcp4, | | + | Logging | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Flexible | Support | Kea 1.2.0 | kea-dhcp4, | | + | Identifier | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Host Commands | Support | Kea 1.2.0 | kea-dhcp4, | | + | | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Subnet Commands | Support | Kea 1.3.0 | kea-dhcp4, | | + | | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Lease Commands | Kea sources | Kea 1.3.0 | kea-dhcp4, | | + | | | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | High | Kea sources | Kea 1.4.0 | kea-dhcp4, | | + | Availability | | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Statistics | Kea sources | Kea 1.4.0 | kea-dhcp4, | | + | Commands | | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | RADIUS | Support | Kea 1.4.0 | kea-dhcp4, | | + | | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Host Cache | Support | Kea 1.4.0 | kea-dhcp4, | | + | | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Class Commands | Support | Kea 1.5.0 | kea-dhcp4, | | + | | customers | | kea-dhcp6 | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | MySQL | Kea sources | Kea 1.6.0 | kea-dhcp4, | | + | Configuration | | | kea-dhcp6 | | + | Backend | | | | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ + | Configuration | Support | Kea 1.6.0 | kea-dhcp4, | | + | Backend | customers | | kea-dhcp6 | | + | Commands | | | | | + +-----------------+-----------------+-----------------+-----------------+------------------------------------------------------+ ISC hopes to see more hooks libraries become available as time progresses, developed both internally and externally. Since this list @@ -902,13 +915,13 @@ can be achieved by using the following configuration: :: "Dhcp6": { - "subnet6": [{ ..., // subnet definition starts here + "subnet6": [{ ..., # subnet definition starts here "reservations": [ - "flex-id": "'port1234'", // value of the first 8 bytes of the interface-id + "flex-id": "'port1234'", # value of the first 8 bytes of the interface-id "ip-addresses": [ "2001:db8::1" ] ], - }], // end of subnet definitions - "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers + }], # end of subnet definitions + "host-reservation-identifiers": ["duid", "flex-id"], # add "flex-id" to reservation identifiers "hooks-libraries": [ { "library": "/path/libdhcp_flex_id.so", @@ -941,13 +954,13 @@ for non-printable characters and do not require the use of the :: "Dhcp6": { - "subnet6": [{ ..., // subnet definition starts here + "subnet6": [{ ..., # subnet definition starts here "reservations": [ - "flex-id": "01:02:03:04:05:06", // value of the first 8 bytes of the interface-id + "flex-id": "01:02:03:04:05:06", # value of the first 8 bytes of the interface-id "ip-addresses": [ "2001:db8::1" ] ], - }], // end of subnet definitions - "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers + }], # end of subnet definitions + "host-reservation-identifiers": ["duid", "flex-id"], # add "flex-id" to reservation identifiers "hooks-libraries": [ { "library": "/path/libdhcp_flex_id.so", @@ -2246,12 +2259,12 @@ An example response could look as follows: { "subnet": "192.0.2.0/24", "id": 5, - // many other subnet-specific details here + # many other subnet-specific details here }, { "id": 6, "subnet": "192.0.3.0/31", - // many other subnet-specific details here + # many other subnet-specific details here } ], "valid-lifetime": 120 diff --git a/doc/guide/install.rst b/doc/guide/install.rst index 2555aedc70..11e38491eb 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -152,7 +152,7 @@ development is done in the “master” branch. The code can be checked out from ``https://gitlab.isc.org/isc-projects/kea.git``: -:: +.. code-block:: console $ git clone https://gitlab.isc.org/isc-projects/kea.git @@ -179,7 +179,7 @@ Configure Before the Build Kea uses the GNU Build System to discover build environment details. To generate the makefiles using the defaults, simply run: -:: +.. code-block:: console $ ./configure @@ -254,7 +254,7 @@ developers, or people who want to extend Kea code or send patches: Internet anyway, please set the XSLTPROC_NET environment variable in configure to any non-empty value, e.g. - :: + .. code-block:: console $ ./configure XSLTPROC_NET=yes --enable-generate-docs @@ -287,7 +287,7 @@ For example, the following command configures Kea to find the Boost headers in /usr/pkg/include, specifies that PostgreSQL support should be enabled, and sets the installation location to /opt/kea: -:: +.. code-block:: console $ ./configure \ --with-boost-include=/usr/pkg/include \ @@ -298,7 +298,7 @@ If you have any problems with building Kea using the header-only Boost code, or you'd like to use the Boost system library (assumed for the sake of this example to be located in /usr/pkg/lib): -:: +.. code-block:: console $ ./configure \ --with-boost-libs=-lboost_system \ @@ -316,7 +316,7 @@ Build After the configure step is complete, build the executables from the C++ code and prepare the Python scripts by running the command: -:: +.. code-block:: console $ make @@ -326,7 +326,7 @@ Install To install the Kea executables, support files, and documentation, issue the command: -:: +.. code-block:: console $ make install @@ -342,7 +342,7 @@ If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with prefix/lib if configured with --prefix) in ``/etc/ld.so.conf`` (or the relevant linker cache configuration file for your OS): -:: +.. code-block:: console $ ldconfig @@ -355,8 +355,8 @@ relevant linker cache configuration file for your OS): :: - program: error while loading shared libraries: libkea-something.so.1: - cannot open shared object file: No such file or directory + program: error while loading shared libraries: libkea-something.so.1: + cannot open shared object file: No such file or directory .. _dhcp-install-configure: @@ -393,17 +393,17 @@ with the following modification. To enable the MySQL database code, at the "configure" step (see :ref:`configure`), the --with-mysql switch should be specified: -:: +.. code-block:: console - ./configure [other-options] --with-mysql + $ ./configure [other-options] --with-mysql If MySQL was not installed in the default location, the location of the MySQL configuration program "mysql_config" should be included with the switch, i.e. -:: +.. code-block:: console - ./configure [other-options] --with-mysql=path-to-mysql_config + $ ./configure [other-options] --with-mysql=path-to-mysql_config See :ref:`mysql-database-create` for details regarding MySQL database configuration. @@ -419,17 +419,17 @@ Build and install Kea as described in :ref:`installation`, with the following modification. To enable the PostgreSQL database code, at the "configure" step (see :ref:`configure`), the --with-pgsql switch should be specified: -:: +.. code-block:: console - ./configure [other-options] --with-pgsql + $ ./configure [other-options] --with-pgsql If PostgreSQL was not installed in the default location, the location of the PostgreSQL configuration program "pg_config" should be included with the switch, i.e. -:: +.. code-block:: console - ./configure [other-options] --with-pgsql=path-to-pg_config + $ ./configure [other-options] --with-pgsql=path-to-pg_config See :ref:`pgsql-database-create` for details regarding PostgreSQL database configuration. @@ -446,9 +446,9 @@ simply install or build and install the package. Then build and install Kea as described in :ref:`installation`. To enable the Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter: -:: +.. code-block:: console - ./configure [other-options] --with-cql=path-to-pkg-config + $ ./configure [other-options] --with-cql=path-to-pkg-config Note if ``pkg-config`` is at its standard location (and thus in the shell path) you do not need to supply its path. If it does not work @@ -461,7 +461,7 @@ dependencies for building cpp-driver, see the project homepage https://github.com/datastax/cpp-driver. In June 2016, the following commands were used: -:: +.. code-block:: console $ git clone https://github.com/datastax/cpp-driver $ cd cpp-driver @@ -486,9 +486,9 @@ Build and install Kea as described in :ref:`installation`, with the following modification. To enable the Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter: -:: +.. code-block:: console - ./configure [other-options] --with-cql=path-to-cql_config + $ ./configure [other-options] --with-cql=path-to-cql_config diff --git a/doc/guide/intro.rst b/doc/guide/intro.rst index 54af333c15..5918ca86c3 100644 --- a/doc/guide/intro.rst +++ b/doc/guide/intro.rst @@ -8,14 +8,14 @@ Kea is the next generation of DHCP software developed by ISC. It supports both DHCPv4 and DHCPv6 protocols along with their extensions, e.g. prefix delegation and dynamic updates to DNS. -This guide covers Kea version KEAVERSION. +This guide covers Kea version |release|. Supported Platforms =================== Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and FreeBSD systems. It is also likely to work on many other platforms. -Kea-KEAVERSION builds have been tested on: +Kea-|release| builds have been tested on: - CentOS Linux — 7.1804 (aka 7.5) - Fedora — 28, 29 diff --git a/doc/guide/kea-guide.rst b/doc/guide/kea-guide.rst index 39f68def88..9a3ad2cfc5 100644 --- a/doc/guide/kea-guide.rst +++ b/doc/guide/kea-guide.rst @@ -6,7 +6,7 @@ Kea is an open source implementation of the Dynamic Host Configuration Protocol (DHCP) servers, developed and maintained by Internet Systems Consortium (ISC). -This is the reference guide for Kea version &keaversion;. +This is the reference guide for Kea version |release|. Links to the most up-to-date version of this document (in PDF, HTML, and plain text formats), along with other documents for Kea, can be found in ISC's `Knowledgebase `_. @@ -47,11 +47,11 @@ Kea is an open source project designed, developed, and maintained by Internet Systems Consortium, Inc, a 501(c)3 non-profit organization. ISC is primarily funded by revenues from support subscriptions for our open source, and we encourage all professional users to consider this option. -To learn more, see ​\ https://www.isc.org/support/. +To learn more, see \ https://www.isc.org/support/. If you would like to contribute to ISC to assist us in continuing to make quality open source software, please visit our donations page at -​\ https://www.isc.org/donate/. +\ https://www.isc.org/donate/. We thank all the organizations and individuals who have helped to make Kea possible. `Comcast `__ and the Comcast diff --git a/doc/guide/keactrl.rst b/doc/guide/keactrl.rst index c9f1e1f959..e7a306bf77 100644 --- a/doc/guide/keactrl.rst +++ b/doc/guide/keactrl.rst @@ -22,9 +22,9 @@ Command Line Options ``keactrl`` is run as follows: -:: +.. code-block:: console - keactrl [-c keactrl-config-file] [-s server[,server,...]] + # keactrl [-c keactrl-config-file] [-s server[,server,...]] ```` is one of the commands described in `Commands <#keactrl-commands>`__. @@ -53,7 +53,7 @@ on a per-command basis using the ``-c`` switch. The contents of ``keactrl.conf`` are: -:: +.. code-block:: bash # This is a configuration file for keactrl script which controls # the startup, shutdown, reconfiguration and gathering the status @@ -155,7 +155,7 @@ The following commands are supported by ``keactrl``: Typical output from ``keactrl`` when starting the servers looks similar to the following: -:: +.. code-block:: console $ keactrl start INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d @@ -169,7 +169,7 @@ keactrl to determine whether a given server is running. If one or more servers are running when the start command is issued, the output will look similar to the following: -:: +.. code-block:: console $ keactrl start INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid. @@ -188,7 +188,7 @@ must be manually deleted. The following command stops all servers: -:: +.. code-block:: console $ keactrl stop INFO/keactrl: Stopping kea-dhcp4... @@ -202,7 +202,7 @@ regardless of whether they are "enabled" in ``keactrl.conf``. If any of the servers are not running, an informational message is displayed as in the ``stop`` command output below. -:: +.. code-block:: console $ keactrl stop INFO/keactrl: kea-dhcp4 isn't running. @@ -218,7 +218,7 @@ file and that are currently running. When a server receives the SIGHUP signal it re-reads its configuration file and, if the new configuration is valid, uses the new configuration. A reload is executed as follows: -:: +.. code-block:: console $ keactrl reload INFO/keactrl: Reloading kea-dhcp4... @@ -232,7 +232,7 @@ version 1.5.0, kea-netconf does not support the SIGHUP signal. If its configuration has changed, please stop and restart it for the change to take effect. This limitation will be removed in a future release. -:: +.. code-block:: console $ keactrl stop INFO/keactrl: kea-dhcp4 isn't running. @@ -262,7 +262,7 @@ take effect. This limitation will be removed in a future release. Sometimes it is useful to check which servers are running. The ``status`` command reports this, with typical output that looks like: -:: +.. code-block:: console $ keactrl status DHCPv4 server: active @@ -288,14 +288,14 @@ the ``keactrl`` command is issued. For example, the following instructs ``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running: -:: +.. code-block:: console $ keactrl stop -s dhcp4,dhcp6 Similarly, the following will start only the ``kea-dhcp4`` and ``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``. -:: +.. code-block:: console $ keactrl start -s dhcp4,dhcp_ddns diff --git a/doc/guide/netconf.rst b/doc/guide/netconf.rst index 4f1f5b6e34..3b71ef1390 100644 --- a/doc/guide/netconf.rst +++ b/doc/guide/netconf.rst @@ -69,7 +69,7 @@ named in Kea models (a short version of schema models). To list the currently installed YANG modules: -:: +.. code-block:: console $ sysrepoctl -l @@ -105,12 +105,12 @@ after installation. To install modules from sources, do the following: -:: +.. code-block:: console - cd src/share/yang/modules - sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang - sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang - sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang + $ cd src/share/yang/modules + $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang + $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp4-server*.yang + $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g kea-dhcp6-server*.yang ... Note that the first -s parameter specifies the location of the YANG @@ -120,7 +120,7 @@ by the Kea configuration under the SYSREPO_REPO name. The installation should look similar to the following: -:: +.. code-block:: console $ sudo sysrepoctl -i -s /home/thomson/devel/sysrepo-0.7.6/build/repository/yang -s . -g ietf-dhcpv6-server*.yang Installing a new module from file 'ietf-dhcpv6-server@2018-11-20.yang'... @@ -148,7 +148,7 @@ The installation should look similar to the following: It is possible to confirm whether the models are imported correctly by using sysrepoctl -l: -:: +.. code-block:: console $ sysrepoctl -l Sysrepo schema directory: /home/thomson/devel/sysrepo-0.7.6/build/repository/yang/ @@ -175,7 +175,7 @@ sysrepoctl -l: To install a new revision of a module it must first be uninstalled, e.g. by: -:: +.. code-block:: console sudo sysrepoctl -u -m kea-dhcp4-server @@ -384,31 +384,31 @@ Kea sources. :: - // This is a simple example of a configuration for the NETCONF agent. - // This server provides a YANG interface for all Kea servers and the agent. + # This is a simple example of a configuration for the NETCONF agent. + # This server provides a YANG interface for all Kea servers and the agent. { "Netconf": { - // Control flags can be defined in the global scope or - // in a managed server scope. Precedences are: - // - use the default value (true) - // - use the global value - // - use the local value. - // So this overwrites the default value: + # Control flags can be defined in the global scope or + # in a managed server scope. Precedences are: + # - use the default value (true) + # - use the global value + # - use the local value. + # So this overwrites the default value: "boot-update": false, - // This map specifies how each server is managed. For each server there - // is a name of the YANG model to be used and the control channel. + # This map specifies how each server is managed. For each server there + # is a name of the YANG model to be used and the control channel. // - // Currently three control channel types are supported: - // "stdout" which outputs the configuration on the standard output, - // "unix" which uses the local control channel supported by the - // "dhcp4" and "dhcp6" servers ("d2" support is not yet available), - // and "http" which uses the Control Agent "ca" to manage itself or - // to forward commands to "dhcp4" or "dhcp6". + # Currently three control channel types are supported: + # "stdout" which outputs the configuration on the standard output, + # "unix" which uses the local control channel supported by the + # "dhcp4" and "dhcp6" servers ("d2" support is not yet available), + # and "http" which uses the Control Agent "ca" to manage itself or + # to forward commands to "dhcp4" or "dhcp6". "managed-servers": { - // This is how kea-netconf can communicate with the DHCPv4 server. + # This is how kea-netconf can communicate with the DHCPv4 server. "dhcp4": { "comment": "DHCP4 server", @@ -420,7 +420,7 @@ Kea sources. } }, - // DHCPv6 parameters. + # DHCPv6 parameters. "dhcp6": { "model": "kea-dhcp6-server", @@ -431,8 +431,8 @@ Kea sources. } }, - // Currently the DHCP-DDNS (nicknamed D2) server does not support - // a command channel. + # Currently the DHCP-DDNS (nicknamed D2) server does not support + # a command channel. "d2": { "model": "kea-dhcp-ddns", @@ -443,7 +443,7 @@ Kea sources. } }, - // Of course the Control Agent (CA) supports HTTP. + # Of course the Control Agent (CA) supports HTTP. "ca": { "model": "kea-ctrl-agent", @@ -455,39 +455,39 @@ Kea sources. } }, - // kea-netconf is able to load hooks libraries that augment its operation. - // Currently there are no hook points defined in kea-netconf - // processing. + # kea-netconf is able to load hooks libraries that augment its operation. + # Currently there are no hook points defined in kea-netconf + # processing. "hooks-libraries": [ - // The hooks libraries list may contain more than one library. + # The hooks libraries list may contain more than one library. { - // The only necessary parameter is the library filename. + # The only necessary parameter is the library filename. "library": "/opt/local/netconf-commands.so", - // Some libraries may support parameters. Make sure you - // type this section carefully, as kea-netconf does not - // validate it (because the format is library-specific). + # Some libraries may support parameters. Make sure you + # type this section carefully, as kea-netconf does not + # validate it (because the format is library-specific). "parameters": { "param1": "foo" } } ], - // Similar to other Kea components, NETCONF also uses logging. + # Similar to other Kea components, NETCONF also uses logging. "loggers": [ { "name": "kea-netconf", "output_options": [ { "output": "/var/log/kea-netconf.log", - // Several additional parameters are possible in - // addition to the typical output. - // Flush determines whether logger flushes output - // to a file. - // Maxsize determines maximum filesize before - // the file is being rotated. - // Maxver specifies the maximum number of - // rotated files being kept. + # Several additional parameters are possible in + # addition to the typical output. + # Flush determines whether logger flushes output + # to a file. + # Maxsize determines maximum filesize before + # the file is being rotated. + # Maxver specifies the maximum number of + # rotated files being kept. "flush": true, "maxsize": 204800, "maxver": 4 @@ -553,7 +553,7 @@ The test box has an Ethernet interface named eth1. On some systems it is possible to rename interfaces, for instance on a Linux with an ens38 interface: -:: +.. code-block:: console # ip link set down dev ens38 # ip link set name eth1 dev ens38 @@ -561,7 +561,7 @@ interface: The interface must have an address in the test prefix: -:: +.. code-block:: console # ip -6 addr add 2001:db8::1/64 dev eth1 @@ -586,14 +586,14 @@ DHCPv6 server: In order to launch the Kea DHCPv6 server using the configuration contained within the ``boot.json`` file, run: -:: +.. code-block:: console # kea-dhcp6 -d -c boot.json The current configuration of the server can be fetched via control socket by running: -:: +.. code-block:: console # echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea6-sock '-,ignoreeof' @@ -638,7 +638,7 @@ Note that in production there should not be a need to log at the DEBUG level. The Kea NETCONF agent is launched by: -:: +.. code-block:: console # kea-netconf -d -c netconf.json @@ -646,7 +646,7 @@ Now that both ``kea-netconf`` and ``kea-dhcp6`` are running, it is possible to populate updates to the configuration to the DHCPv6 server. The following is the configuration extracted from ``startup.xml``: -:: +.. code-block:: xml @@ -669,7 +669,7 @@ The following is the configuration extracted from ``startup.xml``: To populate this new configuration: -:: +.. code-block:: console # sysrepocfg -d startup -f xml -i startup.xml kea-dhcp6-server @@ -704,7 +704,7 @@ NETCONF: In the first case, consider the following ``BAD-schema.xml`` configuration file: -:: +.. code-block:: xml @@ -727,14 +727,14 @@ configuration file: It is directly rejected by ``sysrepocfg``: -:: +.. code-block:: console # sysrepocfg -d running -f xml -i BAD-schema.xml kea-dhcp6-server In the second case, the configuration is rejected by ``kea-netconf``. For example, consider this ``BAD-translator.xml`` file: -:: +.. code-block:: xml @@ -759,7 +759,7 @@ For example, consider this ``BAD-translator.xml`` file: In the third case, the configuration is presented to the Kea DHCPv6 server and fails to validate as in this ``BAD-config.xml`` file: -:: +.. code-block:: xml @@ -793,7 +793,7 @@ NETCONF Operation Example with Two Pools This example adds a second pool to the initial (i.e. startup) configuration in the ``twopools.xml`` file: -:: +.. code-block:: xml @@ -821,7 +821,7 @@ configuration in the ``twopools.xml`` file: This configuration is installed by: -:: +.. code-block:: console # sysrepocfg -d running -f xml -i twopools.xml kea-dhcp6-server @@ -832,7 +832,7 @@ NETCONF Operation Example with Two Subnets This example specifies two subnets in the ``twosubnets.xml`` file: -:: +.. code-block:: xml @@ -864,7 +864,7 @@ This example specifies two subnets in the ``twosubnets.xml`` file: This configuration is installed by: -:: +.. code-block:: console # sysrepocfg -d running -f xml -i twosubnets.xml kea-dhcp6-server @@ -876,7 +876,7 @@ NETCONF Operation Example with Logging This example adds a logger entry to the initial (i.e. startup) configuration in the ``logging.xml`` file: -:: +.. code-block:: xml @@ -947,7 +947,7 @@ The corresponding Kea configuration in JSON is: Finally, any of the previous examples can be replayed using ``sysrepocfg`` in edit mode as follows: -:: +.. code-block:: console # sysrepocfg -d running -f xml -e vi kea-dhcp6-server diff --git a/doc/guide/quickstart.rst b/doc/guide/quickstart.rst index 447ad47850..336509938a 100644 --- a/doc/guide/quickstart.rst +++ b/doc/guide/quickstart.rst @@ -22,27 +22,27 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services 3. Extract the tarball. For example: - :: + .. code-block:: console - $ tar xvzf kea-KEAVERSION.tar.gz + $ tar xvzf kea-|release|.tar.gz 4. Go into the source directory and run the configure script: - :: + .. code-block:: console - $ cd kea-KEAVERSION + $ cd kea-|release| $ ./configure [your extra parameters] 5. Build it: - :: + .. code-block:: console $ make 6. Install it (by default it will be placed in ``/usr/local/``, so it is likely that you will need root privileges for this step): - :: + .. code-block:: console # make install @@ -55,25 +55,25 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services 8. In order to start the DHCPv4 server in the background, run the following command (as root): - :: + .. code-block:: console # keactrl start -s dhcp4 Or run the following command to start the DHCPv6 server instead: - :: + .. code-block:: console # keactrl start -s dhcp6 Note that it is also possible to start all servers simultaneously: - :: + .. code-block:: console - $ keactrl start + # keactrl start 9. Verify that the Kea server(s) is/are running: - :: + .. code-block:: console # keactrl status @@ -92,7 +92,7 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services 11. Stop running the server(s): - :: + .. code-block:: console # keactrl stop @@ -112,12 +112,12 @@ Running the Kea Servers Directly The Kea servers can be started directly, without the need to use ``keactrl``. To start the DHCPv4 server run the following command: -:: +.. code-block:: console # kea-dhcp4 -c /path/to/your/kea4/config/file.json Similarly, to start the DHCPv6 server run the following command: -:: +.. code-block:: console # kea-dhcp6 -c /path/to/your/kea6/config/file.json diff --git a/doc/guide/shell.rst b/doc/guide/shell.rst index b44ab8ae16..821bdc23d2 100644 --- a/doc/guide/shell.rst +++ b/doc/guide/shell.rst @@ -27,9 +27,9 @@ Shell Usage ``kea-shell`` is run as follows: -:: +.. code-block:: console - kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command] + $ kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command] where: @@ -71,7 +71,7 @@ all supported commands from the CA, use the ``list-commands`` command. The following shows a simple example of usage: -:: +.. code-block:: console $ kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands ^D @@ -89,7 +89,7 @@ the command "config-write" to the CA (the ``--service`` parameter has not been used), along with the parameters specified in param.json. The result will be stored in result.json. -:: +.. code-block:: console $ cat param.json "filename": "my-config-file.json" @@ -100,7 +100,7 @@ servers, the default empty path in the URL is not enough, so the ``--path`` parameter should be used. For instance, if requests to the "/kea" path are forwarded to the CA this can be used: -:: +.. code-block:: console $ kea-shell --host 192.0.2.1 --port 8001 --path kea ...