Skip to content
  • Eric S. Raymond's avatar
    Impose a uniform set of man section assignments and install directories... · 3271edce
    Eric S. Raymond authored
    ...replacing the platform-dependent mess in NTP Classic.  The reason
    dumping all that complexity makes sense is that most of our targets
    have a packaging layer that will adjust these to local tastes no
    matter what our install productions do.
    
    Here is the mapping in NTP Classic.  My analysis, a slightly edited form
    of an email on the topic, follows.
    
                 darwin  debian  legacy  netbsd  redhat  solaris
    	     ------  ------  ------  ------  ------  -------
    calc-tickadj -       sbin,8  bin,1   -       sbin,8  sbin,1m
    ntp-keygen   bin,8   sbin,8  bin,1   sbin,8  sbin,8  sbin,1m
    ntp-wait     sbin,8  sbin,8  bin,1   sbin,8  sbin,8  libexec,1m
    ntpd         sbin,8  sbin,8  bin,1   sbin,8  sbin,8  sbin,1m
    ntpdate      sbin,8  sbin,8  bin,1   sbin,8  sbin,8  sbin,1m
    ntpdsim      sbin,8  sbin,8  bin,1   sbin,8  -       sbin,1m
    ntpq         bin,8   bin,1   bin,1   sbin,8  sbin,8  sbin,1m
    ntpsweep     -       bin,1   -       -       -       -
    ntptime      sbin,8  sbin,8  bin,1   sbin,8  sbin,8  sbin,1m
    ntptrace     sbin,8  bin,1   bin,1   sbin,8  sbin,8  sbin,1m
    ntptickadj   -       sbin,8  bin,1   -       sbin,8  sbin,1m
    sntp         bin,8   bin,1   bin,1   sbin,1  sbin,8  sbin,1m
    update-leap  sbin,8  sbin,8  bin,1   sbin,8  -       sbin,1m
    
    All the 'bin' entries are actually /usr/bin.  Section 1m is an
    obsolete System V equivalent of section 8.
    
    That...is rather a dog's breakfast.  Bletch.  There's less consistency
    here, and less guidance, than I expected.  Even if you throw out 'legacy'
    which is obviously a dumb fallback to ancient Unixes.
    
    So let's go to first principles.  The sbin directory is supposed to be
    reserved for binaries that may have to be available during boot,
    possibly before /usr/bin is mounted. It's generally considered bad
    form to drop stuff there *unless* it's needed early.  (Many of the
    above columns exhibit a degree of bad form that surprises me.)
    
    Aha. I went Googling for "/sbin directory".  Right away I found that
    the Linux Filesystem Hierarchy portion of the FSSTND states the above
    more formally:
    
      /sbin should contain only binaries essential for booting, restoring,
      recovering, and/or repairing the system in addition to the binaries
      in /bin.
    
    It costs us little to be FSSTND-conformant, makes us look like good
    Linux citizens, and won't offend people packaging for non-Linuxes.
    
    By this criterion ntp-wait, ntpd, ntpdate, and sntp clearly belong in /sbin
    (sntp so we can use it in the ntpdate wrapper, it might be questionable
    otherwise).  These are the commands that may be required to update the
    system clock at boot time.
    
    Just as clearly calc-tickadj, ntp-keygen, ntpdsim, ntpq, ntpsweep,
    ntptime, ntptrace, and ntptickadj do not belong there. The latter are
    tuning and diagnostic tools to be run after boot, from the shell, by
    NTP admins.  So they go in /usr/bin.
    
    update-leap is never required for system initialization, but it's not
    a userland command either - it's really meant to be run from a cron
    job every couple of weeks. Because it's not required early I'm going
    to say /usr/bin.
    
    There's a little more uniformity about existing practice in where the
    manual pages go. Once we toss out the 'legacy' column and realize that
    1m = 8, the only commands that ever land in section 1 are ntpq, ntpsweep,
    ntptrace, and sntp.
    
    Historically there are two schools of thought about the general
    question. One is that anything administrative goes in section 8.  The
    other is that admin commands which do not require elevated privileges
    go in section 1.  (su(1) is an exception.)
    
    That's pretty much exactly what we see in the Debian column.  All the
    section 8 commands require library or system calls with privilege
    barriers, or to modify files in system space. None of the Section 1
    files do.
    
    The 'debian' column wins this one by a nose because, taken together,
    distributions in that family are likely to have a majority of our
    deployments.  But this is a weak argument and I could be talked into
    "everything goes to section 8" pretty easily.
    
    Inventorying every executable that this codebase might potentially install
    and applying these rules, we have the following table.
    
    Name          Installdir  man  Now installed?
    ------------  ----------  ---  --------------
    calc-tickadj  /usr/bin/    8     No
    ntp-keygen    /usr/bin/    8     Yes
    ntp-wait      /sbin        8     No
    ntpd          /sbin        8     Yes
    ntpdate       /sbin        -     No
    ntpdsim       /usr/bin/    8     No
    ntpq          /usr/bin/    1     Yes
    ntpsweep      /usr/bin/    1     No
    ntptime       /usr/bin/    8     Yes
    ntptrace      /usr/bin/    1     No
    ntptickadj    /usr/bin/    8     Yes
    plot-summary  /usr/bin/    1     No
    sntp          /sbin        1     Yes
    summary       /usr/bin/    1     No
    update-leap   /usr/bin/    8     No
    
    The last column describes, whether, at the time of this commit, there is
    an install production for the given binary or script.
    
    Note: One issue with the install productions as presently written is that
    they're written to install to ${PREFIX}/bin and {PREFIX}/sbin.  This
    is right if we're trying to install a test setup to userspace but wrong
    in the normal case - we want /sbin, not /usr/sbin.
    3271edce