Note: This bug is displayed in read-only format because the product is no longer active in Red Hat Bugzilla.

RHEL Engineering is moving the tracking of its product development work on RHEL 6 through RHEL 9 to Red Hat Jira (issues.redhat.com). If you're a Red Hat customer, please continue to file support cases via the Red Hat customer portal. If you're not, please head to the "RHEL project" in Red Hat Jira and file new tickets here. Individual Bugzilla bugs in the statuses "NEW", "ASSIGNED", and "POST" are being migrated throughout September 2023. Bugs of Red Hat partners with an assigned Engineering Partner Manager (EPM) are migrated in late September as per pre-agreed dates. Bugs against components "kernel", "kernel-rt", and "kpatch" are only migrated if still in "NEW" or "ASSIGNED". If you cannot log in to RH Jira, please consult article #7032570. That failing, please send an e-mail to the RH Jira admins at rh-issues@redhat.com to troubleshoot your issue as a user management inquiry. The email creates a ServiceNow ticket with Red Hat. Individual Bugzilla bugs that are migrated will be moved to status "CLOSED", resolution "MIGRATED", and set with "MigratedToJIRA" in "Keywords". The link to the successor Jira issue will be found under "Links", have a little "two-footprint" icon next to it, and direct you to the "RHEL project" in Red Hat Jira (issue links are of type "https://issues.redhat.com/browse/RHEL-XXXX", where "X" is a digit). This same link will be available in a blue banner at the top of the page informing you that that bug has been migrated.

Bug 910545

Summary:	Confusing ipa tool online help organization
Product:	Red Hat Enterprise Linux 7	Reporter:	Namita Soman <nsoman>
Component:	ipa	Assignee:	Rob Crittenden <rcritten>
Status:	CLOSED CURRENTRELEASE	QA Contact:	IDM QE LIST <seceng-idm-qe-list>
Severity:	unspecified	Docs Contact:
Priority:	medium
Version:	7.0	CC:	mgregg, mkosek, rcritten
Target Milestone:	rc
Target Release:	---
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:	ipa-3.2.1-1.el7	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2014-06-13 11:43:59 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Namita Soman 2013-02-12 19:55:07 UTC

This bug is created as a clone of upstream ticket:
https://fedorahosted.org/freeipa/ticket/3060

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.

Comment 1 Rob Crittenden 2013-02-18 18:25:36 UTC

fixed upstream:

master:
614082e6a6ba025583ce24a2cce94133997925d7
abe26d55c8f43e3a213fe831df7f0536d0600288
de1c4eeae2f3439c1550f9627f45adb4586fa83c
6ac0e9b90f14beba5e5a8857c358a292e218cd49
5ee2216f4973645f18f0ed8eac3c874d81e044ab
1e2437ece1f5d645ab5ab12628021798bb7b9e1a
5f5b4c3e5eec96821411685c7d9a80d85c15af07

ipa-3-1:
991f4719e06ef00409a0270e171c04f5b0e4e41b
bd8d4ac043ae179bc40e8151c3c2676fd30e7bb5
9da7d1a3e41be1307c183c4fbd944aa2b25512b8
640c2550c3a5627f6823494b3129c8394a9024c9
bfb310f05717ef659cee2374b17e7537930cd500
6cb81489bf3a8d386be7f3311c33d3baa846d702
56659f36794348e75fb23e8c892f19fd95d01571

master:
8fcc8bc8d50d266b050c136de7a441d59e363d1b
f16c100f1e72e8afbe26e12e7d236d3ef60f4433

ipa-3-1:
36bfda80717c09929a15147814f6e5ceea4eb60b
a4b54aff311db67b832462b068a299dd73e06101

The fixes include:

- Kerberos ticket not required to obtain help
- Errors are output on stderr
- ipa -h matches ipa help
- ipa COMMAND --help matches ipa help COMMAND
- ipa help prints help for the command, not all the commands

Comment 4 Michael Gregg 2014-01-02 22:34:01 UTC

This looks mostly resolved with one exception. 

cli parsing still seems to make the --help(or -h) option position dependant. 

works: ipa --help user 

Does not work: ipa user --help

If this is expected, I think I can this ticket as verified.

Comment 5 Rob Crittenden 2014-01-02 23:12:02 UTC

It isn't really position-dependent, it is topic help vs command help.

ipa help <topic> or ipa --help <topic> can be used for the top-level topics like user, group, etc.

