Bug 985114 - Provide man pages for the nss configuration files
Provide man pages for the nss configuration files
Status: CLOSED ERRATA
Product: Fedora
Classification: Fedora
Component: nss (Show other bugs)
rawhide
All Linux
unspecified Severity low
: ---
: ---
Assigned To: Elio Maldonado Batiz
Fedora Extras Quality Assurance
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-07-16 16:15 EDT by Elio Maldonado Batiz
Modified: 2014-06-11 11:29 EDT (History)
5 users (show)

See Also:
Fixed In Version: nss-3.15.1-3.fc19
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-08-09 13:11:14 EDT
Type: Bug
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 cert{8|9}.db, key{3|4}.db, secmod.db and pkcs11.txt (24.75 KB, patch)
2013-07-16 19:09 EDT, Elio Maldonado Batiz
no flags Details | Diff
man pages for cert{8|9}.db, key{3|4}.db, secmod.db and pkcs11.txt (24.75 KB, patch)
2013-07-16 19:14 EDT, Elio Maldonado Batiz
no flags Details | Diff
changes to nss.spc in patch format (5.28 KB, patch)
2013-07-16 19:19 EDT, Elio Maldonado Batiz
emaldona: review-
Details | Diff
Ugly docbook for pkcs11.txt - for discussion (23.43 KB, application/xml)
2013-07-17 18:21 EDT, Elio Maldonado Batiz
no flags Details

  None (edit)
Description Elio Maldonado Batiz 2013-07-16 16:15:02 EDT
Description of problem: NSS installs several files classified as system configuration files. These are the nss certificate and key databases, both legacy format and shareddb format, secmod.db and the pkcs11.txt. The last one is obviously a configuration file and the other ones one could argue either way.
It will be a requirement for the next major update of Red Hat Enterprise Linux that all configuration files be documented.


Version-Release number of selected component (if applicable): nss-3.15.1-1.


How reproducible: always
Steps to Reproduce:

Examine nss.spec which enumerates the followeing files to install:

%files
....
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/cert8.db
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/key3.db
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/secmod.db

%files sysinit
...
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/cert9.db
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/key4.db
%config(noreplace) %verify(not md5 size mtime) %{_sysconfdir}/pki/nssdb/pkcs11.txt


Actual results:
There are no pages for this files.

Expected results:
The above files have man pages installed as man(5)


Additional info: The databases just need very simple documentation. On the other hand, writing a full-fleged man page for pkcs11.txt would be a difficult task. It is based on the PKCS #11 module spec documented at  https://developer.mozilla.org/en-US/docs/PKCS11_Module_Specs

It has has a lot of nested structure. Rather than replicate that document in docbook format thatuse us for generating man pages, I propose that, at least intially, we create a rather simple man page to that just points the reader to the upstream document. 

It is very unlikely that a system admistrator will be troubleshooting a broken system on some deserted island without inernet access and have the need to look up the archana that such man page would document :-)
Comment 1 Elio Maldonado Batiz 2013-07-16 19:09:28 EDT
Created attachment 774539 [details]
man pages for cert{8|9}.db, key{3|4}.db, secmod.db and pkcs11.txt

This is a first cut. it includes the changes to the spec file a-d also for two other man related bugs. I'll split it into speparate parts if it turns out be hard to read. Let's see.
Comment 2 Elio Maldonado Batiz 2013-07-16 19:14:28 EDT
Created attachment 774548 [details]
man pages for cert{8|9}.db, key{3|4}.db, secmod.db and pkcs11.txt

This bug file also has the fixes for certutil, cmsutil, crlutil that are for bug 984106 and the upstream bug. I can split it into parts for easier review.
Comment 3 Elio Maldonado Batiz 2013-07-16 19:16:02 EDT
Comment on attachment 774539 [details]
man pages for cert{8|9}.db, key{3|4}.db, secmod.db and pkcs11.txt

Duplicate attachment.
Comment 4 Elio Maldonado Batiz 2013-07-16 19:19:28 EDT
Created attachment 774550 [details]
changes to nss.spc in patch format
Comment 5 Elio Maldonado Batiz 2013-07-17 18:21:17 EDT
Created attachment 775000 [details]
Ugly docbook for pkcs11.txt - for discussion

This is what a real manpage for pkcs11.txt would look like and I this one if far from complete. You can see the remaining descriptins as a big block of comments. It has a lot of nesting of refsections inside valistenries within variable lists. Perhaps I could have chosen simpler entities for the enumartions and the list. My XML and Docbbok knowledege is merely fair, certainly not good enough. That's why, for reasons of expediency, I have opted for a simple one that just contains the url to the gory details upstream at least for now.

Deon, do you know of a better way to tackle this?

-Elio
Comment 6 Elio Maldonado Batiz 2013-07-19 13:00:09 EDT
Comment on attachment 774550 [details]
changes to nss.spc in patch format

Cancelling the review request on the nss.spec changes because it's best to deal with this bug after we have taken care of the other two:

1) rhbz#982856 - nss-sysinit man page has wrong path for script ...
This is a trivial fix.
2) rhbz#984106 - Fixes for the {cert|cms|crl}util man pages ...
This one Kai reviewed it upstream and I'll apply that revised patch.
Comment 7 Fedora Update System 2013-08-02 17:01:41 EDT
nss-3.15.1-3.fc19 has been submitted as an update for Fedora 19.
https://admin.fedoraproject.org/updates/nss-3.15.1-3.fc19
Comment 8 Fedora Update System 2013-08-03 20:03:49 EDT
Package nss-3.15.1-3.fc19:
* should fix your issue,
* was pushed to the Fedora 19 testing repository,
* should be available at your local mirror within two days.
Update it with:
# su -c 'yum update --enablerepo=updates-testing nss-3.15.1-3.fc19'
as soon as you are able to.
Please go to the following url:
https://admin.fedoraproject.org/updates/FEDORA-2013-14189/nss-3.15.1-3.fc19
then log in and leave karma (feedback).
Comment 9 Fedora Update System 2013-08-09 13:11:14 EDT
nss-3.15.1-3.fc19 has been pushed to the Fedora 19 stable repository.  If problems still persist, please make note of it in this bug report.

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