Improved cmdline UX in upcoming Samba 4.15

To the newcomer, Samba’s command line user interface appears to be a haphazard jumble of scripts and binaries with options and design principles that fade in and out of use according to some esoteric pattern.

Douglas Bagnall

The initial quote is from the SambaXP talk What should we do with our user interface? in 2019. Douglas wrote that nobody can fix it as experts are locked-in, newbies are baffled and old options can’t be dropped. Since then things have changed. I’ve succeeded to do the impossible, rewrite the command line user interface.

This is part of an effort to support FIPS mode with Samba. For this the client needs to be able have certain defaults set when the machine is set to FIPS mode. But lets first look at what the issues where and how I addressed them.

What were the problems?


$ smbclient --help | grep '\-k'                                
  -k, --kerberos                 Use kerberos 

$ ldbsearch --help | grep '\-k'
  -k, --kerberos=STRING          Use Kerberos, -k [yes|no]

We have -k and `-k yes`. Same option with and without an argument.


$ ldbedit --help | grep '\-e'
 -e, --editor=PROGRAM            external editor
 -e, --encrypt                   Encrypt connection for privacy

Will I enable encryption or will it open an editor, or both?

$ ldbsearch --help | grep '\-S'
 -S, --sorted                   sort attributes
 -S, --sign                     Sign connection to prevent
 -S, --signing=on|off|required  Set the client signing state
$ ldbsearch --help | grep '\-s'
 -s, --scope=SCOPE              search scope
 -s, --configfile=CONFIGFILE    Use alternative configuration

Will I set the scope or provide a config file with `-s`? I want to set the scope, lets use the long option.

$ ldbsearch --help | grep '\-scope'
 -s, --scope=SCOPE              search scope
 -i, --scope=SCOPE              Use this Netbios scope

Those are just a few examples but I think you see the problems. I could go on with logging to stderr or stdout. You never know where log messages are ending up.

To address all the issues we run into something called the “Backwards compatibility dilemma”:

Fixing consistency across tools will create new problems!

  • We need to introduce new options
  • The complexity might increase
  • We will certainly break scripts of our users

How did we solve the issues?

For tools written in C the command line parser has been rewritten. There were two different implementation and there is only one now! The parser uses the client credentials API for all tools now. This means that all tools behave the same now.

New important common options

--use-kerberos=desired|required|off  Use Kerberos authentication
--use-krb5-ccache=CCACHE             Credentials cache location for Kerberos

For Kerberos there are two options available and they have new names. The -k option is deprecated but still works for a grace period. It will be removed in on of the following Samba relases!

A corresponding smb.conf option has been added: client use kerberos = desired|required|off
This allows you to change the default and in FIPS mode it will be forced to be set to required.

   Configure used protection for client connections

There is a new option to select signing or encryption of the connection. It also doesn’t matter if it is an SMB or RPC connection. It will do the right thing for you 🙂

Corresponding smb.conf option: client protection = sign|encrypt|off|default


All tools and daemons log to stderr by default now! This can be changed using the --debug-stdout option.

Sanity check

The new command line parser comes with a sanity checker. This makes sure that a developer will not introduce duplicate options, whether long or short!


The manpage of all tools and daemons have been changed accordingly to reflect the new options. Feel free to open bugs if you find documentation issues or even better, send patches!

The new implementation should make much more sense and developers have tools to avoid mistakes now. Samba 4.15rc1 has just been released. Samba 4.15 is expected to be released in September 2021.

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *