systemd: add note about locahost defaults

2 files changed, 27 insertions, 6 deletions

diff --git a/daemon/bindings/net.rst b/daemon/bindings/net.rst
index 5a55181f..bfb536c2 100644
--- a/daemon/bindings/net.rst
+++ b/daemon/bindings/net.rst
@@ -21,7 +21,9 @@ Most notable examples of such systems are CentOS 7 and macOS.
 
 If you're using our packages with systemd with sockets support (not supported
 on CentOS 7), network interfaces are configured using systemd drop-in files.
-Each protocol has its own configuration file:
+
+Each protocol has its own configuration file. *By default, these are configured
+to listen on localhost.*
 
 .. csv-table::
   :header: "**Network protocol**", "**Socket file name**"
@@ -31,7 +33,12 @@ Each protocol has its own configuration file:
   ":ref:`mod-http-doh`","``kresd-doh.socket``"
   ":ref:`Web management <mod-http-built-in-services>`","``kresd-webmgmt.socket``"
 
-To configure kresd to listen on a public interface using the original DNS protocol,
+.. warning:: You MUST NOT repeat the localhost defaults in the following
+   drop-in overrides, otherwise the socket will fail to start with "Address in
+   use" error. To view the entire socket configuration, including any drop-ins,
+   use systemctl cat.
+
+To configure kresd to listen on a **public interface** using the original DNS protocol,
 create a drop-in file:
 
 .. code-block:: bash
diff --git a/systemd/kresd.systemd.7.in b/systemd/kresd.systemd.7.in
index d1f815cd..f7452588 100644
--- a/systemd/kresd.systemd.7.in
+++ b/systemd/kresd.systemd.7.in
@@ -28,7 +28,15 @@ system-kresd.slice
 This manual page describes how to manage \fBkresd\fR using \fBsystemd\fR
 units.
 
-.B Socket activation
+.B QUICKSTART
+
+.nf
+.RS 4n
+\fBsystemctl start kresd@1\fR - single instance of kresd, responding on localhost
+.RE
+.fi
+
+.B SOCKET ACTIVATION
 
 \fBkresd\fR integration with systemd takes advantage of socket activation,
 which enables the daemon to run without super user priviledges or any
@@ -49,9 +57,15 @@ these systemd sockets associated with it:
 .RE
 .fi
 
-.B Configuring network interfaces
+.B CONFIGURING NETWORK INTERFACES
+
+By default, \fBkresd is configured to listen on localhost\fR (see ports above).
+You MUST NOT repeat these defaults in the following drop-in overrides,
+otherwise the socket will fail to start with "Address in use" error. To view
+the entire socket configuration, including any drop-ins, use \fBsystemctl
+cat\fR.
 
-To configure \fBkresd\fR to listen on public interfaces, drop-in files (see
+To configure \fBkresd\fR to listen on \fBpublic interfaces\fR, drop-in files (see
 \fIsystemd.unit\fR(5)) should be used. These can be created with:
 
 .nf
@@ -132,7 +146,7 @@ is unlikely.
 
 For more detailed socket configuration, see \fBsystemd.socket\fR(5).
 
-.B Concurrent daemons
+.B CONCURRENT DAEMONS
 
 \fBkresd\fR daemon can be executed in multiple independent processes, which are
 managed with \fBsystemd\fR via systemd templates (see \fBsystemd.unit\fR(5)).