initial conversion of kea guide from docbook to rst/sphinx

doc/guide/.gitignore

@@ -4,3 +4,4 @@
 /kea-messages.xml
 /kea-guide.pdf
 /kea-messages.pdf
+/_build
\ No newline at end of file

doc/guide/Makefile.am

-# generated documentation
-HTMLDOCS = kea-guide.html kea-messages.html
-DOCS = kea-guide.txt
 
-dist_doc_DATA = $(DOCS)
-dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
-
-DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
-DOCBOOK += config-backend.xml keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml
-DOCBOOK += logging.xml ddns.xml hooks.xml hooks-class-cmds.xml hooks-cb-cmds.xml
-DOCBOOK += hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml hooks-radius.xml
-DOCBOOK += hooks-stat-cmds.xml lfc.xml stats.xml ctrl-channel.xml classify.xml shell.xml
-DOCBOOK += agent.xml netconf.xml api.xml congestion-handling.xml hammer.xml
-
-EXTRA_DIST = $(DOCBOOK) kea-docbook.xsl
-
-DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
-
-kea-messages.xml:
-	$(top_builddir)/tools/system_messages -o $@ \
-	`find $(top_srcdir) -name "*.mes" -print`
-
-# This is not a "man" manual, but reuse this for now for docbook.
-if GENERATE_DOCS
-
-kea-guide.html: $(DOCBOOK)
-	@XSLTPROC@ --novalid --xinclude @NONET@ \
-		--path $(top_builddir)/doc \
-		-o $@ \
-		--stringparam section.autolabel 1 \
-		--stringparam section.label.includes.component.label 1 \
-		--stringparam html.stylesheet kea-guide.css \
-		$(srcdir)/kea-docbook.xsl \
-		$(srcdir)/kea-guide.xml
-
-kea-guide.txt: kea-guide.html
-	@ELINKS@ -dump -no-numbering -no-references kea-guide.html > $@
-
-kea-messages.html: kea-messages.xml
-	@XSLTPROC@ --novalid --xinclude @NONET@ \
-		--path $(top_builddir)/doc \
-		-o $@ \
-		--stringparam generate.toc "book toc" \
-		--stringparam html.stylesheet kea-guide.css \
-		$(srcdir)/kea-docbook.xsl \
-		kea-messages.xml
-
-else
-
-$(HTMLDOCS) $(DOCS):
-	@echo Doc generation disabled.  Creating dummy $@.  Configure with --enable-generate-docs to enable it.
-	@echo Doc generation disabled.  Remove this file, configure with --enable-generate-docs, and rebuild Kea > $@
-
-endif
-
-if HAVE_DBLATEX
-
-CLEANFILES = kea-guide.pdf kea-messages.pdf
-
-DBLATEX_FLAGS = --xslt-opts=--path --xslt-opts=$(abs_top_builddir)/doc \
-	-P doc.collab.show=0 -P latex.output.revhistory=0 \
-	-P term.breakline=1 -P filename.as.url=0 \
-	-P imagedata.default.scale="maxwidth=50px,maxheight=35px"
-
-pdf: kea-guide.pdf kea-messages.pdf
-
-kea-guide.pdf: $(DOCBOOK)
-	@DBLATEX@ $(DBLATEX_FLAGS) kea-guide.xml
-
-kea-messages.pdf: kea-messages.xml
-	@DBLATEX@ $(DBLATEX_FLAGS) kea-messages.xml
-
-else
-
-pdf kea-guide.pdf kea-messages.pdf:
-	@echo Install dblatex tool and rerun ./configure to be able to generate documentation in PDF format.
-
-endif
+rst_sources=admin.rst
+rst_sources+=agent.rst
+rst_sources+=api.rst
+rst_sources+=classify.rst
+rst_sources+=config-backend.rst
+rst_sources+=config.rst
+rst_sources+=congestion-handling.rst
+rst_sources+=ctrl-channel.rst
+rst_sources+=ddns.rst
+rst_sources+=dhcp4-srv.rst
+rst_sources+=dhcp6-srv.rst
+rst_sources+=hammer.rst
+rst_sources+=hooks-cb-cmds.rst
+rst_sources+=hooks-class-cmds.rst
+rst_sources+=hooks-ha.rst
+rst_sources+=hooks-host-cache.rst
+rst_sources+=hooks-lease-cmds.rst
+rst_sources+=hooks-radius.rst
+rst_sources+=hooks.rst
+rst_sources+=hooks-stat-cmds.rst
+rst_sources+=install.rst
+rst_sources+=intro.rst
+rst_sources+=keactrl.rst
+rst_sources+=kea-guide.rst
+rst_sources+=lease-expiration.rst
+rst_sources+=lfc.rst
+rst_sources+=logging.rst
+rst_sources+=netconf.rst
+rst_sources+=quickstart.rst
+rst_sources+=shell.rst
+rst_sources+=stats.rst
+
+
+sphinxbuild = sphinx-build
+sphinxopts = -E
+
+kea-guide.pdf: $(rst_sources)
+	@$(sphinxbuild) -M latexpdf $(srcdir) $(builddir)/_build $(sphinxopts)
+
+kea-guide.html: $(rst_sources)
+	@$(sphinxbuild) -M singlehtml $(srcdir) $(builddir)/_build $(sphinxopts)
+
+
+EXTRA_DIST = $(rst_sources)
+
+# TODO: here should ba added some stuff for DIST, etc to be consumed by automake/autoconf

