Dear Lintian maintainers, lintian seems to now warn about manual pages in section 8 with no matching executable: 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 binutils 2.35.1-2 ii bzip2 1.0.8-4 ii diffstat 1.63-1 ii dpkg 1.20.5 ii dpkg-dev 1.20.5 ii file 1: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-perl 0.48-1 ii libclass-xsaccessor-perl 1.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-perl 0.10-1 ii libdevel-size-perl 0.83-1+b1 ii libdpkg-perl 1.20.5 ii libemail-address-xs-perl 1.04-1+b2 ii libfile-basedir-perl 0.08-1 ii libfile-find-rule-perl 0.34-1 ii libfont-ttf-perl 1.06-1 ii libhtml-html5-entities-perl 0.004-1 ii libipc-run3-perl 0.048-2 ii libjson-maybexs-perl 1.004002-1 ii liblist-compare-perl 0.55-1 ii liblist-moreutils-perl 0.416-1+b5 ii liblist-utilsby-perl 0.11-1 ii libmoo-perl 2.004000-1 ii libmoox-aliases-perl 0.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-perl 2.3300-1 ii libtry-tiny-perl 0.30-1 ii libtype-tiny-perl 1.010006-1 ii libunicode-utf8-perl 0.62-1+b1 ii liburi-perl 5.05-1 ii libxml-libxml-perl 2.0134+dfsg-2 ii libyaml-libyaml-perl 0.82+repack-1 ii lzip 1.21-8 ii lzop 1.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-utils 5.2.4-1+b1 lintian recommends no packages. Versions of packages lintian suggests: pn binutils-multiarch <none> 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 VxgvXyIsYjQPvQfJId4UduCQcEUmWrkuOGViMgvQOa1prku2j5APcoZRYcwNyje1 J/+BK8paZPBri5ss4MiPrS9vmjYCpXTGb7ooZwy4W5DVAqntT0F04I9NdHQ3qhD7 3OrwKIOiJfZ+OtLddkxPMqWP0RvlvwUACtdaXL96Zbep/5ZDkbGlilJTc8DN09QQ RfUrx6kkd2heXcpz7qJpPU43xgDE6CF68ag74eHj9mjMGX3xm0GKqca+e9GINb4G iINDgin+p7zbwPPPL0wT8s8lsenRRUIJgToj52LLjbQyRY6lgpsZOKycZtNOtVJb huhnuhGs5HqmPQShF7C5hmgA5YfDyhvIhX/z58sB6KpJJMkHCVaM6jrRYPT3RW5g v3MoOaEAJeRh3AVLgVenGTemdSteNqMrHtn+P3dYUx8iVmNEUnrxIrtm8hO7maoU q4E6PePc298= =l/La -----END PGP SIGNATURE-----
Hi nicoo,
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
Hi Felix, The disagreement is either there, or in the nature of PAM. 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 `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. 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 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
Sorry, forgot the attachment
nicoo <nicoo@debian.org> writes: 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).