Bug 606022
Summary: | nss security tools lack man pages | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Product: | Red Hat Enterprise Linux 6 | Reporter: | Elio Maldonado Batiz <emaldona> | ||||||||||||||||||
Component: | nss | Assignee: | Elio Maldonado Batiz <emaldona> | ||||||||||||||||||
Status: | CLOSED ERRATA | QA Contact: | Hubert Kario <hkario> | ||||||||||||||||||
Severity: | medium | Docs Contact: | |||||||||||||||||||
Priority: | medium | ||||||||||||||||||||
Version: | 6.1 | CC: | amarecek, dlackey, emaldona, eparis, hkario, jpazdziora, kdudka, kengert, mharmsen, ovasik, pschiffe, rrelyea, shaines, syeghiay, thoger | ||||||||||||||||||
Target Milestone: | rc | Keywords: | ManPageChange | ||||||||||||||||||
Target Release: | 6.4 | ||||||||||||||||||||
Hardware: | All | ||||||||||||||||||||
OS: | Linux | ||||||||||||||||||||
Whiteboard: | |||||||||||||||||||||
Fixed In Version: | nss-3.16.1-2.el6 | Doc Type: | Bug Fix | ||||||||||||||||||
Doc Text: |
Man pages for the nss security tools are now provided.
|
Story Points: | --- | ||||||||||||||||||
Clone Of: | 606020 | Environment: | |||||||||||||||||||
Last Closed: | 2014-10-14 05:02:12 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: | |||||||||||||||||||||
Bug Depends On: | 606020 | ||||||||||||||||||||
Bug Blocks: | |||||||||||||||||||||
Attachments: |
|
Description
Elio Maldonado Batiz
2010-06-20 00:46:15 UTC
This request was evaluated by Red Hat Product Management for inclusion in a Red Hat Enterprise Linux major release. Product Management has requested further review of this request by Red Hat Engineering, for potential inclusion in a Red Hat Enterprise Linux Major release. This request is not yet committed for inclusion. The work on the man pages has begun and we have a temporary git repo for it. L O C A T I O N S -------------------- git repo (viewing): http://fedorapeople.org/gitweb?p=emaldonado/public_git/manpagesnss.git;a=summary git repo (checking out): git clone git://fedorapeople.org/~emaldonado/manpagesnss.git Q U I C K S E T U P ----------------------- 1. Check out the man page repository. This can be done anonymously. git clone git://fedorapeople.org/~emaldonado/manpagesnss.git 2. Build a manpage. xmlto man tool-name.xml 3. Build an HTML page. man2html tool-name.1 > tool-name.html 4. Build all the manpages make all Since RHEL 6.2 External Beta has begun, and this bug remains unresolved, it has been rejected as it is not proposed as exception or blocker. Red Hat invites you to ask your support representative to propose this request, if appropriate and relevant, in the next release of Red Hat Enterprise Linux. The man pages will ready in time for RHEL-6.5. The review of the man pages will now be done upstream https://bugzilla.mozilla.org/show_bug.cgi?id=835486 The former added the to the source tree with ability to build them but https://bugzilla.mozilla.org/show_bug.cgi?id=836477 is the review bug *** Bug 980379 has been marked as a duplicate of this bug. *** Created attachment 862576 [details]
man pages for the nss security tools
plus patch to certutil.xml to pick up an upstream bug fix from nss-3.15.4.
Comment on attachment 862576 [details]
man pages for the nss security tools
Let me split the nss.spec file changes and the patch as the latter doesn't show up.
Created attachment 862577 [details]
changes to the spec file in patch format
Created attachment 862578 [details]
certutil man page fix applied upstrean on nss-3.15.4
Comment on attachment 862577 [details]
changes to the spec file in patch format
Could you avoid the intermediary copying?
Instead of ...
+# and copy them here
+for m in "%{allTools}"; do
+ cp ./nss/doc/nroff/${m}.1 .
+done
...
+# Copy the man pages for the nss tools
+for f in "%{allTools}"; do
+ install -c -m 644 ${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
+done
... would it work to simply do (see the modified install line):
+# Copy the man pages for the nss tools
+for f in "%{allTools}"; do
+ install -c -m 644 ./nss/doc/nroff/${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1
+done
The patch looks ok to me. r=kaie
However, if you can simplify it in the proposed way, please do.
(In reply to Kai Engert (:kaie) from comment #21) Thanks for the review. > Comment on attachment 862577 [details] > changes to the spec file in patch format > > Could you avoid the intermediary copying? > Instead of ... > > +# and copy them here > +for m in "%{allTools}"; do > + cp ./nss/doc/nroff/${m}.1 . > +done > ... > +# Copy the man pages for the nss tools > +for f in "%{allTools}"; do > + install -c -m 644 ${f}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1 > +done > > > ... would it work to simply do (see the modified install line): > > +# Copy the man pages for the nss tools > +for f in "%{allTools}"; do > + install -c -m 644 ./nss/doc/nroff/${f}.1 > $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1 > +done > No, that wouldn't work because by the time the build reaches the %install phase the build directory has has been deleted. Rathther tahn copyong here, at the top, a tider way is # and copy them to the dist directory for %%install to find them %{__mkdir_p} ./dist/doc/nroff %{__cp} ./nss/doc/nroff/* ./dist/doc/nroff and at intstall we can have # Copy the man pages for the nss tools for f in "%{allTools}"; do install -c -m 644 ./dist/doc/nroff/${m}.1 $RPM_BUILD_ROOT%{_mandir}/man1/${f}.1 done Eventually, it should be the build/doc/Makefile that copies the man pages to the dist directory and I plan to submit such a patch upstream for you to review along with other improvements. For the time being doing it in the spec file is the simplest way. Created attachment 892047 [details]
Adress some of flaws pointed out by Hubert
This partial fix to show some progress and get some feedback.
--------------------------------------------------------
certutil man page errors -- To be fixed in a later version of the patch
----------------------------------------------------------
cmsutil man page errors:
the -D and -C options are not in alphabetic order
duplicate "SEE ALSO"
Addressed both.
--------------------------------------------------------
crlutil man page errors:
-G Option is specified twice (the second specification is before
Arguments and has no description)
Options and arguments are not in alphabetical order
Addressed.
--------------------------------------------------------
modutil man page
"other execute: 0001", the 0001 is formatted badly
Addressed
"This line can be set added to the ~/.bashrc file to make the change permanent." should probably be "This line can be set added to the ~/.bashrc file to make the change permanent for the user."
Addressed.
--------------------------------------------------------
pk12util man page
synopsis gets formatted badly on narrow (80 column) terminal:
pk12util [-i p12File [-h tokenname] [-v] [common-options]]
[-l p12File [-h tokenname] [-r] [common-options]]
[-o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen] [-n|--cert_key_len certKeyLen] [common-options]]
[common-options are: [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword]]
Not addressed. This one is a hard one to fix because we are using xml docbook to generate the nroff pages. I'm investigating.
Arguments are not in alphabetical order.
Addressed
listing of "Symmetric CBC ciphers for PKCS#5 V2", "PKCS#12 PBE ciphers" and
"PKCS#5 PBE ciphers" has badly formatted first item
Addressed but not in the proper, it's a bit of a hack. Not easy to do in xml and I need to try a better Visual XML editor / validator.
--------------------------------------------------------
signtool man page:
-G and -J options are in wrong position (not alphabetical order)
Addressed.
-G references page 1241 (?!), also double reference to
"Generating Test Object-Signing Certificates"
Adressed.
--------------------------------------------------------
signver man page:
"This line can be set added to the ~/.bashrc file to make the change permanent."
should be "This line can be set added to the ~/.bashrc file to make the change
permanent for the user."
Addressed.
--------------------------------------------------------
ssltap man page:
options are not sorted alphabetically
Adressed.
Created attachment 892069 [details]
Adress some of the flaws pointed out by Hubert - V2
Improved patch with a few certtul.xml fixes and specially pk12util.xml fixes were I got rid of ugly emprary hacks. Using Bluefish along with xmlcopyditor and some cleanup helped. There is more to do.
Created attachment 892672 [details]
Address most of the defects pointed by hkario - v4
Additonal fixes for certutil that were missing in the prior version.
Created attachment 892674 [details]
Address most of the defects pointed by hkario - v4
Added certutil.xml fixed that were missed in the previous one.
(In reply to Hubert Kario from comment #27) > more errors in certutil man page: > > -e argument is formatted as if it was an option for -d argument > > same for: > -u and -t > -6 and -5 > -7 and -6 I couldn't see the bad formatting when I did on fedora-20 or rhel-7 but it show up when doing it on rhel-6.6 as you have indicated. The man pages are generated from docbook xml using the xmlto tool. I suspect there lies the problem. Running $ rpm -q xmlto shows me: rhel-6.6: xmlto-0.0.23-3.el6.i686 -- rhel-7.0: xmlto-0.0.25-7.el7.x86_64 -- good fedora-20: xmlto-0.0.25-7.fc20.x86_64 -- good I problem is likely caused by the older version of xmlto we have on rhel-6.6. Comment on attachment 892674 [details] Address most of the defects pointed by hkario - v4 See https://brewweb.devel.redhat.com/taskinfo?taskID=7417776 for a scratch build with this patch applied. Comment on attachment 892674 [details]
Address most of the defects pointed by hkario - v4
Hubert, I think this patch addresses almost all of the issues you have raised save two dealing with formatting - certutil and pk12util. I have also submitted a version upstream.
Comment on attachment 892674 [details]
Address most of the defects pointed by hkario - v4
r- on the basis that I don't see fixes for:
signtool man page:
-G and -J options are in wrong position (not alphabetical order)
ssltap man page:
options are not sorted alphabetically
pk12util man page:
Arguments are not in alphabetical order.
Besides that:
certutil man page errors:
description of "-d [prefix]directory" in "NSS
recognizes the following prefixes" is confusing, it's not explicit if the prefix
is "sql" or "sql:"
The fix I had in mind, was to make only the "sql:" part bolded/highlighted in the man page.
I didn't check if the formatting fixes were effective. Specifically:
errors in certutil man page:
-e argument is formatted as if it was an option for -d argument
same for:
-u and -t
-6 and -5
-7 and -6
pk12util man page:
synopsis gets formatted badly on narrow (80 column) terminal
listing of "Symmetric CBC ciphers for PKCS#5 V2",
"PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted
first item
I've tested the formatting fixes using nss-3.15.3-11.1.el6.manpages.4.x86_64 errors in certutil man page: -e argument is formatted as if it was an option for -d argument same for: -u and -t -6 and -5 (We probably should report that as a bug in rhel-6, since this is not a problem in rhel-7 or Fedora) errors in crlutil man page: Arguments not sorted errors in pk12util: The synopsis still gets badly formatted at 80 column terminal Arguments not sorted errors in signtool man page: -G and -J options are in wrong position (not alphabetical order) ssltap man page: options are not sorted alphabetically (In reply to Hubert Kario from comment #42) > Comment on attachment 892674 [details] > Address most of the defects pointed by hkario - v4 > > r- on the basis that I don't see fixes for: > > signtool man page: > > -G and -J options are in wrong position (not alphabetical order) > > ssltap man page: > > options are not sorted alphabetically > > pk12util man page: > > Arguments are not in alphabetical order. Yes, I missed those, Comming. > > > > Besides that: > > certutil man page errors: > description of "-d [prefix]directory" in "NSS > recognizes the following prefixes" is confusing, it's not explicit if the > prefix > is "sql" or "sql:" > > The fix I had in mind, was to make only the "sql:" part bolded/highlighted > in the man page. Oh, that's easy to do > > > > I didn't check if the formatting fixes were effective. Specifically: > > errors in certutil man page: > > -e argument is formatted as if it was an option for -d argument > > same for: > -u and -t > -6 and -5 > -7 and -6 > > pk12util man page: > > synopsis gets formatted badly on narrow (80 column) terminal > > listing of "Symmetric CBC ciphers for PKCS#5 V2", > "PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted > first ite That's because I was trying to mimic the nice output pkc12util --help which is very difficult, if not imposible with docbook xml. I'll follow the approach used by crypto-util's genkey. Not perfect but better for this purpose. (In reply to Hubert Kario from comment #43) > I've tested the formatting fixes using nss-3.15.3-11.1.el6.manpages.4.x86_64 > > errors in certutil man page: > > -e argument is formatted as if it was an option for -d argument > > same for: > -u and -t > -6 and -5 > > (We probably should report that as a bug in rhel-6, since this is not a > problem in rhel-7 or Fedora) Reported in Bug 1096478. Created attachment 894337 [details]
Addresses most of the review comments
https://brewweb.devel.redhat.com/taskinfo?taskID=7440040 is a scratch build with the patch applied. (In reply to Elio Maldonado Batiz from comment #44) > (In reply to Hubert Kario from comment #42) > > > > pk12util man page: > > > > synopsis gets formatted badly on narrow (80 column) terminal > > > > listing of "Symmetric CBC ciphers for PKCS#5 V2", > > "PKCS#12 PBE ciphers" and "PKCS#5 PBE ciphers" has badly formatted > > first ite > > That's because I was trying to mimic the nice output pkc12util --help which > is very difficult, if not imposible with docbook xml. I'll follow the > approach used by crypto-util's genkey. Not perfect but better for this > purpose. If you want to match `pk12util --help` output, I don't see why we couldn't show the "pk12util" command multiple times in "SYNOPSIS". I mean, `git-branch`, `grep` and `mplayer` do it, why couldn't we? Comment on attachment 894337 [details]
Addresses most of the review comments
errors (based on nss-3.15.3-11.1.el6.manpages.6.x86_64.rpm):
signtool man page:
-G and -J options are defined twice
crlutil man page:
Arguments not sorted
the good:
ssltap fixed
pk12 arguments sorting fixed
certutil sql: and dbm: highlight fixed
Created attachment 894811 [details] Addresses most of the review comments -G and -J options defined once and crlutil man page arguments sorted https://brewweb.devel.redhat.com/taskinfo?taskID=7443788 is the scratch build with this patch applied Created attachment 894820 [details] temporary workaround to faulty indendation For information purpose, not for review. In the build I also applied this suplementary patch, a temporay workaround the formatting problems based on recommendations that Ondrej Vasik gave me on Bug 1096478. I use it like this: .... # build the man pages clean pushd ./nss %{__make} clean_docs build_docs # workaround until bug 1096478 is resolved patch -b ./doc/nroff/certutil.1 $RPM_SOURCE_DIR/indentation.patch popd ... Comment on attachment 894811 [details]
Addresses most of the review comments
Looks ok, unfortunately it looks like brew already deleted the scratch build so I checked only the patch.
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-2014-1378.html |