Bug 546583

moving this bz to the current freeradius2 package because these will not be fixed for the old 1.1.3 version, however some things have changed

radrelay is now deprecated

radtest now has -d documented in --help

radwho -h option not in option list for getopt, should print usage

radiusd issues now resolved

check-radiusd-config is no longer installed

otherwise the remaining issues in comment #1 are still in effect as far as I can tell after a quick review. Will edit the list in comment #1 so it applies to freeradius2 in the next comment.

Description of problem:
Executables from freeradius package have incomplete usage help and manpages

/usr/bin/radeapclient
---------------------
most of the program options (-c,-r,-t,-S,-q,-s,-v) are not documented in
manpage, option "-i" has different explanation in radeapclient --help and
manpage, option "-y" is mentioned only in manpage.

/usr/bin/radlast
----------------
program options -R,-n,-num,-o,-t,-x are not documented in manpage

/usr/bin/radsqlrelay
--------------------
program options -?,-P,-f are not documented in manpage

/usr/bin/radwho
---------------
-h option not in option list for getopt, should print usage

/usr/bin/radzap
---------------
option -x not documented in manpage

Missing man pages
-----------------
No manual entry for checkrad
No manual entry for radconf2xml
No manual entry for radcrypt
No manual entry for radsniff
No manual entry for rlm_dbm_cat
No manual entry for rlm_dbm_parser
No manual entry for smbencrypt

Entered as upstream bug
https://bugs.freeradius.org/bugzilla/show_bug.cgi?id=154

Created attachment 523715 [details]
Document all command args & add missing man pages

Note: This patch has been submitted upstream. It is expected to be in the next release, 2.1.12 which is the upstream release targeted for the RHEL 5.8 rebase. Therefore it is expected we will not need to use this patch in our RPM, it should be in the upstream tarball.

-------------------------------------------------------------------------------

Go through every installed command and verify:
  * There exists a man page for the command, if not create one
  * For every command line arg in each command:
    - Assure the arg appears in the synopis section of the man page
    - Assure the arg is documented in the options section of the man page
    - Assure the arg is documented in the "usage" emitted by the command

In addition to the above this patch also does:

* Clean up captitalization & the use of terminating periods.
* Removed superfluous unused l option from the getopt format string
  of radwho
* Remove rlm_ippool_tool.pod, superseded by rlm_ippool_tool.8 man page

The follow new man pages were added:

man/man1/smbencrypt.1
man/man5/checkrad.5
man/man5/rlm_dbm_cat.5
man/man5/rlm_dbm_parse.5
man/man8/radconf2xml.8
man/man8/radcrypt.8
man/man8/radsniff.8
man/man8/rlm_ippool_tool.8

If I'm reading this correctly you discovered two issues:

1) typo in the man page for rlm_dbm_parser (man page actually installed as rlm_dbm_parse)

2) no command line args listed in the man page for radlast. The radlast script doesn't actually parse any command line args. In fact it doesn't do much at all except call /usr/bin/last on radwtmp and passing any additional arguments to /usr/bin/last. This is clearly documented in the man page. Does this mean we need to copy the contents of the /usr/bin/last man page into the radlast man page? I don't think that's a good idea, /usr/bin/last may be different on different systems (including non-linux that upstream supports). I think it's fine to just reference the /usr/bin/last man page as is currently done.

What would you like to do? I can fix the typo on rlm_dbm_parse name and respin the packages, but it's not clear to me this is an issue worth consuming QE time on with new packages, but I'm happy to do it. I'll also get upstream to fix the typo.

I'm not inclined to fix issue 2 because I don't see it as an actual problem, I more inclined to believe it's a problem with the test but I'm open to an alternative interpretation.

Let me know what you would like me to do.

Hi John,
I think we should fix the man-typo issue. I'm OK with statement of "unfixed" second issue. I believe it was reported after some summarize testing and not all scripts need to have man pages (for example some helper scripts which aren't for standalone use, etc...)

I prepared a fix but I can't check it in because only blockers are allowed at this point. IMHO having the rlm_dbm_parer man page spelled as rlm_dbm_parse is not a blocker.

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2012-0196.html