#3060 [RFE] Confusing ipa tool online help organization
Closed: Fixed None Opened 6 years ago by nkondras.

There are several problems with the "ipa" tool online help.

By "online help" I mean usage messages produced by running the tool itself.
By "man pages" I mean manual pages accessed using "man" command.

Both the man page and the online help specify COMMAND as required. However,
running ipa without arguments doesn't produce an error. Either COMMAND should
be specified as optional maybe with a description of what ipa does when it's
not specified, or, better, ipa should produce an error in this case, saying
that the command is not specified, followed by the usage message, all output to
stderr, followed by an appropriate exit status.

This part of the "ipa" output is very confusing:

Built-in commands:
Help subtopics:
  console         Start the IPA interactive Python console.
Help subtopics:
  help            Display help for a command or topic.
Help subtopics:
  show-mappings   Show mapping of LDAP attributes to command-line option.

Help topics:

What are "Built-in commands"? Why there are three "Help subtopics:" headers?
Why do they come before "Help topics:" header?

Then, it is not apparent what the user is supposed to do with "Help topics".
I.e. there is no description for the "ipa help <command>" syntax there.

At a first glance, it is easy to mistake the list of help topics for the list
of commands. The next attempted command to retrieve online help, for example,
quite naturally, "ipa user --help" produces this:

ipa: ERROR: unknown command 'user'

But, in contradiction, "ipa user" produces a usage message with exit status
indicating success.

The specific command usage messages are also unsuitable. They include
introductory texts more appropriate for man pages than quick online help. Online
help is consulted often, but introductory texts are read only once or twice.
Those take too much space in the terminal output, pushing previous console
output, which the user often needs, too far above.

Having examples in the online help is more useful than introductory texts, but
doesn't justify impairing user's ability to view previous console output. A
couple of lines would be fine, but probably no more.

The CLI users have come to expect more general help information closer to the
top of the output. However, the most general information - the command list -
is output at the bottom. This is done, apparently, to have it closer to the
prompt after running the command, because otherwise it would be pushed too far
above by the other output, i.e. the introductory text and examples. Considering
that those are unnecessary, at least in present amount, the order could be
reversed.

All-in-all, a good example to follow would be git online help organization with
a few exceptions. Namely, "--help" option and "ipa help <command>" shouldn't
invoke man pages, because this is non-standard, thus unexpected and breaks the
user's focus.

This also means, that "ipa <command-prefix>" syntax, as in "ipa user",
shouldn't be accepted, but "ipa help <command-prefix>", or "man ipa
<command-prefix>" should be.

Man pages could also be organized in a manner similar to git man pages. I.e.
the main man page listing all the commands and separate man pages for every
command.

The online help shouldn't substitute man pages - it is there for a quick lookup
as a cheat sheet. A cheat sheet should be accessible with the least effort and
the least interference.


This is all nice feedback but we are not going to redesign the whole thing. It is what it is. If you have any specific suggestions of how to make it better without breaking the ABI please list them here.

For now I recommend to put this ticket into the Deferred bucket.

This doesn't require changing the interface apart from the interface used to retrieve online help. And even that not by much. I will prepare description of specific interface design on Monday.

I will let the developers speak here but a lot of thought and effort have been invested into the online help. It is all driven by the main plugin framework and it is not easy to change.

Also any change to the interface is an ABI change.
That was a design decision to follow the: ipa help <command> pattern.
Think about help as a specific top level command as any other command.

It was a conscious decision and I do not see a value in changing it. AFAIR it is even documented in the man page, but I am not sure about that. If it is not may be this is what we need to do to make it clearer.

I am definitely against any redesign here. We can change text and formatting of the online help and man pages but we will not change the interface.

Replying to [comment:3 dpal]:

I will let the developers speak here but a lot of thought and effort have
been invested into the online help. It is all driven by the main plugin
framework and it is not easy to change.

Please let me describe specifically what I propose to change and we'll see if
it's possible and if it's worth it. I hope it's not that hard.

Also any change to the interface is an ABI change.

I assume you wanted to say that any interface change may affect users and break
something. I'd say "ABI" usage here is misplaced. ABI is "Application Binary
Interface" and CLI definitely isn't one.

I agree that CLI should be changed carefully, especially in an already widely
used product. However, the changes I propose are minimal and the affected
interfaces are most likely not used for automation.

That was a design decision to follow the: ipa help <command> pattern.
Think about help as a specific top level command as any other command.

Yes, it is fine and I have nothing against it.

