Bug 606022 - nss security tools lack man pages
nss security tools lack man pages
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: nss (Show other bugs)
6.1
All Linux
medium Severity medium
: rc
: 6.4
Assigned To: Elio Maldonado Batiz
Hubert Kario
: ManPageChange
: 980379 (view as bug list)
Depends On: 606020
Blocks:
  Show dependency treegraph
 
Reported: 2010-06-19 20:46 EDT by Elio Maldonado Batiz
Modified: 2014-10-14 01:02 EDT (History)
15 users (show)

See Also:
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 01:02:12 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)
man pages for the nss security tools (6.21 KB, patch)
2014-02-12 18:26 EST, Elio Maldonado Batiz
no flags Details | Diff
changes to the spec file in patch format (4.25 KB, patch)
2014-02-12 18:33 EST, Elio Maldonado Batiz
kengert: review+
Details | Diff
certutil man page fix applied upstrean on nss-3.15.4 (1.72 KB, patch)
2014-02-12 18:37 EST, Elio Maldonado Batiz
kengert: review+
Details | Diff
Address most of the defects pointed by hkario - v4 (19.31 KB, patch)
2014-05-05 15:50 EDT, Elio Maldonado Batiz
no flags Details | Diff
Address most of the defects pointed by hkario - v4 (19.31 KB, patch)
2014-05-05 15:54 EDT, Elio Maldonado Batiz
hkario: review-
Details | Diff
Addresses most of the review comments (39.74 KB, patch)
2014-05-10 18:36 EDT, Elio Maldonado Batiz
hkario: review-
Details | Diff
Addresses most of the review comments (43.40 KB, patch)
2014-05-12 12:47 EDT, Elio Maldonado Batiz
hkario: review+
Details | Diff
temporary workaround to faulty indendation (949 bytes, patch)
2014-05-12 13:06 EDT, Elio Maldonado Batiz
no flags Details | Diff


External Trackers
Tracker ID Priority Status Summary Last Updated
Mozilla Foundation 1007126 None None None Never
Mozilla Foundation 836477 None None None Never

  None (edit)
Description Elio Maldonado Batiz 2010-06-19 20:46:15 EDT
+++ This bug was initially created as a clone of Bug #606020 +++

Description of problem: None of the supprted nss security tools have man pages and they should.

Version-Release number of selected component (if applicable): all n-v-r's

How reproducible: always

Steps to Reproduce:
1. man certutil (or any other one of the nss tools)
  
Actual results:
No man entry for certutil (or any othet nss tool)

Expected results: 
man page descrption on how use the tool

Additional info:
Upstream has documentation on
http://www.mozilla.org/projects/security/pki/nss/tools
so one could easily use that information to start the work.

In some instances a user or sys-admin may be trouble-shooting a problem in an environment with convenient web access and the ability to do a quick check on tools would be higly desirable.

Man pages are often used as a reference in Red Hat courses.
Comment 2 RHEL Product and Program Management 2010-06-19 21:12:53 EDT
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.
Comment 4 Elio Maldonado Batiz 2010-09-29 12:59:51 EDT
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
Comment 10 RHEL Product and Program Management 2011-10-07 12:00:55 EDT
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.
Comment 12 Elio Maldonado Batiz 2013-02-15 11:26:06 EST
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
Comment 13 Elio Maldonado Batiz 2013-02-15 11:28:15 EST
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
Comment 15 Elio Maldonado Batiz 2013-07-02 10:45:10 EDT
*** Bug 980379 has been marked as a duplicate of this bug. ***
Comment 17 Elio Maldonado Batiz 2014-02-12 18:26:13 EST
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 18 Elio Maldonado Batiz 2014-02-12 18:31:30 EST
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.
Comment 19 Elio Maldonado Batiz 2014-02-12 18:33:01 EST
Created attachment 862577 [details]
changes to the spec file in patch format
Comment 20 Elio Maldonado Batiz 2014-02-12 18:37:32 EST
Created attachment 862578 [details]
certutil man page fix applied upstrean on nss-3.15.4
Comment 21 Kai Engert (:kaie) 2014-03-05 12:27:17 EST
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.
Comment 23 Elio Maldonado Batiz 2014-03-26 13:02:59 EDT
(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.
Comment 35 Elio Maldonado Batiz 2014-05-02 18:11:56 EDT
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.
Comment 36 Elio Maldonado Batiz 2014-05-02 22:56:14 EDT
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.
Comment 37 Elio Maldonado Batiz 2014-05-05 15:50:45 EDT
Created attachment 892672 [details]
Address most of the defects pointed by hkario - v4

Additonal fixes for certutil that were missing in the prior version.
Comment 38 Elio Maldonado Batiz 2014-05-05 15:54:30 EDT
Created attachment 892674 [details]
Address most of the defects pointed by hkario - v4

Added certutil.xml fixed that were missed in the previous one.
Comment 39 Elio Maldonado Batiz 2014-05-05 16:13:50 EDT
(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 40 Elio Maldonado Batiz 2014-05-05 16:20:00 EDT
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 41 Elio Maldonado Batiz 2014-05-07 11:36:48 EDT
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 42 Hubert Kario 2014-05-09 10:01:43 EDT
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
Comment 43 Hubert Kario 2014-05-09 10:58:45 EDT
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
Comment 44 Elio Maldonado Batiz 2014-05-10 17:38:28 EDT
(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.
Comment 45 Elio Maldonado Batiz 2014-05-10 18:20:40 EDT
(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.
Comment 46 Elio Maldonado Batiz 2014-05-10 18:36:56 EDT
Created attachment 894337 [details]
Addresses most of the review comments
Comment 47 Elio Maldonado Batiz 2014-05-10 18:48:58 EDT
https://brewweb.devel.redhat.com/taskinfo?taskID=7440040 is a scratch build with the patch applied.
Comment 48 Hubert Kario 2014-05-12 08:17:37 EDT
(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 49 Hubert Kario 2014-05-12 08:29:18 EDT
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
Comment 50 Elio Maldonado Batiz 2014-05-12 12:47:11 EDT
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
Comment 51 Elio Maldonado Batiz 2014-05-12 13:06:44 EDT
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 52 Hubert Kario 2014-05-21 11:19:08 EDT
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.
Comment 54 errata-xmlrpc 2014-10-14 01:02:12 EDT
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

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