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
Attachment:
signature.asc
Description: PGP signature