Bug#973604: lintian reports spare-manual-page on PAM and NSS modules

[Russ Allbery]

nicoo  writes:

> - libpam-afs-session: /usr/share/man/man5/pam_afs_session.5.gz
>   libpam-heimdal: /usr/share/man/man5/pam_krb5.5.gz
>   libpam-krb5: /usr/share/man/man5/pam_krb5.5.gz
>   libpam-ldap: /usr/share/man/man5/pam_ldap.5.gz
>   Indeed PAM modules

The first three are all mine, so don't represent three independent
decisions.  I don't remember my thought process at the time (it was about
15 years ago now).  Maybe my thought was that most of what the man page
for a PAM module documents is what should go into the PAM configuration
files for invoking the module, and thus it's effectively configuration
file documentation?

Linux PAM itself documents all of its modules in section 8, so that's a
reasonable precedent to follow, although it looks like everyone, like me,
made their own decisions.  None of the sections fit all that naturally
(which would explain the folks who picked 7).

-- 
Russ Allbery (r...@debian.org)  

Bug#973604: lintian reports spare-manual-page on PAM and NSS modules

[nicoo]

On Wed, Nov 18, 2020 at 02:08:21AM +0100, nicoo wrote:
> There are literally 4 PAM modules whose documentation is in section 5,
> 4 more in section 7 (misfiled?) and... 83 modules whose documentation is
> in section 8.  (I'm attaching the list for those as a separate file)

Sorry, forgot the attachment

cifs-utils: /usr/share/man/man8/pam_cifscreds.8.gz
cockpit-ws: /usr/share/man/man8/pam_cockpit_cert.8.gz
cockpit-ws: /usr/share/man/man8/pam_ssh_add.8.gz
ecryptfs-utils: /usr/share/man/man8/pam_ecryptfs.8.gz
gridengine-exec: /usr/share/man/man8/pam_sge-qrsh-setup.8.gz
gridengine-exec: /usr/share/man/man8/pam_sge_authorize.8.gz
libcap2-bin: /usr/share/man/man8/pam_cap.8.gz
libpam-abl: /usr/share/man/man8/pam_abl.8.gz
libpam-alreadyloggedin: /usr/share/man/man8/pam_alreadyloggedin.8.gz
libpam-cracklib: /usr/share/man/man8/pam_cracklib.8.gz
libpam-duo: /usr/share/man/man8/pam_duo.8.gz
libpam-elogind: /usr/share/man/man8/pam_elogind.8.gz
libpam-fprintd: /usr/share/man/man8/pam_fprintd.8.gz
libpam-geoip: /usr/share/man/man8/pam_geoip.8.gz
libpam-google-authenticator: /usr/share/man/man8/pam_google_authenticator.8.gz
libpam-ldapd: /usr/share/man/man8/pam_ldap.8.gz
libpam-modules: /usr/share/man/man8/pam_access.8.gz
libpam-modules: /usr/share/man/man8/pam_debug.8.gz
libpam-modules: /usr/share/man/man8/pam_deny.8.gz
libpam-modules: /usr/share/man/man8/pam_echo.8.gz
libpam-modules: /usr/share/man/man8/pam_exec.8.gz
libpam-modules: /usr/share/man/man8/pam_faildelay.8.gz
libpam-modules: /usr/share/man/man8/pam_filter.8.gz
libpam-modules: /usr/share/man/man8/pam_ftp.8.gz
libpam-modules: /usr/share/man/man8/pam_group.8.gz
libpam-modules: /usr/share/man/man8/pam_issue.8.gz
libpam-modules: /usr/share/man/man8/pam_keyinit.8.gz
libpam-modules: /usr/share/man/man8/pam_lastlog.8.gz
libpam-modules: /usr/share/man/man8/pam_limits.8.gz
libpam-modules: /usr/share/man/man8/pam_listfile.8.gz
libpam-modules: /usr/share/man/man8/pam_localuser.8.gz
libpam-modules: /usr/share/man/man8/pam_loginuid.8.gz
libpam-modules: /usr/share/man/man8/pam_mail.8.gz
libpam-modules: /usr/share/man/man8/pam_mkhomedir.8.gz
libpam-modules: /usr/share/man/man8/pam_motd.8.gz
libpam-modules: /usr/share/man/man8/pam_namespace.8.gz
libpam-modules: /usr/share/man/man8/pam_nologin.8.gz
libpam-modules: /usr/share/man/man8/pam_permit.8.gz
libpam-modules: /usr/share/man/man8/pam_pwhistory.8.gz
libpam-modules: /usr/share/man/man8/pam_rhosts.8.gz
libpam-modules: /usr/share/man/man8/pam_rootok.8.gz
libpam-modules: /usr/share/man/man8/pam_securetty.8.gz
libpam-modules: /usr/share/man/man8/pam_sepermit.8.gz
libpam-modules: /usr/share/man/man8/pam_shells.8.gz
libpam-modules: /usr/share/man/man8/pam_succeed_if.8.gz
libpam-modules: /usr/share/man/man8/pam_tally.8.gz
libpam-modules: /usr/share/man/man8/pam_tally2.8.gz
libpam-modules: /usr/share/man/man8/pam_time.8.gz
libpam-modules: /usr/share/man/man8/pam_timestamp.8.gz
libpam-modules: /usr/share/man/man8/pam_tty_audit.8.gz
libpam-modules: /usr/share/man/man8/pam_umask.8.gz
libpam-modules: /usr/share/man/man8/pam_unix.8.gz
libpam-modules: /usr/share/man/man8/pam_userdb.8.gz
libpam-modules: /usr/share/man/man8/pam_warn.8.gz
libpam-modules: /usr/share/man/man8/pam_wheel.8.gz
libpam-modules: /usr/share/man/man8/pam_xauth.8.gz
libpam-modules-bin: /usr/share/man/man8/pam_timestamp_check.8.gz
libpam-mount: /usr/share/man/man8/pam_mount.8.gz
libpam-net: /usr/share/man/man8/pam_newnet.8.gz
libpam-net: /usr/share/man/man8/pam_usernet.8.gz
libpam-otpw: /usr/share/man/man8/pam_otpw.8.gz
libpam-passwdqc: /usr/share/man/man8/pam_passwdqc.8.gz
libpam-pkcs11: /usr/share/man/man8/pam_pkcs11.8.gz
libpam-pwquality: /usr/share/man/man8/pam_pwquality.8.gz
libpam-runtime: /usr/share/man/man8/pam_getenv.8.gz
libpam-snapper: /usr/share/man/man8/pam_snapper.8.gz
libpam-ssh: /usr/share/man/man8/pam_ssh.8.gz
libpam-ssh-agent-auth: /usr/share/man/man8/pam_ssh_agent_auth.8.gz
libpam-sss: /usr/share/man/man8/pam_sss.8.gz
libpam-systemd: /usr/share/man/man8/pam_systemd.8.gz
libpam-u2f: /usr/share/man/man8/pam_u2f.8.gz
libpam-winbind: /usr/share/man/man8/pam_winbind.8.gz
libpam-wrapper: /usr/share/man/man8/pam_chatty.8.gz
libpam-wrapper: /usr/share/man/man8/pam_get_items.8.gz
libpam-wrapper: /usr/share/man/man8/pam_matrix.8.gz
libpam-wrapper: /usr/share/man/man8/pam_set_items.8.gz
libpam-yubico: /usr/share/man/man8/pam_yubico.8.gz
lxc: /usr/share/man/ja/man8/pam_cgfs.8.gz
lxc: /usr/share/man/man8/pam_cgfs.8.gz
manpages-de: /usr/share/man/de/man8/pam_systemd.8.gz
oddjob-mkhomedir: /usr/share/man/man8/pam_oddjob_mkhomedir.8.gz
squid: /usr/share/man/man8/basic_pam_auth.8.gz


signature.asc
Description: PGP signature

Bug#973604: lintian reports spare-manual-page on PAM and NSS modules

[nicoo]

On Mon, Nov 02, 2020 at 07:12:59AM -0800, Felix Lechner wrote:
> Hi nicoo,

Hi Felix,

> We have a misunderstanding about the purpose of manual section 8. It
> was not mentioned in the original UN*X Programmer's Manual [1], but I
> believe it was created for system commands and daemons. They are
> always executable, usually executed as root, and often (but not
> always) located in /sbin or /usr/sbin.

The disagreement is either there, or in the nature of PAM.

> There are no executables with the name 'pam_u2f'. That is why you see
> the Lintian tag.

Yes, obviously, and I'm not suggesting it in section 1.
Yet, those manual page contain information that is relevant for system
administration, and not library documentation.

Indeed, no program is supposed to invoke PAM modules directly, and
instead should use libpam, whose API is indeed documented in section 3:

libpam0g-dev: /usr/share/man/man3/pam_acct_mgmt.3.gz
[...]
libpam0g-dev: /usr/share/man/man3/pam_xauth_data.3.gz


> As you pointed out, many PAM-related packages ship manual pages in
> section 8, but PAM modules are specially constructed shared libraries
> and not system commands in a broader sense. I understand why someone
> might have put them there, but I think they would do better in section
> 5, where 'pam.5' is also located.

`pam(5)` is unrelated to Pluggable Authentication Modules:

NAME
pam - portable arbitrary map file format

DESCRIPTION
The PAM image format is a lowest common denominator 2 
dimensional map for‐
mat.

It is designed to be used for any of myriad kinds  of  
graphics,  but  can
theoretically  be  used for any kind of data that is arranged 
as a two di‐
mensional rectangular array.  Actually, from another 
perspective it can be
seen as a format for data arranged as a three dimensional array.


Section 5 is also intended for “file formats and conventions”, which seems
wholy inappropriate for PAM modules.

Using apt-file, I generated an exhaustive list of manpages whose name start
with pam_.  Using this, I was able to ascertain that only the following are
*not* in section 8:

- libpam-wrapper: /usr/share/man/man1/pam_wrapper.1.gz
  An executable called `pam_wrapper`, meant for testing PAM.

- libpam-abl: /usr/share/man/man1/pam_abl.1.gz
  This is for an executable called `pam_abl`, and there is a separate
  `pam_abl(8)` manpage for the PAM module itself.

- libpam-abl: /usr/share/man/man5/pam_abl.conf.5.gz
  libpam-ldap: /usr/share/man/man5/pam_ldap.conf.5.gz
  libpam-modules: /usr/share/man/man5/pam_env.conf.5.gz
  libpam-mount: /usr/share/man/man5/pam_mount.conf.5.gz
  libpam-winbind: /usr/share/man/man5/pam_winbind.conf.5.gz
  Configuration files, so section 5 does make sense for those.

- libpam-afs-session: /usr/share/man/man5/pam_afs_session.5.gz
  libpam-heimdal: /usr/share/man/man5/pam_krb5.5.gz
  libpam-krb5: /usr/share/man/man5/pam_krb5.5.gz
  libpam-ldap: /usr/share/man/man5/pam_ldap.5.gz
  Indeed PAM modules

- libpam-krb5-migrate-heimdal: /usr/share/man/man7/pam_krb5_migrate_heimdal.7.gz
  libpam-krb5-migrate-mit: /usr/share/man/man7/pam_krb5_migrate_mit.7.gz
  libpam-modules: /usr/share/man/man7/pam_env.7.gz
  libpam-modules: /usr/share/man/man7/pam_selinux.7.gz

  More PAM modules; section 7 is “Miscellaneous (including macro packages and
  conventions), e.g. man(7), groff(7)” so those seem most likely misfiled.


> many PAM-related packages ship manual pages in section 8

There are literally 4 PAM modules whose documentation is in section 5,
4 more in section 7 (misfiled?) and... 83 modules whose documentation is
in section 8.  (I'm attaching the list for those as a separate file)

As the very least, there is an existing consensus to use section 8 there,
and it seems strange for Lintian to enforce different standards without
prior coordination?


> I'll try to find some additional documentation for the different
> manual sections. Please forward anything you might have also. Thank
> you!

I'll also try to see if there is anything semi-formal written down
on the topic, and/or confirm that section 8 is also what's used in
other operating systems which aren't Debian derivatives...
just not tonight, it's already past 2am 


Best,

  nicoo


signature.asc
Description: PGP signature

Bug#973604: lintian reports spare-manual-page on PAM and NSS modules

[Felix Lechner]

Hi nicoo,

On Mon, Nov 2, 2020 at 4:39 AM nicoo  wrote:
>
> > $ lintian -iI /opt/deb/buildarea/libpam-u2f_1.1.0-1_amd64.deb
> > I: libpam-u2f: spare-manual-page usr/share/man/man8/pam_u2f.8.gz

We have a misunderstanding about the purpose of manual section 8. It
was not mentioned in the original UN*X Programmer's Manual [1], but I
believe it was created for system commands and daemons. They are
always executable, usually executed as root, and often (but not
always) located in /sbin or /usr/sbin.

[1] https://www.bell-labs.com/usr/dmr/www/manintro.html

On my Debian 10 system, 'man man' produces the following output:

   1   Executable programs or shell commands
   2   System calls (functions provided by the kernel)
   3   Library calls (functions within program libraries)
   4   Special files (usually found in /dev)
   5   File formats and conventions eg /etc/passwd
   6   Games
   7   Miscellaneous (including macro packages and conventions),
e.g. man(7), groff(7)
   8   System administration commands (usually only for root)
   9   Kernel routines [Non standard]

The package libpam-u2f, on the other hand, contains these files:

lechner@lechner-desktop /l/l/l/git> dpkg-deb -c
/mirror/debian/pool/main/p/pam-u2f/libpam-u2f_1.0.8-1_amd64.deb
drwxr-xr-x root/root 0 2019-07-20 04:01 ./
drwxr-xr-x root/root 0 2019-07-20 04:01 ./lib/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./lib/x86_64-linux-gnu/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./lib/x86_64-linux-gnu/security/
-rw-r--r-- root/root 34656 2019-07-20 04:01
./lib/x86_64-linux-gnu/security/pam_u2f.so
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/share/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/share/doc/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/share/doc/libpam-u2f/
-rw-r--r-- root/root  3990 2019-06-04 02:28
./usr/share/doc/libpam-u2f/README.gz
-rw-r--r-- root/root  1317 2019-07-20 04:01
./usr/share/doc/libpam-u2f/changelog.Debian.gz
-rw-r--r-- root/root   724 2019-06-04 03:37
./usr/share/doc/libpam-u2f/changelog.gz
-rw-r--r-- root/root  3915 2019-07-20 04:01
./usr/share/doc/libpam-u2f/copyright
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/share/man/
drwxr-xr-x root/root 0 2019-07-20 04:01 ./usr/share/man/man8/
-rw-r--r-- root/root  3007 2019-07-20 04:01
./usr/share/man/man8/pam_u2f.8.gz

There are no executables with the name 'pam_u2f'. That is why you see
the Lintian tag.

As you pointed out, many PAM-related packages ship manual pages in
section 8, but PAM modules are specially constructed shared libraries
and not system commands in a broader sense. I understand why someone
might have put them there, but I think they would do better in section
5, where 'pam.5' is also located.

I'll try to find some additional documentation for the different
manual sections. Please forward anything you might have also. Thank
you!

Kind regards
Felix Lechner

Bug#973604: lintian reports spare-manual-page on PAM and NSS modules

[nicoo]

Package: lintian
Version: 2.100.0
Severity: normal

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512

Dear Lintian maintainers,

lintian seems to now warn about manual pages in section 8 with no matching
executable:

> $ lintian -iI /opt/deb/buildarea/libpam-u2f_1.1.0-1_amd64.deb 
> I: libpam-u2f: spare-manual-page usr/share/man/man8/pam_u2f.8.gz
> N:
> I: spare-manual-page
> N:
> N:   Each manual page in /usr/share/man should have a reason to be there.
> N:   This manual page does not appear to have a valid reason to be shipped.
> N:   
> N:   For manual pages in sections 1 and 8, an executable (or a link to one)
> N:   should exist. This check currently considers all installation packages
> N:   created by the same sources, as long as they are present.
> N:   
> N:   Refer to Debian Policy Manual section 12.1 (Manual pages) and
> N:   Bug#583125 for details.
> N:   
> N:   Severity: info
> N:   
> N:   Check: documentation/manual
> N:   
> N:   Renamed from: manpage-without-executable

This is at least incorrect in the case of NSS and PAM modules.

According to lintian.d.o, the following packages get this tag erroneously:
libnss-docker, nss-pam-ldapd, nss-wrapper
libpam-mount, libpam-net, libpam-ssh
pam, pam-geoip, pam-pkcs11, pam-ssh-agent-auth, pam-u2f, pam-wrapper


Best,

  nicoo

- -- System Information:
Debian Release: bullseye/sid
  APT prefers testing
  APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 5.9.0-1-amd64 (SMP w/4 CPU threads)
Kernel taint flags: TAINT_PROPRIETARY_MODULE, TAINT_OOT_MODULE, 
TAINT_UNSIGNED_MODULE
Locale: LANG=C.UTF-8, LC_CTYPE=C.UTF-8 (charmap=UTF-8), LANGUAGE=C.UTF-8
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages lintian depends on:
ii  binutils2.35.1-2
ii  bzip2   1.0.8-4
ii  diffstat1.63-1
ii  dpkg1.20.5
ii  dpkg-dev1.20.5
ii  file1:5.38-5
ii  gettext 0.19.8.1-10
ii  gpg 2.2.20-1
ii  intltool-debian 0.35.0+20060710.5
ii  libapt-pkg-perl 0.1.36+b3
ii  libarchive-zip-perl 1.68-1
ii  libcapture-tiny-perl0.48-1
ii  libclass-xsaccessor-perl1.19-3+b5
ii  libclone-perl   0.45-1
ii  libconfig-tiny-perl 2.24-1
ii  libcpanel-json-xs-perl  4.24-1
ii  libdata-dpath-perl  0.58-1
ii  libdata-validate-domain-perl0.10-1
ii  libdevel-size-perl  0.83-1+b1
ii  libdpkg-perl1.20.5
ii  libemail-address-xs-perl1.04-1+b2
ii  libfile-basedir-perl0.08-1
ii  libfile-find-rule-perl  0.34-1
ii  libfont-ttf-perl1.06-1
ii  libhtml-html5-entities-perl 0.004-1
ii  libipc-run3-perl0.048-2
ii  libjson-maybexs-perl1.004002-1
ii  liblist-compare-perl0.55-1
ii  liblist-moreutils-perl  0.416-1+b5
ii  liblist-utilsby-perl0.11-1
ii  libmoo-perl 2.004000-1
ii  libmoox-aliases-perl0.001006-1
ii  libnamespace-clean-perl 0.27-1
ii  libpath-tiny-perl   0.114-1
ii  libperlio-gzip-perl 0.19-1+b6
ii  libproc-processtable-perl   0.59-2
ii  libsereal-decoder-perl  4.018+ds-1
ii  libsereal-encoder-perl  4.018+ds-1
ii  libtext-glob-perl   0.11-1
ii  libtext-levenshteinxs-perl  0.03-4+b7
ii  libtext-markdown-discount-perl  0.12-1
ii  libtext-xslate-perl 3.5.8-1
ii  libtime-duration-perl   1.21-1
ii  libtime-moment-perl 0.44-1+b2
ii  libtimedate-perl2.3300-1
ii  libtry-tiny-perl0.30-1
ii  libtype-tiny-perl   1.010006-1
ii  libunicode-utf8-perl0.62-1+b1
ii  liburi-perl 5.05-1
ii  libxml-libxml-perl  2.0134+dfsg-2
ii  libyaml-libyaml-perl0.82+repack-1
ii  lzip1.21-8
ii  lzop1.04-1
ii  man-db  2.9.3-2
ii  patchutils  0.4.2-1
ii  perl [libdigest-sha-perl]   5.30.3-4
ii  t1utils 1.41-4
ii  unzip   6.0-25
ii  xz-utils5.2.4-1+b1

lintian recommends no packages.

Versions of packages lintian suggests:
pn  binutils-multiarch 
ii  libtext-template-perl  1.59-1

- -- no debconf information

-BEGIN PGP SIGNATURE-

iQJFBAEBCgAvFiEEU7EqA8ZVHYoLJhPE5vmO4pLV7MsFAl+f/RIRHG5pY29vQGRl
Ymlhbi5vcmcACgkQ5vmO4pLV7Mt3MhAAg1K0lQ1vzaUgUKleB/4KH5MSLdOKgA8g
cr+5R9/kJLgiQq8wCQtjJ/V8eAxyhIt3YAmIttg8eqH4yTvFi0ef1gw0lOYwP1FX
pbO/kW6B6vv9j/NqCldu7l4yybJM5XfMlLxcbohlG7bZWdjdhsS5S0OyKU6H4zx+
jOwy1D7enryLAsjnrDnJMvAHizHEH3KbqZz2b4dCysWqlEc8FAbcpq3Vkcpbc6Qy