From: Michal Nowikowski Date: Tue, 16 Jul 2019 16:40:50 +0000 (+0200) Subject: improved build scripts, renamed kea-guide.rst to index.rst X-Git-Tag: Kea-1.6.1~10^2~87 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d1f24e171581cee0f15866533d9f9c085da9f6eb;p=thirdparty%2Fkea.git improved build scripts, renamed kea-guide.rst to index.rst --- diff --git a/configure.ac b/configure.ac index 8d5085ac31..416dece115 100644 --- a/configure.ac +++ b/configure.ac @@ -1440,25 +1440,56 @@ AC_ARG_ENABLE(generate_docs, [AC_HELP_STRING([--enable-generate-docs], if test "x$enable_generate_docs" != xno ; then -# Check for xsltproc - AC_PATH_PROG([SPHINX], [sphinx-build]) - if test -z "$SPHINX"; then +# Check for sphinx-build + AC_PATH_PROG([SPHINXBUILD], [sphinx-build]) + if test -z "$SPHINXBUILD"; then AC_MSG_ERROR([sphinx-build not found; it is required for --enable-generate-docs, please see http://www.sphinx-doc.org/en/master/usage/installation.html for details]) else - AC_MSG_CHECKING([whether $SPHINX works]) + AC_MSG_CHECKING([whether $SPHINXBUILD works]) # run sphinx to see if it works # We should probably do a more thorough checks - $SPHINX --version + $SPHINXBUILD --version if test $? -ne 0 ; then - AC_MSG_ERROR("Error with $SPHINX --version") + AC_MSG_ERROR("Error with $SPHINXBUILD --version") fi - AC_MSG_RESULT(yes (found in $SPHINX)) + AC_MSG_RESULT(yes (found in $SPHINXBUILD)) + fi + +# xsltproc --nonet parameter + NONET="--nonet" + AC_ARG_VAR(XSLTPROC_NET, [xsltproc uses the Internet to fetch DTDs, entities or documents.]) + if test "x$XSLTPROC_NET" != x ; then + NONET= + fi + AC_SUBST(NONET) + +# Check for xsltproc + AC_PATH_PROG([XSLTPROC], [xsltproc]) + if test -z "$XSLTPROC"; then + AC_MSG_ERROR("xsltproc not found; it is required for --enable-generate-docs") + else + AC_MSG_CHECKING([if $XSLTPROC works]) + # run xsltproc to see if works + $XSLTPROC --novalid --xinclude $NONET http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl + if test $? -ne 0 ; then + AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/manpages/docbook.xsl") + fi + $XSLTPROC --novalid --xinclude $NONET http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl + if test $? -ne 0 ; then + AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/html/docbook.xsl") + fi + AC_MSG_RESULT(yes) + fi + + AC_PATH_PROG([ELINKS], [elinks]) + if test -z "$ELINKS"; then + AC_MSG_ERROR("elinks not found; it is required for --enable-generate-docs") fi fi # Don't fail here if not found, used to generate PDF documentation. -#AC_PATH_PROG([DBLATEX], [dblatex]) -#AM_CONDITIONAL(HAVE_DBLATEX, test "x$DBLATEX" != "x") +AC_PATH_PROG([DBLATEX], [dblatex]) +AM_CONDITIONAL(HAVE_DBLATEX, test "x$DBLATEX" != "x") AM_CONDITIONAL(GENERATE_DOCS, test x$enable_generate_docs != xno) diff --git a/doc/Makefile.am b/doc/Makefile.am index 8af9ce31f6..6b6e666d02 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -182,15 +182,6 @@ devel: (cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings/errors detected. -guide: - $(MAKE) -C guide kea-guide.html - -pdf: - $(MAKE) -C guide kea-guide.pdf - -pages: - $(MAKE) -C guide pages - clean: rm -rf html diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 660fab97f9..9426e67f12 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -1,5 +1,17 @@ +if GENERATE_DOCS +# TODO +#HTMLDOCS = kea-guide.html kea-messages.html +#DOCS = kea-guide.txt -rst_sources=admin.rst +#dist_doc_DATA = $(DOCS) +#dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png +#dist_html_DATA = $(HTMLDOCS) _static/kea-logo-100x70.png + +#doc_DATA = _build/singlehtml/kea-guide.html _build/singlehtml/_static/kea-logo-100x70.png + +rst_sources= +rst_sources+=kea-messages.rst +rst_sources+=admin.rst rst_sources+=agent.rst rst_sources+=api.rst rst_sources+=classify.rst @@ -20,9 +32,9 @@ rst_sources+=hooks-radius.rst rst_sources+=hooks.rst rst_sources+=hooks-stat-cmds.rst rst_sources+=install.rst +rst_sources+=index.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 @@ -31,8 +43,50 @@ rst_sources+=quickstart.rst rst_sources+=shell.rst rst_sources+=stats.rst +static_sources= +static_sources+=_static/kea-imageonly-100bw.png +static_sources+=_static/kea-logo-200.png +static_sources+=_static/kea.css + +all_sources=$(rst_sources) conf.py $(static_sources) + + +EXTRA_DIST = $(all_sources) $(top_srcdir)/tools/system_messages.py + +DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml + +CLEANFILES = kea-guide.pdf kea-messages.pdf + +mes_files= +mes_files+=$(top_srcdir)/src/hooks/dhcp/mysql_cb/mysql_cb_messages.mes +mes_files+=$(top_srcdir)/src/hooks/dhcp/lease_cmds/lease_cmds_messages.mes +mes_files+=$(top_srcdir)/src/hooks/dhcp/high_availability/ha_messages.mes +mes_files+=$(top_srcdir)/src/hooks/dhcp/stat_cmds/stat_cmds_messages.mes +mes_files+=$(top_srcdir)/src/hooks/dhcp/user_chk/user_chk_messages.mes +mes_files+=$(top_srcdir)/src/lib/config/config_messages.mes +mes_files+=$(top_srcdir)/src/lib/hooks/hooks_messages.mes +mes_files+=$(top_srcdir)/src/lib/dhcpsrv/dhcpsrv_messages.mes +mes_files+=$(top_srcdir)/src/lib/dhcpsrv/alloc_engine_messages.mes +mes_files+=$(top_srcdir)/src/lib/dhcpsrv/hosts_messages.mes +mes_files+=$(top_srcdir)/src/lib/http/http_messages.mes +mes_files+=$(top_srcdir)/src/lib/dhcp_ddns/dhcp_ddns_messages.mes +mes_files+=$(top_srcdir)/src/lib/database/db_messages.mes +mes_files+=$(top_srcdir)/src/lib/log/log_messages.mes +mes_files+=$(top_srcdir)/src/lib/log/logimpl_messages.mes +mes_files+=$(top_srcdir)/src/lib/log/tests/log_test_messages.mes +mes_files+=$(top_srcdir)/src/lib/process/process_messages.mes +mes_files+=$(top_srcdir)/src/lib/asiodns/asiodns_messages.mes +mes_files+=$(top_srcdir)/src/lib/eval/eval_messages.mes +mes_files+=$(top_srcdir)/src/bin/dhcp4/dhcp4_messages.mes +mes_files+=$(top_srcdir)/src/bin/agent/ca_messages.mes +mes_files+=$(top_srcdir)/src/bin/d2/d2_messages.mes +mes_files+=$(top_srcdir)/src/bin/dhcp6/dhcp6_messages.mes +mes_files+=$(top_srcdir)/src/bin/lfc/lfc_messages.mes +mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes + +kea-messages.rst: $(mes_files) $(top_srcdir)/tools/system_messages.py + $(top_srcdir)/tools/system_messages.py -o $@ $(mes_files) -sphinxbuild = sphinx-build sphinxopts= sphinxopts+=-v @@ -44,21 +98,28 @@ sphinxopts+=-D version="@PACKAGE_VERSION@" sphinxbuilddir=$(builddir)/_build -all: pdf html singlehtml +all: pdf html -pdf: $(rst_sources) - $(sphinxbuild) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts) +pdf: $(all_sources) + $(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts) -html singlehtml: $(rst_sources) - $(sphinxbuild) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts) +html: $(all_sources) + $(SPHINXBUILD) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts) -EXTRA_DIST = $(rst_sources) +install-data-local: + mkdir -p $(DESTDIR)$(docdir) + cp -r $(sphinxbuilddir)/html $(DESTDIR)$(docdir) + cp -r $(sphinxbuilddir)/latex/KeaAdministratorReferenceManual.pdf $(DESTDIR)$(docdir) -# TODO: here should be added some stuff for DIST, etc to be consumed by automake/autoconf +uninstall-local: + rm -rf $(DESTDIR)$(docdir) clean:: -rm -rf $(sphinxbuilddir) -.PHONY: all pdf html singlehtml +.PHONY: all pdf html + + +endif diff --git a/doc/guide/_static/kea-imageonly-100bw.png b/doc/guide/_static/kea-imageonly-100bw.png new file mode 100644 index 0000000000..fdbaf40359 Binary files /dev/null and b/doc/guide/_static/kea-imageonly-100bw.png differ diff --git a/doc/guide/_static/kea-logo-200.png b/doc/guide/_static/kea-logo-200.png new file mode 100644 index 0000000000..7dbd993d02 Binary files /dev/null and b/doc/guide/_static/kea-logo-200.png differ diff --git a/doc/guide/conf.py b/doc/guide/conf.py index e8ef7d822f..cf7559a6e9 100644 --- a/doc/guide/conf.py +++ b/doc/guide/conf.py @@ -46,7 +46,10 @@ templates_path = ['_templates'] source_suffix = '.rst' # The master toctree document. -master_doc = 'kea-guide' +master_doc = 'index' + +# Additional docs +messages_doc = 'kea-messages' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -71,14 +74,16 @@ pygments_style = None # #html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' +#html_logo = '_static/kea-logo-100x70.png' +html_logo = '_static/kea-imageonly-100bw.png' # 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", -} +#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, @@ -126,8 +131,8 @@ latex_elements = { # (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'), + (master_doc, 'KeaAdministratorReferenceManual.tex', 'Kea Administrator Reference Manual Documentation', author, 'manual'), + (messages_doc, 'KeaMessages.tex', 'Kea Messages Manual', author, 'manual'), ] diff --git a/doc/guide/kea-guide.rst b/doc/guide/index.rst similarity index 97% rename from doc/guide/kea-guide.rst rename to doc/guide/index.rst index 9a3ad2cfc5..dbff406bd3 100644 --- a/doc/guide/kea-guide.rst +++ b/doc/guide/index.rst @@ -1,3 +1,6 @@ +.. figure:: _static/kea-logo-200.png + :align: right + ################################## Kea Administrator Reference Manual ################################## diff --git a/doc/guide/logging.rst b/doc/guide/logging.rst index d2ea69cde5..ff061d7697 100644 --- a/doc/guide/logging.rst +++ b/doc/guide/logging.rst @@ -124,337 +124,337 @@ libraries), or hooks libraries (open source or premium). .. table:: List of Loggers Supported by Kea Servers and Hooks Libraries Shipped With Kea and Premium Packages - +----------------------------------+------------------------+-----------------------+ - | Logger Name | Software Package | Description | - +==================================+========================+=======================+ - | ``kea-ctrl-agent`` | core | The root logger for | - | | | the Control Agent | - | | | exposing the RESTful | - | | | control API. All | - | | | components used by | - | | | the Control Agent | - | | | inherit the settings | - | | | from this logger. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-ctrl-agent.http`` | core | A logger which | - | | | outputs log messages | - | | | related to receiving, | - | | | parsing, and sending | - | | | HTTP messages. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4`` | core | The root logger for | - | | | the DHCPv4 server. | - | | | All components used | - | | | by the DHCPv4 server | - | | | inherit the settings | - | | | from this logger. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp6`` | core | The root logger for | - | | | the DHCPv6 server. | - | | | All components used | - | | | by the DHCPv6 server | - | | | inherit the settings | - | | | from this logger. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.alloc-engine``, | core | Used by the lease | - | ``kea-dhcp6.alloc-engine`` | | allocation engine, | - | | | which is responsible | - | | | for managing leases | - | | | in the lease | - | | | database, i.e. | - | | | creating, modifying, | - | | | and removing DHCP | - | | | leases as a result of | - | | | processing messages | - | | | from clients. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.bad-packets``, | core | Used by the DHCP | - | ``kea-dhcp6.bad-packets`` | | servers for logging | - | | | inbound client | - | | | packets that were | - | | | dropped or to which | - | | | the server responded | - | | | with a DHCPNAK. It | - | | | allows administrators | - | | | to configure a | - | | | separate log output | - | | | that contains only | - | | | packet drop and | - | | | reject entries. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.callouts``, | core | Used to log messages | - | ``kea-dhcp6.callouts`` | | pertaining to the | - | | | callouts registration | - | | | and execution for the | - | | | particular hook | - | | | point. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.commands``, | core | Used to log messages | - | ``kea-dhcp6.commands`` | | relating to the | - | | | handling of commands | - | | | received by the DHCP | - | | | server over the | - | | | command channel. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.database``, | core | Used to log messages | - | ``kea-dhcp6.database`` | | relating to general | - | | | operations on the | - | | | relational databases | - | | | and Cassandra. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.ddns``, | core | Used by the DHCP | - | ``kea-dhcp6.ddns`` | | server to log | - | | | messages related to | - | | | Client FQDN and | - | | | Hostname option | - | | | processing. It also | - | | | includes log messages | - | | | related to the | - | | | relevant DNS updates. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 | - | | | server daemon to log | - | | | basic operations. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.dhcpsrv``, | core | The base loggers for | - | ``kea-dhcp6.dhcpsrv`` | | the libkea-dhcpsrv | - | | | library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.eval``, | core | Used to log messages | - | ``kea-dhcp6.eval`` | | relating to the | - | | | client classification | - | | | expression evaluation | - | | | code. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.host-cache-hooks``, | libdhcp_host_cache | This logger is used | - | ``kea-dhcp6.host-cache-hooks`` | premium hook library | to log messages | - | | | related to the | - | | | operation of the Host | - | | | Cache hooks library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.flex-id-hooks``, | libdhcp_flex_id | This logger is used | - | ``kea-dhcp6.flex-id-hooks`` | premium hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | Flexible Identifiers | - | | | hooks library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.ha-hooks``, | libdhcp_ha hook | This logger is used | - | ``kea-dhcp6.ha-hooks`` | library | to log messages | - | | | related to the | - | | | operation of the High | - | | | Availability hooks | - | | | library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.hooks``, | core | Used to log messages | - | ``kea-dhcp6.hooks`` | | related to the | - | | | management of hooks | - | | | libraries, e.g. | - | | | registration and | - | | | deregistration of the | - | | | libraries, and to the | - | | | initialization of the | - | | | callouts execution | - | | | for various hook | - | | | points within the | - | | | DHCP server. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.host-cmds-hooks``, | libdhcp_host_cmds | This logger is used | - | ``kea-dhcp6.host-cmds-hooks`` | premium hook library | to log messages | - | | | related to the | - | | | operation of the Host | - | | | Commands hooks | - | | | library. In general, | - | | | these will pertain to | - | | | the loading and | - | | | unloading of the | - | | | library and the | - | | | execution of commands | - | | | by the library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.hosts``, | core | Used within the | - | ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs | - | | | messages related to | - | | | the management of | - | | | DHCP host | - | | | reservations, i.e. | - | | | retrieving | - | | | reservations and | - | | | adding new | - | | | reservations. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.lease-cmds-hooks``, | libdhcp_lease_cmds | This logger is used | - | ``kea-dhcp6.lease-cmds-hooks`` | hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | Lease Commands hooks | - | | | library. In general, | - | | | these will pertain to | - | | | the loading and | - | | | unloading of the | - | | | library and the | - | | | execution of commands | - | | | by the library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.leases``, | core | Used by the DHCP | - | ``kea-dhcp6.leases`` | | server to log | - | | | messages related to | - | | | lease allocation. The | - | | | messages include | - | | | detailed information | - | | | about the allocated | - | | | or offered leases, | - | | | errors during the | - | | | lease allocation, | - | | | etc. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.legal-log-hooks``, | libdhcp_legal_log | This logger is used | - | ``kea-dhcp6.legal-log-hooks`` | premium hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | Forensic Logging | - | | | hooks library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.options``, | core | Used by the DHCP | - | ``kea-dhcp4.options`` | | server to log | - | | | messages related to | - | | | the processing of | - | | | options in the DHCP | - | | | messages, i.e. | - | | | parsing options, | - | | | encoding options into | - | | | on-wire format, and | - | | | packet classification | - | | | using options | - | | | contained in the | - | | | received packets. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.packets``, | core | This logger is mostly | - | ``kea-dhcp6.packets`` | | used to log messages | - | | | related to | - | | | transmission of the | - | | | DHCP packets, i.e. | - | | | packet reception and | - | | | the sending of a | - | | | response. Such | - | | | messages include | - | | | information about the | - | | | source and | - | | | destination IP | - | | | addresses and | - | | | interfaces used to | - | | | transmit packets. The | - | | | logger is also used | - | | | to log messages | - | | | related to subnet | - | | | selection, as this | - | | | selection is usually | - | | | based on the IP | - | | | addresses, relay | - | | | addresses, and/or | - | | | interface names, | - | | | which can be | - | | | retrieved from the | - | | | received packet even | - | | | before the DHCP | - | | | message carried in | - | | | the packet is parsed. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.radius-hooks``, | libdhcp_radius | This logger is used | - | ``kea-dhcp6.radius-hooks`` | premium hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | RADIUS hooks library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.stat-cmds-hooks``, | libdhcp_stat_cmds | This logger is used | - | ``kea-dhcp6.stat-cmds-hooks`` | hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | Statistics Commands | - | | | hooks library. In | - | | | general, these will | - | | | pertain to loading | - | | | and unloading the | - | | | library and the | - | | | execution of commands | - | | | by the library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds | This logger is used | - | ``kea-dhcp6.subnet-cmds-hooks`` | hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | Subnet Commands hooks | - | | | library. In general, | - | | | these will pertain to | - | | | loading and unloading | - | | | the library and the | - | | | execution of commands | - | | | by the library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp4.mysql-cb-hooks``, | libdhcp_mysql_cb_hooks | This logger is used | - | ``kea-dhcp6.mysql-cb-hooks`` | hook library | to log messages | - | | | related to the | - | | | operation of the | - | | | MySQL Configuration | - | | | Backend hooks | - | | | library. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp-ddns`` | core | The root logger for | - | | | the kea-dhcp-ddns | - | | | daemon. All | - | | | components used by | - | | | this daemon inherit | - | | | the settings from | - | | | this logger unless | - | | | there are | - | | | configurations for | - | | | more specialized | - | | | loggers. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp-ddns.dctl`` | core | The logger used by | - | | | the kea-dhcp-ddns | - | | | daemon for logging | - | | | basic information | - | | | about the process, | - | | | received signals, and | - | | | triggered | - | | | reconfigurations. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp-ddns.dhcpddns`` | core | The logger used by | - | | | the kea-dhcp-ddns | - | | | daemon for logging | - | | | events related to | - | | | DDNS operations. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the | - | | | kea-dhcp-ddns daemon | - | | | for logging | - | | | information about | - | | | events dealing with | - | | | receiving messages | - | | | from the DHCP servers | - | | | and adding them to | - | | | the queue for | - | | | processing. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the | - | | | kea-dhcp-ddns daemon | - | | | for logging | - | | | information about | - | | | events dealing with | - | | | sending and receiving | - | | | messages to and from | - | | | the DNS servers. | - +----------------------------------+------------------------+-----------------------+ - | ``kea-netconf`` | core | The root logger for | - | | | the NETCONF agent. | - | | | All components used | - | | | by NETCONF inherit | - | | | the settings from | - | | | this logger if there | - | | | is no specialized | - | | | logger provided. | - +----------------------------------+------------------------+-----------------------+ + +----------------------------------+------------------------+--------------------------------+ + | Logger Name | Software Package | Description | + +==================================+========================+================================+ + | ``kea-ctrl-agent`` | core | The root logger for | + | | | the Control Agent | + | | | exposing the RESTful | + | | | control API. All | + | | | components used by | + | | | the Control Agent | + | | | inherit the settings | + | | | from this logger. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-ctrl-agent.http`` | core | A logger which | + | | | outputs log messages | + | | | related to receiving, | + | | | parsing, and sending | + | | | HTTP messages. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4`` | core | The root logger for | + | | | the DHCPv4 server. | + | | | All components used | + | | | by the DHCPv4 server | + | | | inherit the settings | + | | | from this logger. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp6`` | core | The root logger for | + | | | the DHCPv6 server. | + | | | All components used | + | | | by the DHCPv6 server | + | | | inherit the settings | + | | | from this logger. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.alloc-engine``, | core | Used by the lease | + | ``kea-dhcp6.alloc-engine`` | | allocation engine, | + | | | which is responsible | + | | | for managing leases | + | | | in the lease | + | | | database, i.e. | + | | | creating, modifying, | + | | | and removing DHCP | + | | | leases as a result of | + | | | processing messages | + | | | from clients. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.bad-packets``, | core | Used by the DHCP | + | ``kea-dhcp6.bad-packets`` | | servers for logging | + | | | inbound client | + | | | packets that were | + | | | dropped or to which | + | | | the server responded | + | | | with a DHCPNAK. It | + | | | allows administrators | + | | | to configure a | + | | | separate log output | + | | | that contains only | + | | | packet drop and | + | | | reject entries. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.callouts``, | core | Used to log messages | + | ``kea-dhcp6.callouts`` | | pertaining to the | + | | | callouts registration | + | | | and execution for the | + | | | particular hook | + | | | point. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.commands``, | core | Used to log messages | + | ``kea-dhcp6.commands`` | | relating to the | + | | | handling of commands | + | | | received by the DHCP | + | | | server over the | + | | | command channel. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.database``, | core | Used to log messages | + | ``kea-dhcp6.database`` | | relating to general | + | | | operations on the | + | | | relational databases | + | | | and Cassandra. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.ddns``, | core | Used by the DHCP | + | ``kea-dhcp6.ddns`` | | server to log | + | | | messages related to | + | | | Client FQDN and | + | | | Hostname option | + | | | processing. It also | + | | | includes log messages | + | | | related to the | + | | | relevant DNS updates. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 | + | | | server daemon to log | + | | | basic operations. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.dhcpsrv``, | core | The base loggers for | + | ``kea-dhcp6.dhcpsrv`` | | the libkea-dhcpsrv | + | | | library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.eval``, | core | Used to log messages | + | ``kea-dhcp6.eval`` | | relating to the | + | | | client classification | + | | | expression evaluation | + | | | code. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.host-cache-hooks``, | libdhcp_host_cache | This logger is used | + | ``kea-dhcp6.host-cache-hooks`` | premium hook library | to log messages | + | | | related to the | + | | | operation of the Host | + | | | Cache hooks library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.flex-id-hooks``, | libdhcp_flex_id | This logger is used | + | ``kea-dhcp6.flex-id-hooks`` | premium hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | Flexible Identifiers | + | | | hooks library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.ha-hooks``, | libdhcp_ha hook | This logger is used | + | ``kea-dhcp6.ha-hooks`` | library | to log messages | + | | | related to the | + | | | operation of the High | + | | | Availability hooks | + | | | library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.hooks``, | core | Used to log messages | + | ``kea-dhcp6.hooks`` | | related to the | + | | | management of hooks | + | | | libraries, e.g. | + | | | registration and | + | | | deregistration of the | + | | | libraries, and to the | + | | | initialization of the | + | | | callouts execution | + | | | for various hook | + | | | points within the | + | | | DHCP server. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.host-cmds-hooks``, | libdhcp_host_cmds | This logger is used | + | ``kea-dhcp6.host-cmds-hooks`` | premium hook library | to log messages | + | | | related to the | + | | | operation of the Host | + | | | Commands hooks | + | | | library. In general, | + | | | these will pertain to | + | | | the loading and | + | | | unloading of the | + | | | library and the | + | | | execution of commands | + | | | by the library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.hosts``, | core | Used within the | + | ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs | + | | | messages related to | + | | | the management of | + | | | DHCP host | + | | | reservations, i.e. | + | | | retrieving | + | | | reservations and | + | | | adding new | + | | | reservations. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.lease-cmds-hooks``, | libdhcp_lease_cmds | This logger is used | + | ``kea-dhcp6.lease-cmds-hooks`` | hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | Lease Commands hooks | + | | | library. In general, | + | | | these will pertain to | + | | | the loading and | + | | | unloading of the | + | | | library and the | + | | | execution of commands | + | | | by the library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.leases``, | core | Used by the DHCP | + | ``kea-dhcp6.leases`` | | server to log | + | | | messages related to | + | | | lease allocation. The | + | | | messages include | + | | | detailed information | + | | | about the allocated | + | | | or offered leases, | + | | | errors during the | + | | | lease allocation, | + | | | etc. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.legal-log-hooks``, | libdhcp_legal_log | This logger is used | + | ``kea-dhcp6.legal-log-hooks`` | premium hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | Forensic Logging | + | | | hooks library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.options``, | core | Used by the DHCP | + | ``kea-dhcp4.options`` | | server to log | + | | | messages related to | + | | | the processing of | + | | | options in the DHCP | + | | | messages, i.e. | + | | | parsing options, | + | | | encoding options into | + | | | on-wire format, and | + | | | packet classification | + | | | using options | + | | | contained in the | + | | | received packets. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.packets``, | core | This logger is mostly | + | ``kea-dhcp6.packets`` | | used to log messages | + | | | related to | + | | | transmission of the | + | | | DHCP packets, i.e. | + | | | packet reception and | + | | | the sending of a | + | | | response. Such | + | | | messages include | + | | | information about the | + | | | source and | + | | | destination IP | + | | | addresses and | + | | | interfaces used to | + | | | transmit packets. The | + | | | logger is also used | + | | | to log messages | + | | | related to subnet | + | | | selection, as this | + | | | selection is usually | + | | | based on the IP | + | | | addresses, relay | + | | | addresses, and/or | + | | | interface names, | + | | | which can be | + | | | retrieved from the | + | | | received packet even | + | | | before the DHCP | + | | | message carried in | + | | | the packet is parsed. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.radius-hooks``, | libdhcp_radius | This logger is used | + | ``kea-dhcp6.radius-hooks`` | premium hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | RADIUS hooks library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.stat-cmds-hooks``, | libdhcp_stat_cmds | This logger is used | + | ``kea-dhcp6.stat-cmds-hooks`` | hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | Statistics Commands | + | | | hooks library. In | + | | | general, these will | + | | | pertain to loading | + | | | and unloading the | + | | | library and the | + | | | execution of commands | + | | | by the library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds | This logger is used | + | ``kea-dhcp6.subnet-cmds-hooks`` | hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | Subnet Commands hooks | + | | | library. In general, | + | | | these will pertain to | + | | | loading and unloading | + | | | the library and the | + | | | execution of commands | + | | | by the library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp4.mysql-cb-hooks``, | libdhcp_mysql_cb_hooks | This logger is used | + | ``kea-dhcp6.mysql-cb-hooks`` | hook library | to log messages | + | | | related to the | + | | | operation of the | + | | | MySQL Configuration | + | | | Backend hooks | + | | | library. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp-ddns`` | core | The root logger for | + | | | the kea-dhcp-ddns | + | | | daemon. All | + | | | components used by | + | | | this daemon inherit | + | | | the settings from | + | | | this logger unless | + | | | there are | + | | | configurations for | + | | | more specialized | + | | | loggers. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp-ddns.dctl`` | core | The logger used by | + | | | the kea-dhcp-ddns | + | | | daemon for logging | + | | | basic information | + | | | about the process, | + | | | received signals, and | + | | | triggered | + | | | reconfigurations. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp-ddns.dhcpddns`` | core | The logger used by | + | | | the kea-dhcp-ddns | + | | | daemon for logging | + | | | events related to | + | | | DDNS operations. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the | + | | | kea-dhcp-ddns daemon | + | | | for logging | + | | | information about | + | | | events dealing with | + | | | receiving messages | + | | | from the DHCP servers | + | | | and adding them to | + | | | the queue for | + | | | processing. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the | + | | | kea-dhcp-ddns daemon | + | | | for logging | + | | | information about | + | | | events dealing with | + | | | sending and receiving | + | | | messages to and from | + | | | the DNS servers. | + +----------------------------------+------------------------+--------------------------------+ + | ``kea-netconf`` | core | The root logger for | + | | | the NETCONF agent. | + | | | All components used | + | | | by NETCONF inherit | + | | | the settings from | + | | | this logger if there | + | | | is no specialized | + | | | logger provided. | + +----------------------------------+------------------------+--------------------------------+ Note that user-defined hook libraries should not use any of the loggers mentioned above, but should instead define new loggers with names that diff --git a/tools/system_messages.py b/tools/system_messages.py new file mode 100755 index 0000000000..6dee59f95c --- /dev/null +++ b/tools/system_messages.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 + +# Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC") +# +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, You can obtain one at http:#mozilla.org/MPL/2.0/. + +# Produce System Messages Manual +# +# This tool reads all the message files given on the command line. +# It pulls all the messages and description out, sorts them by +# message ID, and writes them out as a single (formatted) file. +# +# Invocation: +# The code is invoked using the command line: +# +# system_messages.py [-o ] +# +# If no output file is specified, output is written to stdout. +# The produced format is ReStructuredText. + +import re +import argparse + + +def parse_args(): + parser = argparse.ArgumentParser(description='Convert set of *.mes files to .rst documentation format') + parser.add_argument('-o', '--output', help='Output file name (default to stdout).') + parser.add_argument('files', help='Input .mes files.', nargs='+') #, required=True) + + args = parser.parse_args() + return args + + +def read_input_files(files): + messages = {} + for f in files: + with open(f) as fp: + namespace = None + msg_descr = None + msg_id = None + msg_text = None + for line in fp.readlines(): + line = line.strip() + + if not line or line.startswith('#'): + pass + + elif line.startswith('$'): + pass + + elif line.startswith('%'): + # end previous message + if msg_id is not None: + section = msg_id.split('_')[0] + messages[msg_id] = (section, msg_id, msg_text, msg_descr) + + # start next message + m = re.search('^%\s?([A-Z0-9_]+)\s+(.*)', line); + msg_id, msg_text = m.groups() + msg_descr = [] + + else: + msg_descr.append(line) + + return messages + + +def generate_rst(messages): + rst = ''' +################### +Kea Messages Manual +################### + +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 |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 `_. + + +.. toctree:: + :numbered: + :maxdepth: 5 + +''' + + prev_section = None + for _, msg in sorted(messages.items()): + section, msg_id, msg_text, msg_descr = msg + + if section != prev_section: + prev_section = section + rst += section + '\n' + rst += '~' * len(section) + '\n\n' + + rst += '**' + msg_id + '**\n\n' + + rst += msg_text + '\n\n' + + rst += ''.join([' ' + l + '\n' for l in msg_descr]) + rst += '\n' + + + return rst + +def main(): + args = parse_args() + + messages = read_input_files(args.files) + + rst = generate_rst(messages) + + if args.output: + with open(args.output, 'w') as f: + f.write(rst) + else: + print(rst) + +if __name__ == '__main__': + main()