Bug 600935 - rpm man page is incomplete not including things like --setperms --setugids and other options from it's --help displayed options
Summary: rpm man page is incomplete not including things like --setperms --setugids an...
Alias: None
Product: Fedora
Classification: Fedora
Component: rpm   
(Show other bugs)
Version: 13
Hardware: All
OS: Linux
Target Milestone: ---
Assignee: Panu Matilainen
QA Contact: Fedora Extras Quality Assurance
Depends On:
TreeView+ depends on / blocked
Reported: 2010-06-06 18:29 UTC by Jasper O'neal Hartline
Modified: 2011-06-27 17:39 UTC (History)
5 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2011-06-27 17:39:38 UTC
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

Description Jasper O'neal Hartline 2010-06-06 18:29:51 UTC
Description of problem:
The RFE is in the subject:
rpm man page is incomplete not including things like --setperms --setugids and other options from it's --help displayed options

Version-Release number of selected component (if applicable):

How reproducible:

Steps to Reproduce:
Actual results:

Expected results:

Additional info:
RPM is a very complete tool for doing package management.
The manual page is essential in using a tool for what it is worth, and nothing more. Without complete manual page definition of options available to the administrator one cannot know the full potential of RPM tool and I hope that all of RPM's options can be documented in it's manual page. 
The manual page is missing options like --setugids --setperms which are displayed from it's --help option output, in fact upon looking at teh manual page and then not seeing these options I had to google "reset permissions of files in an RPM package with rpm" to find these options which I knew existed but could not find in the manual page.

Comment 1 Jeff Johnson 2010-06-07 23:10:36 UTC
Those (--setperm/--setugids) aren't options, but rather POPT exec's which
are technically part of configuration and so could/shoule/would _NOT_
be captured in a man page.

See the configuration details in /usr/librpm/rpmpopt*.

That is the rationale for _NOT_ adding to the rpm.8 man page. YMMV ...

Comment 2 Michael Kearey 2010-06-08 00:37:10 UTC

In comment #1 I am not sure how that rational has been arrived at. We want man pages to be actually useful.

The simple fact is that a man page has been used as a place to document how to use the command and the list of arguments it might accept.

Currently the rpm command does have valid args --setperm and --setugids. They are delivered to the rpm command to make choices as to how the command is to behave. Right now they are undocumented. Exactly how the args are implemented - as a POPT exec or whatever is not exactly relevant. 

If the meaning of --setperms/setugid should not be documented in the rpm man page then at the very least a logical, and easily visible, useful alternative location to describe what the args do is required. That would probably require one new man page and a change to the rpm man page to refer people to it.

I personally think 'In the rpm man page '  is a logical place. And to fully document rpm it is easier to just place it in the rpm man page. BTW aren't --provides and --requires also POPT execs? They seem to be documented in the rpm man page already.


Comment 3 Jasper O'neal Hartline 2010-06-08 00:38:02 UTC
It seems as though, for just two examples of man page documented options which
are also pop/exec alias functions, --provides and --requires are in the query
section of RPM's man page. 

As far as rationale is concerned, I shouldn't need to resort to google to
figure out which options may help me in some system administration task using a
tool which is very flexible, and I call RPM the "Swiss Army Knife" of package
management utilities, while right in teh middle of doing something, although I
know I can look at --help, it has no explanation in detail of any of those

Please understand, some people may or may not know these options exist, some
people read --help, some people read the manual pages, some people use info or
pinfo. Etc.

I suggest this is a good idea simply because they are relevant to RPM, RPM is a
powerful tool, when a user can use it to it's full potential, and likewise an
administrator or user's first interface to using these tools wisely, is in a
man page.

Comment 4 Jeff Johnson 2010-06-08 01:17:06 UTC
So change the man page. *shrug*

I was just explaining why non-options
whose behavior can not only be changed, but also removed, through configuration
do not belong in RPM's man page. What's really in need of documenting
is how to extend RPM functionality using primitives like --pipe
and --queryformat and POPT aliases.

Comment 5 Jeff Johnson 2010-07-07 03:48:57 UTC
Just for the record:

    RPM likely has nearly as many options marked POPT_ARGFLAG_DOC_HIDDEN
    (which means not displayed in --help nor in the man page) as it does
    have documented options. And then there's popt alias/exec, many of whose
    usefulness has come and gone but the aliases remain in /usr/lib/rpm/rpmpopt,
    that also is in need of being completely documented so that noone ever has
    to use Google search ever again in order to use RPM.