ipa <command> --help can provide command-specific help, like for user-add, group-find, etc.

But there is no ipa <topic> anything.

Comment 6 Martin Kosek 2014-01-03 13:26:05 UTC

Right, moving back to ON_QA.

Comment 7 Namita Soman 2014-01-27 16:24:22 UTC

Verified using ipa-server-3.3.3-13.el7.x86_64

Test automation output:
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-001 :: verify help for ipa
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   LOG    ] :: Executing: ipa > /tmp/tmpout.ipaserverinstall_BZ910545.out  2>&1
:: [   PASS   ] :: verify error when running the command ipa with no help (Expected 2, got 2)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'Error: Command not specified' 
:: [   PASS   ] :: Running 'ipa help > /tmp/tmpout.ipaserverinstall_BZ910545.out' (Expected 0, got 0)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'See "ipa help topics" for available help topics.' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'See "ipa help <TOPIC>" for more information on a specific topic.' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'See "ipa help commands" for the full list of commands.' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'See "ipa <COMMAND> --help" for more information on a specific command.' 
:: [   PASS   ] :: Running 'ipa --help' (Expected 0, got 0)
:: [   LOG    ] :: Duration: 3s
:: [   LOG    ] :: Assertions: 8 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-001 :: verify help for ipa

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-002 :: verify help for ipa topic
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   PASS   ] :: Running 'ipa help topics | wc -l > /tmp/tmpout.ipaserverinstall_BZ910545.out' (Expected 0, got 0)
:: [   LOG    ] :: Verifying that 29 topics are listed...
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain '29' 
:: [   LOG    ] :: Duration: 1s
:: [   LOG    ] :: Assertions: 2 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-002 :: verify help for ipa topic

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-003 :: verify help for ipa command
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   PASS   ] :: Running 'ipa help commands | wc -l > /tmp/tmpout.ipaserverinstall_BZ910545.out' (Expected 0, got 0)
:: [   LOG    ] ::  Verifying that 235 commands are listed....
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain '235' 
:: [   LOG    ] :: Duration: 1s
:: [   LOG    ] :: Assertions: 2 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-003 :: verify help for ipa command

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-004 :: verify help for ipa command when using a topic
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   LOG    ] :: Executing: ipa trust > /tmp/tmpout.ipaserverinstall_BZ910545.out  2>&1
:: [   PASS   ] :: verify help for ipa command when using a topic will provide topic info but give an error (Expected 1, got 1)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'Manage trust relationship between IPA and Active Directory domains.' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'ipa: ERROR: unknown command 'trust'' 
:: [   LOG    ] :: Duration: 1s
:: [   LOG    ] :: Assertions: 3 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-004 :: verify help for ipa command when using a topic

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-005 :: verify exit status for ipa command
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   LOG    ] :: Executing: ipa trust help > /tmp/tmpout.ipaserverinstall_BZ910545.out  2>&1
:: [   PASS   ] :: verify exit status for ipa command will not provide topic info and give an error (Expected 1, got 1)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should not contain 'Manage trust relationship between IPA and Active Directory domains.' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'ipa: ERROR: unknown command 'trust'' 
:: [   LOG    ] :: Duration: 1s
:: [   LOG    ] :: Assertions: 3 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-005 :: verify exit status for ipa command

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
:: [   LOG    ] :: BZ910545 ipa-help-006 :: verify help when command and topic are same
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

:: [   PASS   ] :: Running 'ipa passwd --help > /tmp/tmpout.ipaserverinstall_BZ910545.out' (Expected 0, got 0)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should not contain 'EXAMPLES' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'Options' 
:: [   PASS   ] :: Running 'ipa help passwd > /tmp/tmpout.ipaserverinstall_BZ910545.out' (Expected 0, got 0)
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should not contain 'Options' 
:: [   PASS   ] :: File '/tmp/tmpout.ipaserverinstall_BZ910545.out' should contain 'EXAMPLES' 
:: [   LOG    ] :: Duration: 2s
:: [   LOG    ] :: Assertions: 6 good, 0 bad
:: [   PASS   ] :: RESULT: BZ910545 ipa-help-006 :: verify help when command and topic are same

Comment 8 Ludek Smid 2014-06-13 11:43:59 UTC

This request was resolved in Red Hat Enterprise Linux 7.0.

Contact your manager or support representative in case you have further questions about the request.