Usability of 'samba-tool domain provision'

[Rowland Penny]

On 04/05/16 13:40, Alexander Bokovoy wrote:
> On Wed, 04 May 2016, Rowland Penny wrote:
>> On 04/05/16 12:16, Alexander Bokovoy wrote:
>>> On Wed, 04 May 2016, Peter C. Kelly wrote:
>>>> Andreas said:
>>>>
>>>>> This documents issues I
>>>>> found during provisioning. samba-tool is far away from being user friendly.
>>>>> a) It isn't clear what domain is from 'samba-tool domain provison --help'
>>>> I have raised bug 11894, and attached a patch which addresses this
>>>> point as per Rowland's suggested wording.
>>>>
>>>>> b) The --realm option is essential but at the end of the help ...
>>>> The reason that the realm is way down the bottom is that it is under a
>>>> heading "Samba Common Options", along with configFile debuglevel and
>>>> option.
>>>>
>>>> What is currently holding me up from developing the second trivial
>>>> patch is a need for a bit more clarity on how this --help output
>>>> should look.  It seems to me that if the --domain parameter is
>>>> compulsory, then the heading text should say so,
>>>> and that if a realm has to be specified (or read in from an existing
>>>> conf file) then perhaps that should be mentioned in the introductory
>>>> text as well.
>>> It would, perhaps, be good to have it in both categories to avoid
>>> changing common options' help.
>>>
>> It doesn't need to be in both categories, if you do an interactive
>> provision, there is this:
>>
>>              realm = ask("Realm", default)
>>              if realm in (None, ""):
>>                  raise CommandError("No realm set!")
>>
>> If you specify everything with the command, there is this:
>>
>>              realm = sambaopts._lp.get('realm')
>>              if realm is None:
>>                  raise CommandError("No realm set!")
>>
>> So, if you don't provide the 'realm', it refuses to continue and tells you
>> why.
> There is a difference between running the tool and reading the
> documentation. ;) If we can improve expectations by pointing out that
> realm and other options are really not options here but required
> arguments, it would save some time to people who want to automate.
> Manual page for samba-tool is very short on what could be expected from
> the user in specific commands, unfortunately. The help output isn't
> helping too.
>

Well, if you run 'samba-tool domain provision --help', you get this at 
the top:

Usage: samba-tool domain provision [options]

Provision a domain.


There then follows the list of options.

I am sure that 'Provision a domain' can be expanded on, starting with ', 
you must supply the realm name.'

Rowland