NUT(7)

📦
version 2.8.5 · 9 versions
, in fedora 43, fedora 44

🎀 NUT(7) — the Network UPS Tools manual 🎀

okay bestie, buckle up, this is the nut overview page from the NUT Manual (that's Network UPS Tools, obvs) and it's a LOT, but it's genuinely so good, i promise. part 1 of 3, so don't go anywhere 💅

✨ NAME ✨

nut — the whole entire overview of the Network UPS Tools (NUT) project, in one (long, iconic, slightly chaotic) page 🫶

🌸 DESCRIPTION 🌸

okay so. the Network UPS Tools (NUT) project is a free and open source tool kit for monitoring and managing different types of power distribution devices. it first got released under that name in 1999, following up from a few earlier projects (yes it's been serving cunt since the 90s, we love a veteran 👑).

since then? NUT has expanded to cover thousands of devices from hundreds of vendors, and it handles a whole bunch of device types — UPS, ePDU, ATS/STS, solar, and blade server IPMI (as a sort of PDU for the blades, which is lowkey genius) — all with a consistent API and data model. and that data model? it's been published as The "UPS management protocol", Informational RFC 9271. no cap, it's a real RFC. iykyk ✨

the project is in active development, constantly supporting newer devices and their firmwares, plus new operating system releases. but one of the internally recognized goals is to remain compatible with the systems NUT could have been once deployed on. like, even if the vendors of those boxes and operating systems no longer exist, the venerable hardware still deserves to be protected with new UPS devices. it's giving respect-your-elders energy and honestly? slay 🫶

the original development involved POSIX-compliant operating systems. over time, NUT for Windows support was also implemented — however, as of NUT release v2.8.3, it remains not 100% complete — so it is possible to run the whole server and client stack as native Windows programs. almost. mostly. we're getting there 💀

most operating systems deliver NUT as packages built from a certain release. and a "release" for the project is just a better-tested snapshot of on-going development with an opinionated choice of build and run-time system configuration options. cute, right?

so some OS distribution maintainers pick fixes from later releases to update their software packages, while nominally remaining on the same base line version that the corresponding major release of that distribution originally went with. this lets them balance delivering stable programs with well-known qualities and minimal downsides for a long stretch of time that the OS release is supported (aka it does not cause headaches during minor updates) — but it also misses out on new capabilities, features (and yes, new bugs 🙈), which the on-going development regularly adds to the current code base du-jour. tradeoffs, bestie.

as such, NUT community support for releases (or any other non-current code) is generally limited to suggestions based on experience. any fixes happen on the main development branch — there are no release-tracking branches to port such solutions into — and custom builds of NUT would be required to apply them in an end-user environment. this workflow is highly automated in the project code base (its recipes and scripts), and the packaged dependencies or toolkits needed for a build are documented for numerous platforms (see links at the end of this page 👀).

and thanks to all of this, the NUT project is also a wider open-source community leader and reference in the area of build recipes and testing automation for low-level multi-platform Autotools/C/C++ projects in general. main character energy fr fr 💅

🦋 NUT Architecture 🦋

the project follows a multi-tiered architecture. it may seem a bit complex at first glance, but it's what allows for flexibility with very different real-life setups to handle. in practice, this involves numerous programs (and their configuration files) running on the same or different systems — that's the "network" part in the name, bestie ✨

many deployment scenarios are explored in the famous NUT Configuration Examples book maintained by Roger Price. go read it, it's iconic.

⭐ NUT Drivers ⭐

the lowest tier comprises NUT drivers — 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. and 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. options, we love to see it.

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. secure-ish, we stan.

for each monitored power distribution device, a NUT driver instance should be running on a machine that has a communication link to that device. one device, one driver, running somewhere that can actually talk to it 🫶

Note 📝 — there is currently no support for "multiplexing" information or commands for devices with multiple-media/multiple-driver access, e.g. to gain redundant connection or a better data collection than any one driver provides. for some devices it may be possible to run several drivers independently (probably for your monitoring system to cherry-pick data points from one driver or another), while others might only enable any one link exclusively. so no, you can't just double up for funsies, bestie 😭

⭐ NUT Data Server ⭐

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. it's basically the group chat admin of your power devices 💅

on one side, the data server connects to one or more UNIX local socket files or Windows named pipes (one for each running driver). on another side, it listens on the TCP/IP network (port 3493 by default) to communicate with local or remote client programs. so it's giving double-agent, but in a helpful way ✨

it's 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. security queen 👑

⭐ NUT Clients ⭐

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

  • upsmon(8) — a daemon to monitor primarily the states of UPSes (as opposed to other device types that NUT can handle) which power some power source units of this particular system, and based on how many PSUs are required for the system to run — it initiates a local shutdown when too many UPSes are not in a healthy condition. instances of this client allow a single UPS powering a whole rack or desk of computers to be seen by each of them (through a data server running on one of them, on a machine actually connected to the UPS — the "primary" system). one UPS, whole rack, everyone eats 🍓
Note 📝 — the upsmon client typically splits into two processes: an unprivileged one running with credentials of its RUN_AS_USER configured in the upsmon.conf(5) file (or a built-in/packaged default like nut, ups, monuser or nobody) which does most of the work (including notification scripts called via the NOTIFYCMD setting), and the part which remains owned by root to initiate the system shutdown by calling SHUTDOWNCMD when/if the time comes. two halves of one icon, honestly 💜

NUT deployments which desire higher-fidelity control (e.g. different systems shutting down after different time spent on battery) often couple the upsmon(8) with upssched(8) as their NOTIFYCMD handler.

the upsmon primary system waits for secondary systems to disconnect as part of their shut down, and is usually also responsible for commanding the managed UPS to shut itself down and power up when the "wall power" returns (or to reset the load if it is already back), subject to UPS hardware capabilities. most client integrations also stall the ultimate reboot/power-off of their machine, if its shut down was triggered by upsmon, and reboot after a long delay (if the machine is still alive). this combined approach allows to avoid the "power race condition", when systems would otherwise remain shut down indefinitely (until someone comes and reboots them) just because external power returned when the shut down spree had already started. the way that this is literally just good engineering? obsessed 😭

  • upsc(8) — a command-line client for anonymous read-only access, used to list devices served by a NUT data server, or to query data points reported by a particular device. simple, clean, does exactly what it says 🎀
  • NUT-Monitor(8) — a GUI client for read-only or read-write access. for the visual girlies 🦋
  • a suite of CGI clients can run on a web server like Apache or nginx to provide a simple HTML interface to your devices. web interface era 💅

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). so many doors, all of them open ✨

⭐ NUT Drivers during shutdown ⭐

arguably another layer in this three-layer stack is a separate role for the NUT Driver programs on the upsmon(8) primary system as mentioned above: actually telling the UPS to turn off or power-cycle as part of your computer's emergency shut down. it's the dramatic finale, the last act, the closing number 👑

while the long-running services for the NUT drivers, data server and clients are stopped as part of common OS shutdown, there may be an "endgame" integration such as high-numbered SysV init scripts (e.g. /etc/rc0.d/K99nut) or the systemd shutdown hook facility, or even something built into the initrd or similar RAM disk image that originally launched the end-user visible OS and regains control when the OS says it is done. sneaky? yes. necessary? also yes 😭

please note 📝 — not all operating systems offer ways of such integration, and may resort to other solutions (perhaps calling such logic from the stop method of upsmon init script or service definition). so check your OS, bestie, don't just assume 🫶

either way, this integration has the effect of detecting that the currently processed shutdown is due to an upsmon FSD activity (e.g. that the flag file specified by POWERDOWNFLAG configuration option in upsmon.conf(5) exists and is valid), and launches the NUT driver program(s) again to connect to the UPS(es) that this system is a primary manager of (and has possibly out-of-band connections to), just to send them the requested command and exit. in and out, quick little errand run, bye 💅✨

For a real example of that end-game integration, go peek at the nutshutdown script — it might already be chilling in your packaged distribution — or its sources at https://github.com/networkupstools/nut/blob/master/scripts/systemd/nutshutdown.in. That script also ships a fix for the "power race condition", which is the whole problem on operating systems that don't limit how long shutdown activity can drag on. 🏁

✨ NUT Run-time Nuances ✨

Okay bestie, there are SO many more notes out there — the Frequently Asked Questions document lives in the NUT sources and on the web site, and your packaging might even hand you a copy. 📚

😭 "File or directory not found" messages

So when NUT daemon programs start up, they check whether certain files exist — files that they'd create themselves, like PID files, local sockets, etc. — and they report it when such a file isn't there. Same energy for the programs that try to signal an earlier instance (if the PID is known): if that fails, you get a message too. 💀

And yes, this looks scary and confusing to first-time NUT users, because the very first thing NUT does is greet them with what looks like error messages. (NUT v2.8.x release lineage did work on improving the wording, since people asked about this constantly.) But fr, these messages are just a troubleshooting feature that's genuinely useful at that exact point in the program's life cycle: if you expect "other" program instances to be running and they aren't seen, the message helps you catch that error:

  • If this is a first run, so there should be no artifacts from "another" instance of this program lying around, the message says exactly that. ✨
  • If your program starts and sees an older instance already running, what happens next 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, meaning any old one is assumed stuck and should be terminated automatically? 🤔

The "directory" part of the wording, which may show up 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 those reports. 🙅‍♀️

That said, NUT does use directories — known in the code and in the configure script options as --with-pidpath, --with-altpidpath and --with-statepath — and those should be created and given certain permissions each (the latter two may overlap). Usually that's handled either by packaging, or by manual steps following the documentation when you build NUT from sources. On some platforms (like Linux with systemd and its systemd-tmpfiles subsystem) they may be maintained at run-time by configuration files delivered to the system. 🛠️

You can also see this message from upsmon(8) being unable to populate the POWERDOWNFLAG if the location it points to (/etc/killpower by default) doesn't exist or is read-only — or from a late shutdown integration script like the nutshutdown hook if that location got un-mounted by the time it runs. Recommendation: store that file on a volatile file system (under /var/run or /run on most modern distributions; typically the pidpath is located there too), because that survives until reboot and disappears during reboot. 🌀

👑 User/Group Accounts

Generally, NUT daemon programs avoid running as a highly-privileged root account (on POSIX platforms) — even though they anticipate being started as root (most system services are) and then drop privileges to run as the configured user and group accounts such as nut:nut. 💅

  • One notable exception is the upsmon(8) daemon, which splits into a root-owned process that may trigger the OS shutdown routine, and an unprivileged process that does everything else. 👯
  • Default user and group accounts are built-in, selected as options for the configure script when it prepares the build of NUT. Those settings can be overridden by a configuration file or by command-line options of the respective NUT daemons — whether to run as a different unprivileged user account (it may be possible to constrain each NUT service to run in its own dedicated account), or to stay capable of everything as root (rarely, drivers get configured this way temporarily to troubleshoot local device access). 🧚

🔐 File system permissions

When you're using NUT drivers with local communications media (USB or Serial ports), you absolutely must make sure 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 by using an init-script for volatile implementations. 🔧

Heads up: there are several run-time locations for data and socket files of NUT's privileged and unprivileged programs, plus 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't rewrite them, not even if there happens to be an exploitable code problem discovered in them over time. 🚨

Also super important to note: 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 those streams can be saved to disk by the OS service integration (or by a redirection from an init-script). 📝

🦋 NUT Drivers as Service instances

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) facility, also known as "NDE". It's a script that may also be called automatically (via packaging on supported platforms) at start-up, or may be running continuously 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 the upsdrvctl(8) tool), and it either fails (because the device is already busy) or ends up conflicting with the copy of the driver running as a service instance — and then they begin to terminate each other. 💀 It's giving sibling rivalry, honestly.

