packaging: kresctl man page, manager's unit file

diff --git a/distro/pkg/deb/python3-knot-resolver-manager.install b/distro/pkg/deb/python3-knot-resolver-manager.install
index 449b4632e91c3a233edaec6c92a343da0964e59e..b614a4bbbc24e41765adf0e0c0ca0fa8327e3a4a 100644 (file)
--- a/distro/pkg/deb/python3-knot-resolver-manager.install
+++ b/distro/pkg/deb/python3-knot-resolver-manager.install
@@ -1,2 +1,2 @@
 etc/knot-resolver/config.yml
-lib/systemd/system/knot-resolver.service
+usr/lib/systemd/system/knot-resolver.service

diff --git a/distro/pkg/deb/python3-knot-resolver-manager.manpages b/distro/pkg/deb/python3-knot-resolver-manager.manpages
new file mode 100644 (file)
index 0000000..a453f7e
--- /dev/null
+++ b/distro/pkg/deb/python3-knot-resolver-manager.manpages
@@ -0,0 +1 @@
+debian/tmp/usr/share/man/man8/kresctl.8*

diff --git a/distro/pkg/deb/rules b/distro/pkg/deb/rules
index 26a2ff3f9f9b9ee182fcfc2727d5a8acd3aa5ff9..f0b482b9a8b404a954590291d88e9154915d3e17 100755 (executable)
--- a/distro/pkg/deb/rules
+++ b/distro/pkg/deb/rules
@@ -43,7 +43,6 @@ override_dh_auto_install:
        DESTDIR="${PWD}/debian/tmp" ninja -v -C build_deb install
        dh_auto_install --buildsystem=pybuild --sourcedirectory manager
        install -m 644 -D $(CURDIR)/manager/etc/knot-resolver/config.yml $(CURDIR)/debian/tmp/etc/knot-resolver/config.yml
-       install -m 644 -D $(CURDIR)/manager/knot-resolver.service $(CURDIR)/debian/tmp/lib/systemd/system/knot-resolver.service
 
 override_dh_auto_test:
        meson test -C build_deb

