smb.conf.5: add clarification how configuration changes reflected by Samba

Users of Linux distributions know to read smb.conf(5) manual page but
apparently not many of them read smbd(8) and winbindd(8) to understand
how changes to smb.conf file are reflected in the running processes.

Add a small section that makes it clear where to find relevant
information. Also correct the information in smbd, nmbd, and winbindd
manual pages.

The interval at which smbd does check for smb.conf changes was increased
from 60 seconds to 180 seconds in 1999 with commit 3db52feb1f3b.

Signed-off-by: Alexander Bokovoy <ab@samba.org>
Reviewed-by: Isaac Boukris <iboukris@samba.org>

Autobuild-User(master): Alexander Bokovoy <ab@samba.org>
Autobuild-Date(master): Tue Oct 20 08:50:13 UTC 2020 on sn-devel-184

4 files changed, 55 insertions, 5 deletions

diff --git a/docs-xml/manpages/nmbd.8.xml b/docs-xml/manpages/nmbd.8.xml
index c145e820770..4ece42f3ca6 100644
--- a/docs-xml/manpages/nmbd.8.xml
+++ b/docs-xml/manpages/nmbd.8.xml
@@ -244,7 +244,15 @@
 	directory (or the <filename>var/locks</filename> directory configured
 	under wherever Samba was configured to install itself). This will also
 	cause <command>nmbd</command> to dump out its server database in
-	the <filename>log.nmb</filename> file.</para>
+	the <filename>log.nmb</filename> file. Additionally, the signal will
+	cause reloading <command>nmbd</command> configuration.</para>
+
+        <para>
+        Instead of sending a SIGHUP signal, a request to dump namelists
+        into the file and reload a configuration file may be sent using
+        <citerefentry><refentrytitle>smbcontrol</refentrytitle>
+       <manvolnum>1</manvolnum></citerefentry> program.
+        </para>
 
 	<para>The debug log level of nmbd may be raised or lowered
 	using <citerefentry><refentrytitle>smbcontrol</refentrytitle>
diff --git a/docs-xml/manpages/smb.conf.5.xml b/docs-xml/manpages/smb.conf.5.xml
index f72833c003f..c4387187ecc 100644
--- a/docs-xml/manpages/smb.conf.5.xml
+++ b/docs-xml/manpages/smb.conf.5.xml
@@ -27,6 +27,36 @@
 	</para>
 </refsect1>
 
+<refsect1>
+	<title>HOW CONFIGURATION CHANGES ARE APPLIED</title>
+
+	<para>
+	The Samba suite includes a number of different programs. Some of them operate in a client mode, others are
+	server daemons that provide various services to its clients. The <filename moreinfo="none">smb.conf
+        </filename> file is processed in the following way:
+        </para>
+
+	<itemizedlist>
+		<listitem><para>
+		The Samba suite's client applications read their configuration only once. Any changes made after start aren't
+		reflected in the context of already running client code.
+		</para></listitem>
+
+		<listitem><para>
+		The Samba suite's server daemons reload their configuration when requested. However, already active connections
+		do not change their configuration. More detailed information can be found in
+		<citerefentry><refentrytitle>smbd</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry>
+		<refentrytitle>winbindd</refentrytitle><manvolnum>8</manvolnum></citerefentry> manual pages.
+                </para></listitem>
+	</itemizedlist>
+
+	<para>
+	To request Samba server daemons to refresh their configuration, please use
+	<citerefentry><refentrytitle>smbcontrol</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility.
+        </para>
+
+</refsect1>
+
 <refsect1 id="FILEFORMATSECT">
 	<title>FILE FORMAT</title>
 
diff --git a/docs-xml/manpages/smbd.8.xml b/docs-xml/manpages/smbd.8.xml
index deba2cad9e2..73d808c70b7 100644
--- a/docs-xml/manpages/smbd.8.xml
+++ b/docs-xml/manpages/smbd.8.xml
@@ -68,11 +68,18 @@
 	the copy of the server for that client terminates.</para>
 
 	<para>The configuration file, and any files that it includes, 
-	are automatically reloaded every minute, if they change.  You 
-	can force a reload by sending a SIGHUP to the server.  Reloading 
+	are automatically reloaded every three minutes, if they change.
+	One can force a reload by sending a SIGHUP to the server. Reloading
 	the configuration file will not affect connections to any service 
 	that is already established.  Either the user will have to 
-	disconnect from the service, or <command>smbd</command> killed and restarted.</para>
+	disconnect from the service, or <command>smbd</command> killed and restarted.
+        </para>
+
+        <para>Instead of sending a SIGHUP signal, a request to reload configuration
+	file may be sent using <citerefentry><refentrytitle>smbcontrol</refentrytitle>
+	<manvolnum>1</manvolnum></citerefentry> program.
+        </para>
+
 </refsect1>
 
 <refsect1>
diff --git a/docs-xml/manpages/winbindd.8.xml b/docs-xml/manpages/winbindd.8.xml
index 71fb248c204..99c00388c20 100644
--- a/docs-xml/manpages/winbindd.8.xml
+++ b/docs-xml/manpages/winbindd.8.xml
@@ -390,7 +390,12 @@ auth  required    /lib/security/pam_unix.so \
 		apply any parameter changes to the running
 		version of winbindd.  This signal also clears any cached
 		user and group information.  The list of other domains trusted
-		by winbindd is also reloaded.  </para></listitem>
+		by winbindd is also reloaded.
+		</para>
+		<para>Instead of sending a SIGHUP signal, a request to reload configuration
+		file may be sent using <citerefentry><refentrytitle>smbcontrol</refentrytitle>
+		<manvolnum>1</manvolnum></citerefentry> program.
+		</para></listitem>
 		</varlistentry>
 
 		<varlistentry>