doc/guide/agent.rst

+.. _kea-ctrl-agent:
+
+*********************
+The Kea Control Agent
+*********************
+
+.. _agent-overview:
+
+Overview
+========
+
+The Kea Control Agent (CA) is a daemon which exposes a RESTful control
+interface for managing Kea servers. The daemon can receive control
+commands over HTTP and either forward these commands to the respective
+Kea servers or handle these commands on its own. The determination
+whether the command should be handled by the CA or forwarded is made by
+checking the value of the "service" parameter, which may be included in
+the command from the controlling client. The details of the supported
+commands, as well as their structures, are provided in
+`??? <#ctrl-channel>`__.
+
+The CA can use hook libraries to provide support for additional commands
+or custom behavior of existing commands. Such hook libraries must
+implement callouts for the "control_command_receive" hook point. Details
+about creating new hook libraries and supported hook points can be found
+in the `Kea Developer's
+Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__.
+
+The CA processes received commands according to the following algorithm:
+
+-  Pass command into any installed hooks (regardless of service
+   value(s)). If the command is handled by a hook, return the response.
+
+-  If the service specifies one more or services, forward the command to
+   the specified services and return the accumulated responses.
+
+-  If the service is not specified or is an empty list, handle the
+   command if the CA supports it.
+
+.. _agent-configuration:
+
+Configuration
+=============
+
+The following example demonstrates the basic CA configuration.
+
+::
+
+   {
+       "Control-agent": {
+           "http-host": "10.20.30.40",
+           "http-port": 8080,
+
+           "control-sockets": {
+               "dhcp4": {
+                   "comment": "main server",
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-v4"
+               },
+               "dhcp6": {
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-v6",
+                   "user-context": { "version": 3 }
+               },
+               "d2": {
+                   "socket-type": "unix",
+                   "socket-name": "/path/to/the/unix/socket-d2"
+               },
+           },
+
+           "hooks-libraries": [
+           {
+               "library": "/opt/local/control-agent-commands.so",
+               "parameters": {
+                   "param1": "foo"
+               }
+           } ],
+
+           "loggers": [ {
+               "name": "kea-ctrl-agent",
+               "severity": "INFO"
+           } ]
+       }
+   }
+
+The ``http-host`` and ``http-port`` parameters specify an IP address and
+port to which HTTP service will be bound. In the example configuration
+provided above, the RESTful service will be available under the URL of
+``http://10.20.30.40:8080/``. If these parameters are not specified, the
+default URL is http://127.0.0.1:8000/
+
+As mentioned in `Overview <#agent-overview>`__, the CA can forward
+received commands to the Kea servers for processing. For example,
+``config-get`` is sent to retrieve the configuration of one of the Kea
+services. When the CA receives this command, including a ``service``
+parameter indicating that the client desires to retrieve the
+configuration of the DHCPv4 server, the CA forwards this command to that
+server and passes the received response back to the client. More about
+the ``service`` parameter and the general structure of commands can be
+found in `??? <#ctrl-channel>`__.
+
+The CA uses UNIX domain sockets to forward control commands and receive
+responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2``
+maps specify the files to which UNIX domain sockets are bound. In the
+configuration above, the CA will connect to the DHCPv4 server via
+``/path/to/the/unix/socket-v4`` to forward the commands to it.
+Obviously, the DHCPv4 server must be configured to listen to connections
+via this same socket. In other words, the command socket configuration
+for the DHCPv4 server and the CA (for this server) must match. Consult
+`??? <#dhcp4-ctrl-channel>`__, `??? <#dhcp6-ctrl-channel>`__ and
+`??? <#d2-ctrl-channel>`__ to learn how the socket configuration is
+specified for the DHCPv4, DHCPv6 and D2 services.
+
+   **Warning**
+
+   "dhcp4-server", "dhcp6-server" and "d2-server" were renamed to
+   "dhcp4", "dhcp6" and "d2" respectively in Kea 1.2. If you are
+   migrating from Kea 1.2, you must modify your CA configuration to use
+   this new naming convention.
+
+User contexts can store arbitrary data as long as they are in valid JSON
+syntax and their top-level element is a map (i.e. the data must be
+enclosed in curly brackets). Some hook libraries may expect specific
+formatting; please consult the relevant hook library documentation for
+details.
+
+User contexts can be specified on either global scope, control socket,
+or loggers. One other useful feature is the ability to store comments or
+descriptions; the parser translates a "comment" entry into a user
+context with the entry, which allows a comment to be attached within the
+configuration itself.
+
+Hooks libraries can be loaded by the Control Agent in the same way as
+they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
+supports one hook point - 'control_command_receive' - which makes it
+possible to delegate processing of some commands to the hooks library.
+The ``hooks-libraries`` list contains the list of hooks libraries that
+should be loaded by the CA, along with their configuration information
+specified with ``parameters``.
+
+Please consult `??? <#logging>`__ for the details how to configure
+logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in
+the example above.
+
+.. _agent-secure-connection:
+
+Secure Connections
+==================
+
+The Control Agent does not natively support secure HTTP connections like
+SSL or TLS. In order to setup a secure connection, please use one of the
+available third-party HTTP servers and configure it to run as a reverse
+proxy to the Control Agent. Kea has been tested with two major HTTP
+server implentations working as a reverse proxy: Apache2 and nginx.
+Example configurations, including extensive comments, are provided in
+the ``doc/examples/https/`` directory.
+
+The reverse proxy forwards HTTP requests received over a secure
+connection to the Control Agent using unsecured HTTP. Typically, the
+reverse proxy and the Control Agent are running on the same machine, but
+it is possible to configure them to run on separate machines as well. In
+this case, security depends on the protection of the communications
+between the reverse proxy and the Control Agent.
+
+Apart from providing the encryption layer for the control channel, a
+reverse proxy server is also often used for authentication of the
+controlling clients. In this case, the client must present a valid
+certificate when it connects via reverse proxy. The proxy server
+authenticates the client by checking whether the presented certificate
+is signed by the certificate authority used by the server.
+
+To illustrate this, the following is a sample configuration for the
+nginx server running as a reverse proxy to the Kea Control Agent. The
+server enables authentication of the clients using certificates.
+
+::
+
+   #   The server certificate and key can be generated as follows:
+   #
+   #   openssl genrsa -des3 -out kea-proxy.key 4096
+   #   openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt
+   #
+   #   The CA certificate and key can be generated as follows:
+   #
+   #   openssl genrsa -des3 -out ca.key 4096
+   #   openssl req -new -x509 -days 365 -key ca.key -out ca.crt
+   #
+   #
+   #   The client certificate needs to be generated and signed:
+   #
+   #   openssl genrsa -des3 -out kea-client.key 4096
+   #   openssl req -new -key kea-client.key -out kea-client.csr
+   #   openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
+   #           -CAkey ca.key -set_serial 01 -out kea-client.crt
+   #
+   #   Note that the 'common name' value used when generating the client
+   #   and the server certificates must differ from the value used
+   #   for the CA certificate.
+   #
+   #   The client certificate must be deployed on the client system.
+   #   In order to test the proxy configuration with 'curl' run
+   #   command similar to the following:
+   #
+   #   curl -k --key kea-client.key --cert kea-client.crt -X POST \
+   #        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
+   #         https://kea.example.org/kea
+   #
+   #
+   #
+   #   nginx configuration starts here.
+
+   events {
+   }
+
+   http {
+           #   HTTPS server
+       server {
+           #     Use default HTTPS port.
+           listen 443 ssl;
+           #     Set server name.
+           server_name kea.example.org;
+
+           #   Server certificate and key.
+           ssl_certificate /path/to/kea-proxy.crt;
+           ssl_certificate_key /path/to/kea-proxy.key;
+
+           #   Certificate Authority. Client certificate must be signed by the CA.
+           ssl_client_certificate /path/to/ca.crt;
+
+           # Enable verification of the client certificate.
+           ssl_verify_client on;
+
+           # For URLs such as https://kea.example.org/kea, forward the
+           # requests to http://127.0.0.1:8080.
+           location /kea {
+               proxy_pass http://127.0.0.1:8080;
+           }
+       }
+   }
+
+..
+
+   **Note**
+
+   Note that the configuration snippet provided above is for testing
+   purposes only. It should be modified according to the security
+   policies and best practices of your organization.
+
+When you use an HTTP client without TLS support as ``kea-shell``, you
+can use an HTTP/HTTPS translator such as stunnel in client mode. A
+sample configuration is provided in the ``doc/examples/https/shell/``
+directory.
+
+.. _agent-launch:
+
+Starting the Control Agent
+==========================
+
+The CA is started by running its binary and specifying the configuration
+file it should use. For example:
+
+::
+
+   $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
+
+It can be started by keactrl as well (see `??? <#keactrl>`__).
+
+.. _agent-clients:
+
+Connecting to the Control Agent
+===============================
+
+For an example of a tool that can take advantage of the RESTful API, see
+`??? <#kea-shell>`__.