⚙️ Configuring NUT Drivers

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 the service-aware upsdrvsvcctl(8) and nut-driver-enumerator(8) or the legacy upsdrvctl(8), plus 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 — though you should probably review and adapt the contents first, e.g. to add a description that's meaningful to you like "UPS in garage", etc. 🚗

🎀 Other configuration files

NUT sample configuration files (packaged, or seen in sources under https://github.com/networkupstools/nut/tree/master/conf) start with a heading comment about the minimal set of their required options. And ngl, many of these files can contain credentials — either for NUT roles, or for networked power devices as part of their NUT driver section configuration — 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'd 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'd need upsmon.conf(5), and depending on your setup, you 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 the NUT project (NUT-Monitor(8) 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. 🙈

💖 USER MANUAL PAGES 💖

📌 Note

This build of NUT was configured to deliver only manual pages for programs that were actually built. For more information about the ecosystem please see the NUT website listing at https://networkupstools.org/docs/man/index.html or the sources of these pages at https://github.com/networkupstools/nut/tree/master/docs/man

🎀 Configuration files

🧚 Daemons

💅 Clients commands

✨ Configuration commands

🌸 CGI programs

🦋 Platform management

Windows

  • nut.exe(8)

👑 Driver control

🔥 Drivers

okay bestie, this is the whole roster — literally every single one, no skips, no cuts 💖

🌈 DEVELOPER MANUAL PAGES 🌈

💜 Client library

🦋 Device discovery library

⭐ INTERNET RESOURCES ⭐

  • The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/ and specifically the NUT Documentation collection with the FAQ page and several books on different aspects of NUT usage and development, maintained as part of the project code base
  • The NUT Configuration Examples book, maintained by Roger Price
  • Project GitHub repository, wiki and issue tracker: https://github.com/networkupstools/nut
  • Commonly referenced articles include:
    • The NUT FAQ page
    • Changing NUT daemon debug verbosity should be your first step in any troubleshooting
    • Build prerequisites to make NUT from scratch on various Operating Systems documents the packages you might need to build NUT on about a dozen operating system distributions (most of those the NUT CI farm tests each development iteration on)
    • Building NUT for in‐place upgrades or non‐disruptive tests details how to build a newer version of NUT than your system packaging provides (as a potential replacement of the older installation), e.g. to test if some issue got resolved or if an updated driver sees more information from your device; most such tests can be done without installing the new build into your system (not until you like it better than the current deployment)
    • Specific bits of know-how and caveats regarding NUT for Windows
  • Related projects
  • We are on Wikipedia: https://en.wikipedia.org/wiki/Network_UPS_Tools
  • The "UPS management protocol", Informational RFC 9271: https://datatracker.ietf.org/doc/html/rfc9271

and that's the whole vibe check, bestie 🫶 this page is from Network UPS Tools version 2.8.5, dated 10/07/2026, and it lives in section NUT(7) — go forth and read ur man pages, mwah 💋✨

📦 where this page comes from