It was a conscious decision and I do not see a value in changing it. AFAIR it
is even documented in the man page, but I am not sure about that. If it is
not may be this is what we need to do to make it clearer.

I am definitely against any redesign here. We can change text and formatting
of the online help and man pages but we will not change the interface.

First of all, I've changed my opinion on help topics, i.e. the output of "ipa
help <topic>" commands. I was confusing commands and topics, not in the least
because of the confusing help messages.

However, please see my proposal to change other things below.

Change the ipa -h/--help output

The current output has several problems:

  • doesn't mention COMMAND argument and command options,
  • doesn't distinguish global and command options,
  • doesn't mention what the program does,
  • the description of -h/--help doesn't start with a capital:
  • requires invocation of "ipa help commands", which produces a huge list, to
    find out even most often used commands:

    $ ipa --help
    Usage: ipa [options]

    Options:
    -h, --help show this help message and exit
    -e KEY=VAL Set environment variable KEY to VAL
    -c FILE Load configuration from FILE
    -d, --debug Produce full debuging output
    --delegate Delegate the TGT to the IPA server
    -v, --verbose Produce more verbose output. A second -v displays the
    XML-RPC request
    -a, --prompt-all Prompt for ALL values (even if optional)
    -n, --no-prompt Prompt for NO values (even if required)
    -f, --no-fallback Only use the server configured in /etc/ipa/default.conf

    Available help topics:
    ipa help topics

    Available commands:
    ipa help commands

Instead, output something like this:

$ ipa --help
Usage: ipa [global-options] COMMAND [command-options]
Manage IPA domain.

Global options:
  -h, --help         Show this help message and exit
  -e KEY=VAL         Set environment variable KEY to VAL
  -c FILE            Load configuration from FILE
  -d, --debug        Produce full debuging output
  --delegate         Delegate the TGT to the IPA server
  -v, --verbose      Produce more verbose output. A second -v displays the
                     XML-RPC request
  -a, --prompt-all   Prompt for ALL values (even if optional)
  -n, --no-prompt    Prompt for NO values (even if required)
  -f, --no-fallback  Only use the server configured in /etc/ipa/default.conf

Often used commands:
  help               Display help for a command or topic.
  user-add           Add a new user.
  user-del           Delete a user.
  user-show          Display information about a user.
  host-add           Add a new host.
  host-del           Delete a host.
  host-show          Display information about a host.
  console            Start the IPA interactive Python console.

See "ipa help topics" for available help topics.
See "ipa help <TOPIC>" for more information on a specific topic.
See "ipa help commands" for the full list of commands.
See "ipa help <COMMAND>" for more information on a specific command.

The tool description in the second line and the contents of the "often used
commands" list are just examples.

Change the result of executing "ipa"

Current result is identical to "ipa help", which is wrong, because it violates
the syntax described in the resulting output itself:

$ ipa
Usage: ipa [global-options] COMMAND ...

Built-in commands:
Help subtopics:
  console         Start the IPA interactive Python console.
Help subtopics:
  help            Display help for a command or topic.
Help subtopics:
  show-mappings   Show mapping of LDAP attributes to command-line option.

Help topics:
  automember      Auto Membership Rule.
  automount       Automount
  cert            IPA certificate operations
  config          Server configuration
  delegation      Group to Group Delegation
  dns             Domain Name System (DNS)
  group           Groups of users
  hbac            Host-based access control commands
  hbactest        Simulate use of Host-based access controls
  host            Hosts/Machines
  hostgroup       Groups of hosts.
  krbtpolicy      Kerberos ticket policy
  migration       Migration to IPA
  misc            Misc plug-ins
  netgroup        Netgroups
  passwd          Set a user's password
  permission      Permissions
  ping            Ping the remote IPA server to ensure it is running.
  pkinit          Kerberos pkinit options
  privilege       Privileges
  pwpolicy        Password policy
  range           Manage ID ranges
  role            Roles
  selfservice     Self-service Permissions
  selinuxusermap  SELinux User Mapping
  service         Services
  sudo            commands for controlling sudo configuration
  trust           Manage trust relationship between realms
  user            Users

Try `ipa --help` for a list of global options.

Instead, produce an error message telling COMMAND is missing, followed by the
-h/--help output (as proposed above), all done to stderr. Exit with non-zero
exit status:

$ ipa
ipa: ERROR: command not specified
Usage: ipa [global-options] COMMAND [command-options]
Manage IPA domain.