doc/guide/conf.py

+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Kea Administrator Reference Manual'
+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.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'kea-guide'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# 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
+# documentation.
+#
+html_theme_options = {
+    "logo": "kea-logo-100x70.png",
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'KeaAdministratorReferenceManualdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'KeaAdministratorReferenceManual.tex', 'Kea Administrator Reference Manual Documentation',
+     'Kea Team', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'keaadministratorreferencemanual', 'Kea Administrator Reference Manual Documentation',
+     [author], 1)
+]
+
+
+# -- 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

doc/guide/config-backend.rst

+.. _config-backend:
+
+Kea Configuration Backend
+=========================
+
+.. _cb-applicability:
+
+Applicability
+-------------
+
+Kea Configuration Backend (abbreviated as CB) is a feature first
+introduced in 1.6.0 release, which provides Kea servers with the ability
+to manage and fetch their configuration from one or more databases. In
+the documentation, the term "Configuration Backend" may also refer to
+the particular Kea module providing support to manage and fetch the
+configuration information from the particular database type. For
+example: MySQL Configuration Backend is the logic implemented within the
+"mysql_cb" hooks library which provides a complete set of functions to
+manage and fetch the configuration information from the MySQL database.
+
+In small deployments, e.g. those comprising a single DHCP server
+instance with limited and infrequently changing number of subnets, it
+may be impractical to use the CB as a configuration repository because
+it requires additional third party software to be installed and
+configured - in particular the MySQL server and MySQL client. Once the
+number of DHCP servers and/or the number of managed subnets in the
+network grows, the usefulness of the CB becomes obvious.
+
+A good example is a pair of the Kea DHCP servers which can be configured
+to support High Availability as described in
+`??? <#high-availability-library>`__. The configurations of both servers
+are almost exactly the same. They may differ by the server identifier
+and designation of the server as a primary or standby (or secondary).
+They may also differ by the interfaces configuration. Typically, the
+subnets, shared networks, option definitions, global parameters are the
+same for both servers and can be sourced from a single database instance
+to both Kea servers.
+
+Using the database as a single source of configuration for subnets
+and/or other configuration information supported by the CB has the
+advantage that any modifications to the configuration in the database is
+automatically applied to both servers.
+
+Another case when the centralized configuration repository is desired is
+in deployments including large number of the DHCP servers, possibly
+using a common lease database to provide redundancy. The new servers can
+be added to the pool frequently to fulfil growing scalability
+requirements. Adding the new server does not require replicating the
+entire configuration to the new server when common database is used.
+