Dear Maintainer,

The smbclient(1) manpage contains some multiple entries in the OPTIONS
section regarding the SYNOPSIS list.

Here are the two detected cases:

71:       -m|--max-protocol protocol
72-           This allows the user to select the highest SMB protocol level that smbclient will use to connect to the server. By default this is set to highest available SMB3
and
259:       -m|--max-protocol=MAXPROTOCOL
260-           The value of the parameter (a string) is the highest protocol level that will be supported by the client.

76:       -P|--machine-pass
77-           Make queries to the external server using the machine account of the local server.
and
335:       -P|--machine-pass
336-           Use stored machine account password.

Moreover the entries in the OPTIONS section should be more consistent to the SYNOPSIS
syntax. For instance, SYNOPSIS is:

       smbclient [-M|--message=HOST] [-I|--ip-address=IP] [-E|--stderr] [-L|--list=HOST] [-T|--tar=<c|x>IXFvgbNan] [-D|--directory=DIR] [-b|--send-buffer=BYTES]
        [-t|--timeout=SECONDS] [-p|--port=PORT] [-g|--grepable] [-q|--quiet] [-B|--browse] [-?|--help] [--usage] [-d|--debuglevel=DEBUGLEVEL] [--debug-stdout]
        [-s|--configfile=CONFIGFILE] [--option=name=value] [-l|--log-basename=LOGFILEBASE] [--leak-report] [--leak-report-full] [-R|--name-resolve=NAME-RESOLVE-ORDER]
        [-O|--socket-options=SOCKETOPTIONS] [-m|--max-protocol=MAXPROTOCOL] [-n|--netbiosname=NETBIOSNAME] [--netbios-scope=SCOPE] [-W|--workgroup=WORKGROUP]
        [--realm=REALM] [-U|--user=[DOMAIN/]USERNAME%[PASSWORD]] [-N|--no-pass] [--password=STRING] [--pw-nt-hash] [-A|--authentication-file=FILE] [-P|--machine-pass]
        [--simple-bind-dn=DN] [--use-kerberos=desired|required|off] [--use-krb5-ccache=CCACHE] [--use-winbind-ccache] [--client-protection=sign|encrypt|off] [-V|--version]
        [-c|--command=STRING]

and the entries in OPTIONS are (with the duplicates):
       -M|--message NetBIOS name      <- =HOST
       -p|--port port                 <- =PORT
       -g|--grepable
       -m|--max-protocol protocol     <- duplicated
       -P|--machine-pass              <- duplicated
       -I|--ip-address IP-address     <- =IP
       -E|--stderr
       -L|--list                      <- =HOST
       -b|--send-buffer buffersize    <- =BYTES
       -B|--browse
       -t|--timeout <timeout-seconds> <- =SECONDS
       -T|--tar tar options           <- =<c|x>IXFvgbNan
       -D|--directory initial directory <- =DIR
       -c|--command command string    <- =STRING
       -?|--help
       -d|--debuglevel=DEBUGLEVEL
       -l|--log-basename=logdirectory <- =LOGFILEBASE
       -V|--version
       -R|--name-resolve=NAME-RESOLVE-ORDER
       -O|--socket-options=SOCKETOPTIONS
       -m|--max-protocol=MAXPROTOCOL
       -n|--netbiosname=NETBIOSNAME
       -W|--workgroup=WORKGROUP
       -r|--realm=REALM
       -U|--user=[DOMAIN\]USERNAME[%PASSWORD] <- / or \ ?
       -N|--no-pass
       -A|--authentication-file=filename
       -P|--machine-pass

And as we can see, the SYNOPSIS set is much larger than that of OPTIONS.

Regards,
Patrice

ps: I just used the following command to check: man smbclient | grep -n -A 1 '\-.|'

28.10.2022 10:28, Patrice DUROUX wrote:

Umm.  This is all good. But samba upstream is difficult to deal with.
I definitely don't have enough time/energy to fight there.  If you
do have it, please open bug in bugzilla.samba.org, and/or create a
merge request for in on gitlab.com - maybe this way it will be easier.