Global options:
  -h, --help         Show this help message and exit
  -e KEY=VAL         Set environment variable KEY to VAL
  -c FILE            Load configuration from FILE
  -d, --debug        Produce full debuging output
  --delegate         Delegate the TGT to the IPA server
  -v, --verbose      Produce more verbose output. A second -v displays the
                     XML-RPC request
  -a, --prompt-all   Prompt for ALL values (even if optional)
  -n, --no-prompt    Prompt for NO values (even if required)
  -f, --no-fallback  Only use the server configured in /etc/ipa/default.conf

Often used commands:
  help               Display help for a command or topic.
  user-add           Add a new user.
  user-del           Delete a user.
  user-show          Display information about a user.
  host-add           Add a new host.
  host-del           Delete a host.
  host-show          Display information about a host.
  console            Start the IPA interactive Python console.

See "ipa help topics" for available help topics.
See "ipa help <TOPIC>" for more information on a specific topic.
See "ipa help commands" for the full list of commands.
See "ipa help <COMMAND>" for more information on a specific command.

Remove support for "ipa <topic>" invocation syntax

Current result is successful exit status and, "ipa help <topic>" output, like
this:

$ ipa pkinit
Kerberos pkinit options

Enable or disable anonymous pkinit using the principal
WELLKNOWN/ANONYMOUS@REALM. The server must have been installed with
pkinit support.

EXAMPLES:

 Enable anonymous pkinit:
  ipa pkinit-anonymous enable

 Disable anonymous pkinit:
  ipa pkinit-anonymous disable

For more information on anonymous pkinit see:

http://k5wiki.kerberos.org/wiki/Projects/Anonymous_pkinit

Topic commands:
  pkinit-anonymous  Enable or Disable Anonymous PKINIT.

Instead, produce an error and --help output to stderr, exit with non-zero exit status:

$ ipa pkinit
ipa: ERROR: unknown command 'pkinit'
Usage: ipa [global-options] COMMAND [command-options]
Manage IPA domain.

Global options:
  -h, --help         Show this help message and exit
  -e KEY=VAL         Set environment variable KEY to VAL
  -c FILE            Load configuration from FILE
  -d, --debug        Produce full debuging output
  --delegate         Delegate the TGT to the IPA server
  -v, --verbose      Produce more verbose output. A second -v displays the
                     XML-RPC request
  -a, --prompt-all   Prompt for ALL values (even if optional)
  -n, --no-prompt    Prompt for NO values (even if required)
  -f, --no-fallback  Only use the server configured in /etc/ipa/default.conf

Often used commands:
  help               Display help for a command or topic.
  user-add           Add a new user.
  user-del           Delete a user.
  user-show          Display information about a user.
  host-add           Add a new host.
  host-del           Delete a host.
  host-show          Display information about a host.
  console            Start the IPA interactive Python console.

See "ipa help topics" for available help topics.
See "ipa help <TOPIC>" for more information on a specific topic.
See "ipa help commands" for the full list of commands.
See "ipa help <COMMAND>" for more information on a specific command.

Alternative: add help topics to the command list