diff --git a/distro/pkg/rpm/knot-resolver.spec b/distro/pkg/rpm/knot-resolver.spec
index f0318ec3de54632d972f0a3712e677f119bce836..7edcfe3f788a869d55eecb00fc0be1a95fa05a32 100644 (file)
--- a/distro/pkg/rpm/knot-resolver.spec
+++ b/distro/pkg/rpm/knot-resolver.spec
@@ -229,7 +229,6 @@ mv %{buildroot}/%{_datadir}/doc/%{name}/* %{buildroot}/%{_pkgdocdir}/
 pushd manager
 %py3_install
 install -m 644 -D etc/knot-resolver/config.yml %{buildroot}%{_sysconfdir}/knot-resolver/config.yml
-install -m 644 -D knot-resolver.service %{buildroot}%{_unitdir}/knot-resolver.service
 popd
 
 %pre
@@ -357,6 +356,7 @@ fi
 %{_libdir}/knot-resolver/kres_modules/watchdog.lua
 %{_libdir}/knot-resolver/kres_modules/workarounds.lua
 %{_mandir}/man8/kresd.8.gz
+%{_mandir}/man8/kresctl.8.gz
 
 %files devel
 %{_includedir}/libkres

diff --git a/doc/kresctl.8.in b/doc/kresctl.8.in
new file mode 100644 (file)
index 0000000..04b383c
--- /dev/null
+++ b/doc/kresctl.8.in
@@ -0,0 +1,67 @@
+.TH "kresctl" "8" "@date@" "CZ.NIC" "Knot Resolver @version@"
+.\"
+.\" kresctl.8 -- Knot Resolver control tool manpage
+.\"
+.\" Copyright (c) 2022, CZ.NIC. All rights reserved.
+.\"
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\"
+.\"
+.SH "NAME"
+.B kresctl
+\- Control Knot Resolver @version@, the full caching DNSSEC-enabled resolver
+.SH "SYNOPSIS"
+.B kresctl
+.RB [ \-s | \-\-socket
+.IR API_SOCKET ]
+.IR <command>
+.IR <args>
+.SH "DESCRIPTION"
+.B \fIkresctl\fR is a control tool for Knot Resolver, a DNSSEC-enabled full caching resolver.
+.P
+
+\fBkresctl\fR may be used to control and inspect the configuration of running
+Knot Resolver via its HTTP API.
+
+Full documentation is available at
+\fIhttps://knot-resolver.readthedocs.io\fR or in package documentation
+(available as knot-resolver-doc package in most distributions.
+.SH OPTIONS
+The available options are:
+.TP
+.B \-s\fI <api_socket>\fR, \fB\-\-socket \fI<api_socket>
+
+Specify how to connect to a running Knot Resolver. Accepts path to Unix-domain
+socket  or \fIhost:port\fR. Defaults to \fI/var/run/knot-resolver/manager.sock\fR
+
+Some commands do not require communication with the running resolver. In such
+cases, the value of this option is ignored and the command may succeed even
+if the socket is invalid.
+.B \-h, --help
+Print help message and exit.
+.SH COMMANDS
+.TP
+.B config [-d|--delete] [--stdin] \fIjson_ptr\fR \fI[new_value]\fR
+Get or modify resolver's runtime configuration.
+
+\fIjson_ptr\fR follows \fBRFC 6901\fR and specifies, which part of the configuration
+will the tool operate on. This argument is required. When not given any additional
+options or arguments, prints the current configured value. Equivalent to GET method
+in the underlying HTTP API.
+
+When \fB-d\fR or \fB--delete\fR is provided, \fBkresctl\fB tries to remove
+the runtime configuration subtree. The operation fails if it renders the
+configuration invalid. Equivalent to the DELETE method in the HTTP API.
+
+When \fB--stdin\fR or \fInew_value\fR are provided, the new value (from the
+argument or from reading stdin) is put into the configuration at the given
+\fIjson_ptr\fR. The operation fails if it renders the configuration invalid.
+Equivalent to PUT method in the underlying HTTP API.
+.TP
+.B stop
+Gracefully stops the running resolver.
+.SH "SEE ALSO"
+\fBkresd(8)\fR, @man_seealso_systemd@\fIhttps://knot-resolver.readthedocs.io/en/v@version@/\fR
+.SH "AUTHORS"
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.

diff --git a/doc/meson.build b/doc/meson.build
index a8439c5a6b5f18e4dced24289c92296fd6a5786a..29e6faf93adaf673f6aa258aefc41923dcfe0e3a 100644 (file)
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -18,6 +18,12 @@ man_kresd = configure_file(
 )
 install_man(man_kresd)
 
+man_kresctl = configure_file(
+  input: 'kresctl.8.in',
+  output: 'kresctl.8',
+  configuration: man_config,
+)
+install_man(man_kresctl)
 
 # html and info documentation
 if get_option('doc') == 'enabled'

diff --git a/manager/meson.build b/manager/meson.build
index cfc8959269f0dbbf9da706f797f9c2ca5366e85a..b4be63f9038015a26a541c223788db22e6842742 100644 (file)
--- a/manager/meson.build
+++ b/manager/meson.build
@@ -31,12 +31,4 @@ if build_manager
         sources: 'etc/knot-resolver/config.yml',
         install_dir: etc_dir,
     )
-
-    # systemd service
-    if systemd_files == 'enabled'
-        install_data(
-            sources: 'knot-resolver.service',
-            install_dir: systemd_unit_dir,
-        )
-    endif
 endif
\ No newline at end of file

diff --git a/manager/pyproject.toml b/manager/pyproject.toml
index ac4cf48241d35023d3004a70a4b836e24fa5714b..0ddf341cb6bb65e804ce1900b0a61232ce26ed64 100644 (file)
--- a/manager/pyproject.toml
+++ b/manager/pyproject.toml
@@ -67,6 +67,7 @@ gen-setuppy = { shell = "python scripts/create_setup.py > setup.py", help = "Gen
 tox = { cmd = "tox", help = "Run tests in tox" }
 integration = {cmd = "python tests/integration/runner.py", help = "Run integration tests" }
 configure-vscode = {cmd = "scripts/configure-vscode", help = "Create VSCode configuration for debugging, virtual envs etc" }
+man = {cmd = "scripts/man", help = "Display manpage from sources" }
 
 
 [tool.black]

diff --git a/manager/scripts/_env.sh b/manager/scripts/_env.sh
index 57ab04b6aa665f87461090b4dd525190001de35a..b1941edfed5beee1ab04f04a3f848e8aaaeb71c2 100644 (file)
--- a/manager/scripts/_env.sh
+++ b/manager/scripts/_env.sh
@@ -33,3 +33,20 @@ PATH="$PATH:$gitroot/node_modules/.bin"
 
 # fail even on unbound variables
 set -o nounset
+
+
+function build_kresd {
+       echo
+       echo Building Knot Resolver
+       echo ----------------------
+       echo -e "${blue}In case of an compilation error, run this command to try to fix it:${reset}"
+       echo -e "\t${blue}rm -r $(realpath .install_kresd) $(realpath .build_kresd)${reset}"
+       echo
+       pushd ..
+       mkdir -p manager/.build_kresd manager/.install_kresd
+       meson manager/.build_kresd --prefix=$(realpath manager/.install_kresd) --default-library=static --buildtype=debug
+       ninja -C manager/.build_kresd
+       ninja install -C manager/.build_kresd
+       export PATH="$(realpath manager/.install_kresd)/sbin:$PATH"
+       popd
+}

diff --git a/manager/scripts/man b/manager/scripts/man
new file mode 100755 (executable)
index 0000000..ba28e41
--- /dev/null
+++ b/manager/scripts/man
@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# ensure consistent behaviour
+src_dir="$(dirname "$(realpath "$0")")"
+source $src_dir/_env.sh
+
+build_kresd
+
+man -l .install_kresd/share/man/man8/$1*
\ No newline at end of file

diff --git a/manager/scripts/run b/manager/scripts/run
index 76b7f9d99b9426c906c7c039c056b829cf5c6f83..d9c7d28f2102c1f02c4a71e6c667159c6ead7660 100755 (executable)
--- a/manager/scripts/run
+++ b/manager/scripts/run
@@ -4,19 +4,7 @@
 src_dir="$(dirname "$(realpath "$0")")"
 source $src_dir/_env.sh
 
-echo
-echo Building Knot Resolver
-echo ----------------------
-echo -e "${blue}In case of an compilation error, run this command to try to fix it:${reset}"
-echo -e "\t${blue}rm -r $(realpath .install_kresd) $(realpath .build_kresd)${reset}"
-echo
-cd ..
-mkdir -p manager/.build_kresd manager/.install_kresd
-meson manager/.build_kresd --prefix=$(realpath manager/.install_kresd) --default-library=static --buildtype=debug -Dmanager=enabled
-ninja -C manager/.build_kresd
-ninja install -C manager/.build_kresd
-export PATH="$(realpath manager/.install_kresd)/sbin:$PATH"
-cd manager
+build_kresd
 
 echo
 echo Building Knot Resolver Manager native extensions

diff --git a/manager/tests/packaging/control b/manager/tests/packaging/control
index 6f9c01fd26001d4f2190e0ef2bfae06a95157614..169552dc0dc6a77130b7b837d2828a20357edf25 100644 (file)
--- a/manager/tests/packaging/control
+++ b/manager/tests/packaging/control
@@ -27,3 +27,10 @@ Depends: knot-utils, jq, curl
 {% else -%}
 Depends: unsupported-distro-this-package-does-not-exist-and-the-test-should-fail
 {%- endif %}
+
+
+Tests: manpage.sh
+Tests-Directory: manager/tests/packaging
+{% if distro.match('fedora') or distro.match('rocky') or distro.match('opensuse') -%}
+Depends: man
+{%- endif %}

diff --git a/manager/tests/packaging/manpage.sh b/manager/tests/packaging/manpage.sh
new file mode 100755 (executable)
index 0000000..eeab3e4
--- /dev/null
+++ b/manager/tests/packaging/manpage.sh
@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -e
+
+man -w kresd
+man -w kresd.systemd
+man -w kresctl

diff --git a/manager/knot-resolver.service b/systemd/knot-resolver.service.in
similarity index 59%
rename from manager/knot-resolver.service
rename to systemd/knot-resolver.service.in
index 00be7d48e3872346000e34209c49816701e4cbbd..3c8d2477e1ecfd018ef187c542bd76c771175513 100644 (file)
--- a/manager/knot-resolver.service
+++ b/systemd/knot-resolver.service.in
@@ -1,5 +1,10 @@
 [Unit]
 Description=Knot Resolver Manager
+Documentation=man:knot-resolver.systemd(7)
+Wants=network-online.target
+After=network-online.target
+Before=nss-lookup.target
+Wants=nss-lookup.target
 
 [Service]
 Type=notify
@@ -7,6 +12,10 @@ TimeoutStartSec=10s
 ExecStart=/usr/bin/env python3 -m knot_resolver_manager --config=/etc/knot-resolver/config.yml
 KillSignal=SIGINT
 WorkingDirectory=/var/run/knot-resolver/
+User=@user@
+Group=@group@
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_SETPCAP
+AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_SETPCAP
 # See systemd.service(5) for explanation, why we should replace this with a blocking request
 # ExecReload=/usr/bin/env kill -HUP $MAINPID
 

diff --git a/systemd/meson.build b/systemd/meson.build
index 6ca0bac1309623dbddd1fbd3d6213a3aa76fb040..17bad82888444b9994fe35e4e38f1dbec3d41477 100644 (file)
--- a/systemd/meson.build
+++ b/systemd/meson.build
@@ -30,6 +30,12 @@ if systemd_files == 'enabled'
     sources: 'kresd.target',
     install_dir: systemd_unit_dir,
   )
+  manager_service = configure_file(
+    input: 'knot-resolver.service.in',
+    output: 'knot-resolver.service',
+    configuration: systemd_config,
+    install_dir: systemd_unit_dir,
+  )
 
   ## man page
   kresd_systemd_man = configure_file(