[Nut-upsdev] Man page sections

[Jim Klimov]

Just in case, I've double-checked what commonly lands into which directory
without any large path customization except putting drivers out of sight.

This was a quick build test, so maybe there are further programs in other
build setups (and/or platforms). But I guess these ones are widely used so
should be present in almost all builds.

----

:; rm -rf /tmp/nnnn ; git clean -fdX ; ./autogen.sh && ./configure
--with-all=auto --with-drvpath='${prefix}/drv'
 --enable-docs-man-for-progs-built-only=yes && make DESTDIR=/tmp/nnnn
install -j 8
:; find /tmp/nnnn | grep -E 'libexec/|bin/'
/tmp/nnnn/usr/local/ups/cgi-bin/upsstats.cgi
/tmp/nnnn/usr/local/ups/cgi-bin/upsset.cgi
/tmp/nnnn/usr/local/ups/cgi-bin/upsimage.cgi

/tmp/nnnn/usr/local/ups/libexec/sockdebug
/tmp/nnnn/usr/local/ups/libexec/nut-driver-enumerator.sh
/tmp/nnnn/usr/local/ups/libexec/enphase-monitor

/tmp/nnnn/usr/local/ups/sbin/upsmon
/tmp/nnnn/usr/local/ups/sbin/upsd
/tmp/nnnn/usr/local/ups/sbin/upsdrvctl
/tmp/nnnn/usr/local/ups/sbin/upsdrvsvcctl
/tmp/nnnn/usr/local/ups/sbin/upssched

/tmp/nnnn/usr/local/ups/bin/upslog
/tmp/nnnn/usr/local/ups/bin/upsc
/tmp/nnnn/usr/local/ups/bin/nutconf
/tmp/nnnn/usr/local/ups/bin/nut-scanner
/tmp/nnnn/usr/local/ups/bin/NUT-Monitor
/tmp/nnnn/usr/local/ups/bin/upsrw
/tmp/nnnn/usr/local/ups/bin/upscmd
/tmp/nnnn/usr/local/ups/bin/upssched-cmd

----

In context of the earlier posts in the thread: `upslog` pops up and is in a
twilight zone: it is a client which does not need authentication (like
upsc, but in a loop and may be looking at multiple sources). So perhaps
correctly in "bin" by those criteria. But it can also be used as a daemon
(optionally; reference service units provided for systems that would have
them), so might be "sbin"-ish too.

TBH, I am not sure the "requires (external) auth" mantra is a strong
argument to put stuff (upscmd, upsrw, parts of NUT-Monitor) into sysmgmt
area. A chat client like Pidgin or SSH client would need that too... but
these are available as end-user programs that can be used by multiple users
on a system for multiple different purposes (access same or different
servers as  same or different people).

The `nutconf` probably fits a sysadmin area, looking at and acting on the
NUT configuration (so at least needs FS permissions to do its job);
although in edge cases someone might use it with a custom `NUT_CONFPATH`
e.g. for testing or package preparation. But these can do with
fully-qualified path calls.

For the `nut-scanner` it depends: local devices (serial/USB) might be
constrained by FS permissions (sysmgmt); scanning networked devices would
not care (except on systems with detailed firewalls whose rules include
user accounts and program names, or RBAC/SELinux/etc. complications). At
least, the tool itself does not modify anything locally (only produces
outputs that can be added into active NUT configs by copy-paste, shell
redirect, `nutconf`, etc.) so is not strictly "sysmgmt". The most
questionable part is whether layman users *should* be able to casually call
something like this, and if fully-qualified path calls do not suffice (with
the tool moved into "sbin"). IIRC it ended up in `bin` to facilitate setups
for home users who would do most of the routine as the unprivileged
account, but I don't think this should stop us if we deem a change needed
(just someone should update blogs to `sudo -i` before most of NUT setup, if
not yet).

The (sample) `upssched-cmd` script probably should be in `sbin` if not
under `libexec(/nut)` or even `share` (and maybe named as a `*.sample` like
packaged config templates are).
The actively used one (referenced as CMDSCRIPT from upssched.conf) should
be a modified copy or unrelated code, placed wherever the local sysadmin
deems fit.

Jim Klimov






On Wed, Jun 4, 2025 at 2:31 PM Greg Troxel via Nut-upsdev <
nut-upsdev at alioth-lists.debian.net> wrote:

> Jim Klimov via Nut-upsdev <nut-upsdev at alioth-lists.debian.net> writes:
>
> >   The puzzle I found myself solving is whether all NUT programs truly fit
> > into "System management commands" (well, in a way they do all relate to
> > power mgmt), or if the division line is more about end-user/interactive
> > programs vs. daemons and sysadmin commands - similar to "bin" vs. "sbin"
> > (can that choice of install path semi-bluntly apply to man section
> > selection too)?
>
> From having used Unix since Sixth Edition, and not really going to study
> anything before responding, my immediate reaction is
>
>   Users should have /bin and /usr/bin in PATH, but not sbin.  Programs
>   in bin are thus intended for users, and man pages should be foo.1
>
>   System administration is generally done with /sbin and /usr/sbin
>   additionally in path.   Programs in sbin are thus sysadmin commands,
>   and man pages should be bar.8
>
> >   Is the `NUT-Monitor` (python UI) a sysmgmt or user program? What about
> > `upsc`, `upscmd`, `upsrw`? Perhaps tools like `nut-scanner` or `nutconf`?
> > Or developer aids like `sockdebug`/`pipedebug`?
>
> To answer this, think about a computer with a UPS, and 8 users, 2 of
> whom are able to become root and do sysadmin, and 6 are not.  This is
> the normal situation for a server.
>
> If it's reasonable for a non-admin user to run a program, and it will
> run and at least read status without needing to be a uid/gid with any
> kind of privileges, then that program should probably be in bin and .1.
> If the program doesn't make sense to use without privileges (even if the
> privileges are knowing a nut pw, not being uid 0), then it belongs sbin
> and .8.
>
> I would say
>
>   bin/1:
>     upsc
>
>   sbin/8:
>     upscmd, upsrw, nut-scanner, nutconf
>
> >   There is less of question about `upsd` or daemon clients like `upsmon`,
> > `upssched`, `upslog`, CGI, drivers, etc. - they belong in .8.
>
> Agreed.  But cgi doesn't belong in sbin.  It belongs in libexec/cgi,
> because sbin should only contain programs that people run.  Programs
> that are (only) run by other programs belong in libexec.
>
>
>
>
> An example of this "sort of logically system management but sensible for
> normal users" is envstat (on NetBSD) which prints the CPU temperatures.
> I would have said that belongs in bin/1, but it's in sbin/8.   So not
> the right place (on a knife-edge decision) but consistentcy in place for
> program and place for manual.
>
>
> _______________________________________________
> Nut-upsdev mailing list
> Nut-upsdev at alioth-lists.debian.net
> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsdev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20250604/72593b45/attachment.htm>