Commit b5b87d18 authored by Michal Nowikowski's avatar Michal Nowikowski
Browse files

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
parent a13c6ef7
......@@ -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
/* 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;
}
......@@ -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
......
......@@ -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
......
......@@ -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')
......@@ -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/
......
This diff is collapsed.
......@@ -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,
......
......@@ -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 <https://ccache.samba.org/>`__. 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
......@@ -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": [