This bugreport will most likely stay in the bts forever and uselessly
attract my attention... hwell... :(

Thanks,

/mjt

28.10.2022 10:28, Patrice DUROUX wrote:

samba manpages are generated. And this is interesting.

The first text above comes from docs-xml/manpages/smbclient.1.xml:

                 <term>-m|--max-protocol protocol</term>
                 <listitem><para>This allows the user to select the
                 highest SMB protocol level that smbclient will use to
                 connect to the server. By default this is set to..

And the second text comes from docs-xml/smbdotconf/protocol/clientmaxprotocol.xml:

   <samba:parameter name="client max protocol"
                  context="G"
                  type="enum"
                  function="_client_max_protocol"
                  enumlist="enum_protocol"
                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
   <description>
     <para>The value of the parameter (a string) is the highest
     protocol level that will be supported by the client.</para>
     ...

So it looks like smbclient.1.xml manpage lists *all* options available,
and also includes other files which lists some options which are referenced
by smbclient.1.xml. And it looks like the same applies to other manpages too.

I'm Cc'ing samba-technical@ with this.

Thanks,

/mjt

Thanks Michael!

I have also dig a bit into the samba source.
There are similar duplicates in the smbcacls(1) manpage.

$ rgrep -n "max-protocol" *
docs-xml/build/DTD/samba.entities:559:<!ENTITY cmdline.common.connection.max-protocol '
docs-xml/build/DTD/samba.entities:561:	<term>-m|--max-protocol=MAXPROTOCOL</term>
docs-xml/build/DTD/samba.entities:580:&cmdline.common.connection.max-protocol;
docs-xml/manpages/rpcclient.1.xml:37:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcquotas.1.xml:41:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/winexe.1.xml:37:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcacls.1.xml:51:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcacls.1.xml:182:		<term>-m|--max-protocol PROTOCOL_NAME</term>
docs-xml/manpages/smbcacls.1.xml:190:		a max-protocol of SMB3 is required.
docs-xml/manpages/mdsearch.1.xml:37:      <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/nmblookup.1.xml:43:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbclient.1.xml:46:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbclient.1.xml:193:		<term>-m|--max-protocol protocol</term>
docs-xml/manpages/smbclient.1.xml:201:		a max-protocol of SMB3 is required.
docs-xml/manpages/samba-regedit.8.xml:33:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/net.8.xml:35:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
lib/cmdline/cmdline.c:705:		.longName   = "max-protocol",
source3/selftest/tests.py:508:for options in ["", "--option=clientntlmv2auth=no", "--option=clientusespnego=no", "--option=clientusespnego=no --option=clientntlmv2auth=no", "--option=clientntlmv2auth=no --option=clientlanmanauth=yes --max-protocol=LANMAN2", "--option=clientntlmv2auth=no --option=clientlanmanauth=yes --option=clientmaxprotocol=NT1"]:
source3/utils/smbcquotas.c:627:			.longName   = "max-protocol",
source3/utils/net_help_common.c:67:	d_printf(_("\t-m|--max-protocol=MAXPROTOCOL\t\tSet max protocol level\n"));

I think that samba.dtd contents some common shared entries and both
smbclient.1.xml and smbcacls.1.xml should not have their own
<varlistentry><term>...</term></varlistentry>.

I did not try to check by removing them.

More annoying is small discrepancy regarding the '-U|--user' option.

$ rgrep -n "\-U|--user" *
docs-xml/build/DTD/samba.entities:591:	<term>-U|--user=[DOMAIN\]USERNAME[&pct;PASSWORD]</term>
docs-xml/manpages/rpcclient.1.xml:42:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbcquotas.1.xml:46:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/winexe.1.xml:42:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg>
docs-xml/manpages/smbcacls.1.xml:56:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/mdsearch.1.xml:42:      <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbclient.1.xml:51:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg>
docs-xml/manpages/samba-regedit.8.xml:38:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbtree.1.xml:34:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/net.8.xml:40:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/pdbedit.8.xml:33:		<arg choice="opt">-U|--user SID=STRING</arg>
source3/utils/net_help_common.c:75:	d_printf(_("\t-U|--user=[DOMAIN/]USERNAME[%%PASSWORD]\tSet the "

The separator to the DOMAIN value (ie. [DOMAIN\] or [DOMAIN/]) and the position
of the pourcent % should be inside the brackets (ie. [%PASSWORD] and not
%[PASSWORD]).

Finally, I found more to say about the documentation versus the output of help
option on the different samba commands.
Let see with what upstream have to say.

To conclude, be free to close this wish.

Regards,
Patrice
that smbclient will use to connect to the server. By default this is set to
highest available SMB3
level that will be supported by the client.
xml/smbdotconf/protocol/clientmaxprotocol.xml:
of the local server.
SYNOPSIS

Can we move this discussion to an upstream bug, and even better propose
a patch per https://wiki.samba.org/index.php/Contribute on GitLab for
Samba master?
There is nothing debian-specific here and it is all going to have to be
solved upstream anyway.
Hard work has been started to have our manpages and even more
importantly code use common elements so that we have consistent
behaviour and consistent documentation, the rough edges just need a
clean up and this would be an awesome contributed patch, as it just
takes time.
Andrew Bartlett
-- 
Andrew Bartlett (he/him)       https://samba.org/~abartlet/Samba Team Member (since 2001) https://samba.orgSamba Team Lead, Catalyst IT   https://catalyst.net.nz/services/samba
Samba Development and Support, Catalyst IT - Expert Open SourceSolutions