NUT(7)

The lowest tier comprises NUT drivers, which are programs that can talk a particular protocol over certain media. Some protocols follow an industry standard (like USB HID or SNMP), or are dialects of a de-facto standard (like the originally Megatec "Q*" family of protocols used by many other vendors), but many others are vendor-specific. Some devices support several media connection types (e.g. Serial and/or USB ports, and/or SNMP for networked management), so there may be several suitable NUT drivers to choose from.

The NUT drivers are responsible for translation between NUT standard data point or instant command names and whatever strings need to be pulled for that particular device. The data is exposed to other programs on the same machine following the NUT Driver/Server Socket Protocol, which relies on operating system access controls for the UNIX local socket file or a Windows named pipe.

For each monitored power distribution device, a NUT driver instance should be running on a machine that has a communication link to that device.

A NUT Data Server (upsd(8)) represents one or more NUT drivers that run on the same machine as itself, to provide networked access to their data or pass around the instant command requests and replies.

On one side the data server connects to one or more UNIX local socket files or Windows named pipes (one for each running driver), and on another side it listens on the TCP/IP network (port 3493 by default) to communicate with local or remote client programs. It is also responsible for communication security for driver access, whether by defining the NUT user account names and assigned protocol access permissions (for value-setting or commands; read access is anonymous), or by handling the TLS/SSL part where enabled.

Practical work visible to end-users is done by a multitude of NUT clients, many of which are delivered by the project itself and more are created and maintained by the community at large. Some standard clients of note include:

Many monitoring systems integrate with NUT (and through it — with a varied assortment of power devices), using either simple clients like upsc or upslog, or libraries and bindings provided by the project itself (e.g. C, C++, Python, Java in a nearby repository) or by third-party efforts (e.g. Perl, Go, C#, REST API).

When NUT daemon programs start, they check for existence of certain files they would create themselves (PID files, local sockets, etc.) and report when such file does not exist. Similarly, some programs try to signal an earlier instance (if the PID is known) and would report if that failed.

While this does look scary and confusing to people who use NUT for the first time and it greets them with what looks like error messages (we did work on improving the wording during the NUT v2.8.x release lineage due to frequent questions), these messages are in fact just a troubleshooting aspect that is useful at that point in program life cycle: if you expect "other" program instances to be running when they are not seen, this message helps catch the error. If this is a first run, so no "other" program instance’s artifacts should be there, the message says just that. If your program starts and sees an older instance already running, further behavior depends on the situation (e.g. did you start a copy to signal the already running daemon with some command? did you start a new copy and so any old one is assumed stuck and should be terminated automatically?)

The "directory" part of the wording, which may be present in these messages, comes from the standard system library. It does not mean you should blindly create a directory (or any other object) for the file names listed in such reports.

That said, NUT does use directories (known in code and the configure script options as --with-pidpath, --with-altpidpath and --with-statepath) which should be created and assigned certain permissions each (the latter two may overlap). Generally this is done either by packaging, or by manual steps according to documentation when building NUT from sources. On some platforms (e.g. Linux with systemd and its systemd-tmpfiles subsystem) they may be maintained at run-time by configuration files delivered to the system.

The message can also be seen from upsmon(8) being unable to populate the POWERDOWNFLAG if the location it points to (/etc/killpower by default) does not exist or is read-only, or from a late shutdown integration script like the nutshutdown hook if that location was un-mounted by the time it runs. It is recommended to store that file on a volatile file system (under /run on most modern distributions; typically the pidpath is located there too), which remains until reboot and disappears during reboot.

Generally NUT daemon programs avoid running as a highly-privileged root account (on POSIX platforms), and drop privileges to run as the configured user and group accounts such as nut:nut.

When using NUT drivers with local communications media (USB or Serial ports), you must ensure that the unprivileged run-time account like nut:nut is allowed access to those device file system nodes. On many platforms this can be automated with subsystems like udev, devd, hotplug, upower; on others (older ones) you may have to chmod/chown/chgrp particular devfs nodes (whether on the persistent filesystem, or using an init-script for volatile implementations).

Note that there are several run-time locations for data and socket files of NUT’s privileged and unprivileged programs, and for configuration files. Access to these directories and individual files should be secured according to NUT documentation; NUT daemons will warn about lax permissions in their syslog or console messages. Generally, root:nut and 0640 permissions are correct for most of the files (so the run-time NUT programs may only read them but can not rewrite them, not even if there happens to be an exploitable code problem discovered in them over time).

It is also important to note that (except for upslog(8)) no NUT daemons leave log files on their own: they send syslog messages, or write to stdout/stderr, and either or both of these streams can be saved to disk by the OS service integration (or a redirection from an init-script).

Starting with NUT v2.8.0, on systems with service management frameworks (like Linux systemd or Solaris/illumos SMF) you may be even inadvertently using the nut-driver-enumerator(8). This is a script, which may also called automatically (via packaging on impacted platforms) at start-up or as a service, to process the ups.conf(5) file and maintain the service units (with their dependencies) for each driver section separately.

This sometimes raises eyebrows when end-users try to manually start a NUT driver program (either directly or using upsdrvctl(8) tool), and this either fails (because the device is already busy) or gets to conflict with the copy of the driver running as a service instance and they begin to terminate each other.

To get started with the NUT server system, you should populate the ups.conf(5) file with a section per device, which informs both the respective drivers, and tools like service-aware upsdrvsvcctl(8) and nut-driver-enumerator(8) or the legacy upsdrvctl(8), and the upsd(8) data server, to name a few.

In many typical cases, the nut-scanner(8) tool can get you started by discovering supported USB, Serial, SNMP, NetXML, IPMI devices, or remote NUT deployments using Avahi mDNS or the good old port-knocking scan. This tool would propose a complete section content that you can copy-paste into your ups.conf file (possibly review and adapt the contents first, to e.g. add a description meaningful to you like "UPS in garage", etc.)

NUT sample configuration files (packaged or seen in sources under https://github.com/networkupstools/nut/tree/master/conf directory) start with a heading comment about the minimal set of their required options. Note that many of these files can contain credentials (either for NUT roles, or for networked power devices as part of their NUT driver section configuration) and so these files and any of their backup copies should be secured accordingly.

The nut.conf(5) may be used by init-scripts or other system integration code (it notably contains the MODE setting to choose which profile of NUT services to start or not on this particular system).

On the NUT server you would need at least minimally configured: ups.conf(5), upsd.conf(5), upsd.users(5).

On the majority of NUT clients (meaning each system monitoring the UPS state so it knows when to trigger its local shutdown), you would need upsmon.conf(5) and depending on your setup, may need a custom NOTIFYCMD or SHUTDOWNCMD (if you script something complex), and/or upssched.conf(5) and a custom CMDSCRIPT for it.

For NUT CGI clients several files may need to be adapted and placed into certain directories according to their documentation: hosts.conf(5) and upsset.conf(5) for configuration, and upsstats-single.html and upsstats.html for HTML UI templates.

Other clients, whether delivered by NUT project (NUT-Monitor(1) GUI) or co-located (WMNut) or third-party (see https://networkupstools.org/projects.html) would probably support saving their settings or "favorites". Do not forget to secure access to those files and their copies as well.