From ab26c7b8d14b17744d2387c26865d676815c2d72 Mon Sep 17 00:00:00 2001
From: Andrew Bartlett <abartlet@samba.org>
Date: Tue, 10 Aug 2021 09:13:15 +1200
Subject: [PATCH 1/3] docs: Ensure to rebuild manpages if samba.entities or
 samba.version changes

BUG: https://bugzilla.samba.org/show_bug.cgi?id=14791

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
(cherry picked from commit a363742635c54a6cb19363f4be9d2be2b731a5e6)
---
 buildtools/wafsamba/wafsamba.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/buildtools/wafsamba/wafsamba.py b/buildtools/wafsamba/wafsamba.py
index 4fe9daf160e..0427c90ca80 100644
--- a/buildtools/wafsamba/wafsamba.py
+++ b/buildtools/wafsamba/wafsamba.py
@@ -946,9 +946,13 @@ def SAMBAMANPAGES(bld, manpages, extra_source=None):
     bld.env.SAMBA_CATALOGS = 'file:///etc/xml/catalog file:///usr/local/share/xml/catalog file://' + bld.env.SAMBA_CATALOG
 
     for m in manpages.split():
-        source = m + '.xml'
+        source = [m + '.xml']
         if extra_source is not None:
             source = [source, extra_source]
+        # ${SRC[1]} and ${SRC[2]} are not referenced in the
+        # SAMBA_GENERATOR but trigger the dependency calculation so
+        # ensures that manpages are rebuilt when these change.
+        source += ['build/DTD/samba.entities', 'build/DTD/samba.build.version']
         bld.SAMBA_GENERATOR(m,
                             source=source,
                             target=m,
-- 
2.25.1


From 772f0f4da58e5640a90ff8aa6b006677c6f89160 Mon Sep 17 00:00:00 2001
From: Andrew Bartlett <abartlet@samba.org>
Date: Tue, 10 Aug 2021 09:14:08 +1200
Subject: [PATCH 2/3] docs: Document all the other ways to send a password to
 smbclient et al

This was previously hidden knowlege not easily available to
administrators and end users.

BUG: https://bugzilla.samba.org/show_bug.cgi?id=14791

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>
(cherry picked from commit 9b50d2e52e6c85bc3ab991cd8a4b870aff397bda)
---
 docs-xml/build/DTD/samba.entities | 52 ++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/docs-xml/build/DTD/samba.entities b/docs-xml/build/DTD/samba.entities
index 80e051e7684..beff3cb1f6e 100644
--- a/docs-xml/build/DTD/samba.entities
+++ b/docs-xml/build/DTD/samba.entities
@@ -595,13 +595,16 @@
 		</para>
 
 		<para>
-			If &pct;password is not specified, the user will be
+			If &pct;PASSWORD is not specified, the user will be
 			prompted. The client will first check the
-			<envar>USER</envar> environment variable, then the
-			<envar>LOGNAME</envar> variable and if either exists,
-			the string is uppercased. If these environmental
+			<envar>USER</envar> environment variable
+			(which is also permitted to also contain the
+			password seperated by a &pct;), then the
+			<envar>LOGNAME</envar> variable (which is not
+			permitted to contain a password) and if either exists,
+			the value is used. If these environmental
 			variables are not found, the username
-			<constant>GUEST</constant> is used.
+			found in a Kerberos Credentials cache may be used.
 		</para>
 
 		<para>
@@ -616,9 +619,15 @@
 		</para>
 
 		<para>
-			Be cautious about including passwords in scripts. For
-			security it is better to let the client ask for the
-			password if needed.
+			Be cautious about including passwords in scripts
+			or passing user-supplied values onto the command line. For
+			security it is better to let the Samba client tool ask for the
+			password if needed, or obtain the password once with <command>kinit</command>.
+		</para>
+		<para>
+			While Samba will attempt to scrub the password
+			from the process title (as seen in ps), this
+			is after startup and so is subject to a race.
 		</para>
 	</listitem>
 </varlistentry>
@@ -659,10 +668,31 @@
 			Specify the password on the commandline.
 		</para>
 
+		<para> Be cautious about including passwords in
+			scripts or passing user-supplied values onto
+			the command line. For security it is better to
+			let the Samba client tool ask for the password
+			if needed, or obtain the password once with
+			<command>kinit</command>.
+		</para>
+
+		<para> If --password is not specified,
+		       the tool will check the <envar>PASSWD</envar>
+		       environment variable, followed by <envar>PASSWD_FD</envar>
+		       which is expected to contain an open
+		       file descriptor (FD) number.
+		</para>
+		<para>
+		       Finally it will check <envar>PASSWD_FILE</envar> (containing
+		       a file path to be opened). The file should only
+		       contain the password. Make certain that the
+		       permissions on the file restrict
+		       access from unwanted users!
+		</para>
 		<para>
-			Be cautious about including passwords in scripts. For
-			security it is better to let the client ask for the
-			password if needed.
+			While Samba will attempt to scrub the password
+			from the process title (as seen in ps), this
+			is after startup and so is subject to a race.
 		</para>
 	</listitem>
 </varlistentry>
-- 
2.25.1


From 5cd90ceaba0ed68c3615aa9f9eb7107bd1f8c40a Mon Sep 17 00:00:00 2001
From: Andrew Bartlett <abartlet@samba.org>
Date: Tue, 10 Aug 2021 09:20:45 +1200
Subject: [PATCH 3/3] docs: Avoid duplicate information on USER and PASSWD,
 reference the common section

BUG: https://bugzilla.samba.org/show_bug.cgi?id=14791

Signed-off-by: Andrew Bartlett <abartlet@samba.org>
Reviewed-by: Jeremy Allison <jra@samba.org>

Autobuild-User(master): Jeremy Allison <jra@samba.org>
Autobuild-Date(master): Thu Sep  9 00:52:09 UTC 2021 on sn-devel-184

(cherry picked from commit 18e08c709002506fe217ca6a7a098fcdc00f8c29)
---
 docs-xml/manpages/smbclient.1.xml | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/docs-xml/manpages/smbclient.1.xml b/docs-xml/manpages/smbclient.1.xml
index 0de5b8a0e00..48ba59525d6 100644
--- a/docs-xml/manpages/smbclient.1.xml
+++ b/docs-xml/manpages/smbclient.1.xml
@@ -1193,16 +1193,10 @@
 <refsect1>
 	<title>ENVIRONMENT VARIABLES</title>
 
-	<para>The variable <envar>USER</envar> may contain the
-	username of the person	using the client. This information is
-	used only if the protocol  level is high enough to support
-	session-level passwords.</para>
-
-
-	<para>The variable <envar>PASSWD</envar> may contain
-	the password of the person using the client.  This information is
-	used only if the protocol level is high enough to support
-	session-level passwords. </para>
+	<para>See the <command>--user</command> and
+	<command>--password</command> options for details on ways to
+	specify a username and password via an environment variable.
+	</para>
 </refsect1>
 
 
-- 
2.25.1