So if you are gonna undertake ensuring that _ALL_ options/aliases/exec's/whatever
are fully documented, and you don't agree with whatever rationale was used to
choose what got documented and where, then by all means, document all of
RPM's options/aliases/exec's/whatever to your heart's content.

For extra credit: Also make sure that the two book's written about RPM (and its options)
are updated -- conformant with your new rationale -- in order to COMPLETELY
document all RPM behavior as thoroughly as possible.

Have fun!

Comment 6 Jasper O'neal Hartline 2010-07-07 06:07:24 UTC
I don't own RPM, I don't maintain it's package. I also am not paid by RedHat, Inc. or any other entity to do it as an immediate incentive. Once I singly, know RPM's options by memory, the necessity of a manual page which is fully featured becomes less important.. to me of course. The fact is many people won't know how to use these options because they cannot know they even exist or what they do.

I suppose if it isn't important, then nobody will want to.
I think it is important.

Comment 7 Jeff Johnson 2010-07-07 12:57:53 UTC
Full disclosure:

RPM is GPL/LGPL (noone "owns"), I have nothing to do with the RPM, and am
not paid by RedHat or any other entity to "fix" as an immediate incentive.

I did write the man page (in DocBook), and added a fair number of the options in RPM
(not --setuid/--setgid however). After working on RPM for 12
years now), I have no personal need for an RPM man page (although
I do find it useful as reference). 

While I'm not "many people", I do end-up doing support on IRC and
on mailing lists. I personally have not needed/used --setuid/--setgid
for perhaps 5 years now afaicr. I can't remember the last time I
needed --setuid/--setgid. And I don't recall the last time anyone
had an issue that using --setuid/--setgid would have solved

What I typically do (and what I see many people use instead) is
    rpm -Uvh --force *.rpm
to reset uid's and gid's by reinstalling a package, which "works" just fine,
and is one less CLI option to worry about, and to document. That also
seems to indicate that "nobody" has alternative options to achieve
whatever goal is important to them.

I'm glad you think documenting --setgid/--setuid is important, and
hope you succeed,

Comment 8 Jasper O'neal Hartline 2010-07-08 02:14:14 UTC
Using --setugids --setperms actually fixes issues where file permissions may have accidentally been changed due to some error in the user/administrators actions.

The scenario and fix you describe using rpm -Uvh on an rpm package, actually requires that RPM package to exist, and is a futile attempt at trying to argue the relevant need for documenting useful and all options RPM has or can use.

Thanks for showing how frustrating this is because I know it isn't.
If these options were documented to begin with as they were added to RPM, we wouldn't be having this discussion I'm sure.

Comment 9 Jeff Johnson 2010-07-08 03:17:05 UTC
I'm not stopping you from using --setugids or changing the
man page for RPM. I am saying It Really Doesn't Matter imho.

Since when is Google search not more useful than any other
form of documentation? From the beginning?

Have fun!

Comment 10 Bug Zapper 2011-06-02 11:49:15 UTC
This message is a reminder that Fedora 13 is nearing its end of life.
Approximately 30 (thirty) days from now Fedora will stop maintaining
and issuing updates for Fedora 13.  It is Fedora's policy to close all
bug reports from releases that are no longer maintained.  At that time
this bug will be closed as WONTFIX if it remains open with a Fedora 
'version' of '13'.

Package Maintainer: If you wish for this bug to remain open because you
plan to fix it in a currently maintained version, simply change the 'version' 
to a later Fedora version prior to Fedora 13's end of life.

Bug Reporter: Thank you for reporting this issue and we are sorry that 
we may not be able to fix it before Fedora 13 is end of life.  If you 
would still like to see this bug fixed and are able to reproduce it 
against a later version of Fedora please change the 'version' of this 
bug to the applicable version.  If you are unable to change the version, 
please add a comment here and someone will do it for you.

Although we aim to fix as many bugs as possible during every release's 
lifetime, sometimes those efforts are overtaken by events.  Often a 
more recent Fedora release includes newer upstream software that fixes 
bugs or makes them obsolete.

The process we are following is described here: 

Comment 11 Bug Zapper 2011-06-27 17:39:38 UTC
Fedora 13 changed to end-of-life (EOL) status on 2011-06-25. Fedora 13 is 
no longer maintained, which means that it will not receive any further 
security or bug fix updates. As a result we are closing this bug.

If you can reproduce this bug against a currently maintained version of 
Fedora please feel free to reopen this bug against that version.

Thank you for reporting this bug and we are sorry it could not be fixed.

Note You need to log in before you can comment on or make changes to this bug.