Alternatively, add help topics to the list of commands (i.e. "ipa help
commands" output), like this:

user                             Output help on user management commands.
user-add                         Add a new user.
user-del                         Delete a user.

Fix error reporting for option usage with such commands. I.e. instead of:

$ ipa user --help
ipa: ERROR: unknown command 'user'

Do this:

$ ipa user --help
ipa: ERROR: no such option: --foo

However, this would still be confusing in case of typos. For example, a user
might have typed "ipa user" instead of "ipa user-mod" in a script and got a
succesful exit status. It is better to produce an error in such case.

Also, this is contradictory. If "user" is a valid command, then "ipa help user"
should produce help message on that command, i.e. its options, etc., and
not a help topic. Note how the option usage error above isn't followed by this
command usage message.

So, I would definitely vote for removing "ipa <topic>" syntax altogether.

Change "ipa help topics" output

Current output is mixed with irrelevant and confusing information, making it
harder to read:

$ ipa help topics
Usage: ipa [global-options] COMMAND ...

Built-in commands:
Help subtopics:
  console         Start the IPA interactive Python console.
Help subtopics:
  help            Display help for a command or topic.
Help subtopics:
  show-mappings   Show mapping of LDAP attributes to command-line option.

Help topics:
  automember      Auto Membership Rule.
  automount       Automount
  cert            IPA certificate operations
  config          Server configuration
  delegation      Group to Group Delegation
  dns             Domain Name System (DNS)
  group           Groups of users
  hbac            Host-based access control commands
  hbactest        Simulate use of Host-based access controls
  host            Hosts/Machines
  hostgroup       Groups of hosts.
  krbtpolicy      Kerberos ticket policy
  migration       Migration to IPA
  misc            Misc plug-ins
  netgroup        Netgroups
  passwd          Set a user's password
  permission      Permissions
  ping            Ping the remote IPA server to ensure it is running.
  pkinit          Kerberos pkinit options
  privilege       Privileges
  pwpolicy        Password policy
  range           Manage ID ranges
  role            Roles
  selfservice     Self-service Permissions
  selinuxusermap  SELinux User Mapping
  service         Services
  sudo            commands for controlling sudo configuration
  trust           Manage trust relationship between realms
  user            Users

Try `ipa --help` for a list of global options.

This is apparently done so the output of "ipa help" makes more sense, which is
abuse of the purpose. See also below.

Instead, output just the help topic table, the same way as it is done for "ipa
help commands":

$ ipa help topics
automember      Auto Membership Rule.
automount       Automount
cert            IPA certificate operations
config          Server configuration
delegation      Group to Group Delegation
dns             Domain Name System (DNS)
group           Groups of users
hbac            Host-based access control commands
hbactest        Simulate use of Host-based access controls
host            Hosts/Machines
hostgroup       Groups of hosts.
krbtpolicy      Kerberos ticket policy
migration       Migration to IPA
misc            Misc plug-ins
netgroup        Netgroups
passwd          Set a user's password
permission      Permissions
ping            Ping the remote IPA server to ensure it is running.
pkinit          Kerberos pkinit options
privilege       Privileges
pwpolicy        Password policy
range           Manage ID ranges
role            Roles
selfservice     Self-service Permissions
selinuxusermap  SELinux User Mapping
service         Services
sudo            commands for controlling sudo configuration
trust           Manage trust relationship between realms
user            Users

Change the result of executing "ipa help"

Current result is identical to "ipa help topics", the latter being "augmented"
to be suitable for both purposes. As a result, it isn't very suitable for
either.

The output should be short introduction to the tool and the help system
instead. Something like this:

$ ipa help
ipa - Manage IPA domain.

See "ipa --help" for general usage.
See "ipa help --help" for "help" command usage.
See "ipa help topics" for the list of help topics.
See "ipa help commands" for the list of commands.

This output could also contain a list of most often used commands and help
topics.

Add command description to the "ipa <command> -h/--help" output

The current "ipa <command> -h/--help" output doesn't mention the purpose of the
tool, only usage, for example:

$ ipa pkinit-anonymous --help
Usage: ipa [global-options] pkinit-anonymous ACTION [options]

Positional arguments:
  ACTION      <action>

Options:
  -h, --help  show this help message and exit

Add tool description after the "Usage:" line, the one used in the "ipa help
commands" output, like this:

$ ipa pkinit-anonymous --help
Usage: ipa [global-options] pkinit-anonymous ACTION [options]
Enable or Disable Anonymous PKINIT.

Positional arguments:
  ACTION      <action>

Options:
  -h, --help  show this help message and exit

Closing remarks

Thank you for reading through this long proposal. I hope at least some of the
changes could be implemented. Maybe this bug should be split into several bugs
to simplify handling.

I have objection to current 'ipa dnsrecord-mod -h' behaviour:

# ipa dnsrecord-mod -h
Usage: ipa [global-options] dnsrecord-mod DNSZONE NAME [options]

Positional arguments:
  DNSZONE               Zone name
  NAME                  Record name

Options:
  -h, --help            show this help message and exit
  --ttl=INT             Time to live
  --class=['IN', 'CS', 'CH', 'HS']
                        DNS class

There is no clear pointer to 'ipa help dns' command. At least this pointer + sentence or two about this particular command would be useful.

CLI specific, no UXD input needed

master: [[br]]
614082e [[br]]
abe26d5 [[br]]
de1c4ee [[br]]
6ac0e9b [[br]]
5ee2216 [[br]]
1e2437e [[br]]
5f5b4c3 [[br]]

ipa-3-1: [[br]]
991f471[[br]]
bd8d4ac[[br]]
9da7d1a[[br]]
640c255[[br]]
bfb310f[[br]]
6cb8148[[br]]
56659f3[[br]]

Metadata Update from @nkondras:
- Issue assigned to pviktori
- Issue set to the milestone: FreeIPA 3.2 - 2013/02

2 years ago

Login to comment on this ticket.

Metadata