Skip to contentSkip to conversation

docs: update username= option to drop invalid examples

PATCH Applied Martin Schwenke 2 participants 2 messages Sep 10, 2025 – Jan 6

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: update username= option to drop invalid examples

When hurrying and scanning the documentation, my eye was drawn to the examples ``user%password`` or ``workgroup/user`` and ``workgroup/user%password``, especially because they were rendered in bold in my terminal. I didn't read them in the context of them being deprecated and experienced a non-zero amount of frustration when they didn't work. Given that these no longer work at all, remove them and add clarity.

peace & happiness,
martin

From 036719fde9b55a07831bf015e0e58ed2fbf7bc05 Mon Sep 17 00:00:00 2001
From: Martin Schwenke <[email protected]>
Date: Wed, 10 Sep 2025 19:07:48 +1000
Subject: [PATCH] docs: update username= option to drop invalid examples

When hurrying and scanning the documentation, my eye was drawn to the examples ``user%password`` or ``workgroup/user`` and ``workgroup/user%password``, especially because they were rendered in bold in my terminal. I didn't read them in the context of them being deprecated and experienced a non-zero amount of frustration when they didn't work. Given that these no longer work at all, remove them and add clarity.

---
 mount.cifs.rst | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)
mount.cifs.rst +8 -11
index d489070..936cacb 100644
@@ -57,17 +57,14 @@ username=arg|user=arg
   specifies the username to connect as. If this is not
   given, then the environment variable USER is used.
 
-  Earlier versions of mount.cifs also allowed one to specify the
-  username in a ``user%password`` or ``workgroup/user`` or
-  ``workgroup/user%password`` to allow the password and workgroup to
-  be specified as part of the username. Support for those alternate
-  username formats is now deprecated and should no longer be
-  used. Users should use the discrete ``password=`` and ``domain=`` to
-  specify those values. While some versions of the cifs kernel module
-  accept ``user=`` as an abbreviation for this option, its use can
-  confuse the standard mount program into thinking that this is a
-  non-superuser mount. It is therefore recommended to use the full
-  ``username=`` option name.
+  Users must use the discrete ``password=`` and ``domain=`` options to
+  specify relevant values. Including these in the ``username=`` option
+  is no longer supported.
+
+  While some versions of the cifs kernel module accept ``user=`` as an
+  abbreviation for this option, its use can confuse the standard mount
+  program into thinking that this is a non-superuser mount. It is
+  therefore recommended to use the full ``username=`` option name.
 
 password=arg|pass=arg
   specifies the CIFS password. If this option is not given then the
Signature · 1 line
2.47.3
Applied
#1 lore raw

Merged into cifs-utils for-next

Quoted 11 lines · Martin Schwenke

When hurrying and scanning the documentation, my eye was drawn to the examples ``user%password`` or ``workgroup/user`` and ``workgroup/user%password``, especially because they were rendered in bold in my terminal. I didn't read them in the context of them being deprecated and experienced a non-zero amount of frustration when they didn't work. Given that these no longer work at all, remove them and add clarity.

peace & happiness,
martin

Signature · 3 lines
Thanks,

Steve