From jimklimov+nut at gmail.com  Wed Jun  4 08:11:29 2025
From: jimklimov+nut at gmail.com (Jim Klimov)
Date: Wed, 4 Jun 2025 09:11:29 +0200
Subject: [Nut-upsdev] Man page sections
Message-ID: <CAJYg8v+X8NrXE6ZPziO_nbP8vXLQnBZm4DG9RVj1Gi8WUGu4fQ@mail.gmail.com>

Cheers,

  During a recent PR review, I found that some man pages had links that
referred to clients like upsc as in man section 1, others as 8, and set out
to rectify it... only to find out that I am not sure about the actual right
path forward. So seeking community concensus on this one :)

  Namely, it seems that the only page built as a `.1` (since recently,
formalized as `.$(MAN_SECTION_CMD_USR)` because not all OSes follow the
same section layout) is a page for `libupsclient-config` (pre-pkgconf
helper script), and all other NUT programs landed in `.8` (or
`.$(MAN_SECTION_CMD_SYS)`).

  As a reminder, rough section definitions (common denominators that I
could find) that we juggle in docs/man/Makefile.am are:

* (3) Library calls: MAN_SECTION_API
* (5) File formats and configuration files: MAN_SECTION_CFG
* (8) System management commands: MAN_SECTION_CMD_SYS
* (1) User commands (Programs):
MAN_SECTION_CMD_USR
* (7) Overview, conventions, and miscellaneous:
MAN_SECTION_MISC

  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)?

  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`?

  There is less of question about `upsd` or daemon clients like `upsmon`,
`upssched`, `upslog`, CGI, drivers, etc. - they belong in .8.

  So far this is posted as part of
https://github.com/networkupstools/nut/pull/2977 but I guess I'll break up
that PR to move forward with the less-questionable changes.

Jim Klimov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20250604/464ca958/attachment.htm>

From gdt at lexort.com  Wed Jun  4 13:31:37 2025
From: gdt at lexort.com (Greg Troxel)
Date: Wed, 04 Jun 2025 08:31:37 -0400
Subject: [Nut-upsdev] Man page sections
In-Reply-To: <CAJYg8v+X8NrXE6ZPziO_nbP8vXLQnBZm4DG9RVj1Gi8WUGu4fQ@mail.gmail.com>
 (Jim Klimov via Nut-upsdev's message of "Wed, 4 Jun 2025 09:11:29
 +0200")
References: <CAJYg8v+X8NrXE6ZPziO_nbP8vXLQnBZm4DG9RVj1Gi8WUGu4fQ@mail.gmail.com>
Message-ID: <rmiqzzz3cye.fsf@s1.lexort.com>

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.



From jimklimov+nut at gmail.com  Wed Jun  4 15:35:13 2025
From: jimklimov+nut at gmail.com (Jim Klimov)
Date: Wed, 4 Jun 2025 16:35:13 +0200
Subject: [Nut-upsdev] Man page sections
In-Reply-To: <rmiqzzz3cye.fsf@s1.lexort.com>
References: <CAJYg8v+X8NrXE6ZPziO_nbP8vXLQnBZm4DG9RVj1Gi8WUGu4fQ@mail.gmail.com>
 <rmiqzzz3cye.fsf@s1.lexort.com>
Message-ID: <CAJYg8vJLKBrkuiJEZUAWG=MSN3yT4twAPCogUjpxBLPOgKu3Aw@mail.gmail.com>

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>

From gdt at lexort.com  Wed Jun  4 17:54:38 2025
From: gdt at lexort.com (Greg Troxel)
Date: Wed, 04 Jun 2025 12:54:38 -0400
Subject: [Nut-upsdev] Man page sections
In-Reply-To: <CAJYg8vJLKBrkuiJEZUAWG=MSN3yT4twAPCogUjpxBLPOgKu3Aw@mail.gmail.com>
 (Jim Klimov's message of "Wed, 4 Jun 2025 16:35:13 +0200")
References: <CAJYg8v+X8NrXE6ZPziO_nbP8vXLQnBZm4DG9RVj1Gi8WUGu4fQ@mail.gmail.com>
 <rmiqzzz3cye.fsf@s1.lexort.com>
 <CAJYg8vJLKBrkuiJEZUAWG=MSN3yT4twAPCogUjpxBLPOgKu3Aw@mail.gmail.com>
Message-ID: <rmi1prz30s1.fsf@s1.lexort.com>

Jim Klimov <jimklimov+nut at gmail.com> writes:

> 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.

I think it comes down to: would a normal user not acting
semi-sysadminish ever want to run it, and could they, doing something
useful.   I think it's ok for programs that land on the sysadmin side of
the divide to be in sbin.

> 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).

On one hand you are right, but pidgin/ssh are intended for remote
access, whereas I see nut clients intended primarily for the local ups,
where local might be different machine same cluster.  I'd again think
"is user acting sysadminish".  upsc is sort of "tell me the power
status" which feels semi-normal, but I'm not normal.


> 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.

Definitely sbin.  and indeed sbin is not inaccessible, just not default.

> 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).

I see nut-scanner as fundamentally sysadmin in intent and usage, even if
it doesn't need privs.   sbin is all about segregating commands that
normal users wouldn't want to run

> 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.

agree that examples belong in share/examples/nut, not really installed