FreeBSD Manual Pages
NUT(7) NUT Manual NUT(7) NAME nut - Overview of the Network UPS Tools (NUT) DESCRIPTION The Network UPS Tools (NUT) project provides a free and open source tool kit for monitoring and managing different types of power distribution devices, first released under such name in 1999 and following up from a few earlier projects. Since then, NUT has expanded to cover thousands of devices from hundreds of vendors, and to handle various device types (UPS, ePDU, ATS/STS, solar, blade server IPMI as a sort of PDU for the blades, etc.) all with a consistent API and data model, which has since been published as The "UPS management protocol", Informational RFC 9271. While the project is in active development to support ever newer devices and their firmwares, as well as operating system releases, one of the internally recognized goals is to remain compatible with the systems NUT could have been once deployed on: even if vendors of those boxes and operating systems no longer exist, the venerable hardware deserves to be still protected with new UPS devices. Although 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. Most operating systems deliver NUT as packages built from a certain release, which for the project is just a better-tested snapshot of on-going development. 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 distribution's major release originally went with. This allows to balance delivering stable programs with well-known qualities and minimal downsides for a long stretch of time, but misses out on new capabilities, features (and yes, new bugs) which the on-going development regularly adds to the current code base du-jour. As such, NUT community support for releases (or any other non-current code) is generally limited to suggestions based on experience, but 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). Thanks to 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. NUT Architecture The project follows a multi-tiered architecture which may seem a bit complex, but 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 (the "network" part in the name). Many deployment scenarios are explored in the famous NUT Configuration Examples book maintained by Roger Price. NUT Drivers 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. 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. 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. 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. NUT Clients 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: • upsmon(8) is 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 -- 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). 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 NOTIFYCMD setting), and the part which remains owned by root to initiate the system shutdown by calling SHUTDOWNCMD when/if the time comes. 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. • upsc(8) is 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. • NUT-Monitor(8) is a GUI client for read-only or read-write access. • A suite of CGI clients can run on a web server like Apache or nginx to provide a simple HTML interface to your devices. 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). 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. 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. Please note that 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). 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. For an example of such end-game integration please see the nutshutdown script if available in your packaged distribution, or its sources at https://github.com/networkupstools/nut/blob/master/scripts/systemd/nutshutdown.in which also implements a solution to avoid the "power race condition" (for operating systems that do not limit the duration of shutdown activity). NUT Run-time Nuances For many more notes, please see the Frequently Asked Questions document in NUT sources or on the web site. A copy may be delivered by your packaging. "File or directory not found" messages 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. User/Group Accounts 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. • One notable exception is the upsmon(8) daemon which splits into a root-owned process which may trigger the OS shutdown routine, and an unprivileged process which does everything else. File system permissions 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). 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) (also known as "NDE") facility. This is a script, which may be also 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 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. 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 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.) Other configuration files 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(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 • nut.conf(5) • ups.conf(5) • upsd.conf(5) • upsd.users(5) • upsmon.conf(5) • upssched.conf(5) • hosts.conf(5) • upsset.conf(5) • upsstats.html(5) Daemons • upsd(8) • upsmon(8) • upssched(8) • upslog(8) Clients commands • upsc(8) • upscmd(8) • upsrw(8) • NUT-Monitor(8) Configuration commands • nutconf(8) • nut-scanner(8) CGI programs • upsimage.cgi(8) • upsset.cgi(8) • upsstats.cgi(8) Platform management Windows • nut.exe(8) Driver control • upsdrvctl(8) Drivers • nutupsdrv(8) • adelsystem_cbi(8) • al175(8) • apc_modbus(8) • apcsmart-old(8) • apcsmart(8) • apcupsd-ups(8) • bcmxcp(8) • bcmxcp_usb(8) • belkin(8) • belkinunv(8) • bestfcom(8) • bestfortress(8) • bestuferrups(8) • bestups(8) • bicker_ser(8) • blazer-common(8) • blazer_ser(8) • blazer_usb(8) • clone-outlet(8) • clone(8) • dummy-ups(8) • etapro(8) • everups(8) • failover(8) • gamatronic(8) • generic_modbus(8) • genericups(8) • huawei-ups2000(8) • isbmex(8) • ivtscd(8) • liebert-esp2(8) • liebert-gxe(8) • liebert(8) • masterguard(8) • metasys(8) • mge-shut(8) • mge-utalk(8) • microdowell(8) • microsol-apc(8) • netxml-ups(8) • nhs_ser(8) • nut_usb_addvars(8) • nutdrv_atcl_usb(8) • nutdrv_hashx(8) • nutdrv_qx(8) • nutdrv_siemens_sitop(8) • oneac(8) • optiups(8) • phoenixcontact_modbus(8) • powercom(8) • powerman-pdu(8) • powerpanel(8) • powervar_cx_ser(8) • powervar_cx_usb(8) • rhino(8) • richcomm_usb(8) • riello_ser(8) • riello_usb(8) • safenet(8) • sms_ser(8) • snmp-ups(8) • socomec_jbus(8) • solis(8) • tripplite(8) • tripplite_usb(8) • tripplitesu(8) • upscode2(8) • usbhid-ups(8) • ve-direct(8) • victronups(8) DEVELOPER MANUAL PAGES • libupsclient-config(1) • nut-recorder(8) • skel(8) • sockdebug(8) Client library • libnutclient(3) • libnutclient_commands(3) • libnutclient_devices(3) • libnutclient_general(3) • libnutclient_misc(3) • libnutclient_tcp(3) • libnutclient_variables(3) • upsclient(3) • upscli_add_host_cert(3) • upscli_cleanup(3) • upscli_connect(3) • upscli_tryconnect(3) • upscli_disconnect(3) • upscli_fd(3) • upscli_get(3) • upscli_init(3) • upscli_set_default_connect_timeout(3) • upscli_get_default_connect_timeout(3) • upscli_init_default_connect_timeout(3) • upscli_list_next(3) • upscli_list_start(3) • upscli_readline(3) • upscli_sendline(3) • upscli_splitaddr(3) • upscli_splitname(3) • upscli_ssl(3) • upscli_strerror(3) • upscli_upserror(3) • upscli_str_add_unique_token(3) • upscli_str_contains_token(3) Device discovery library • nutscan(3) • nutscan_add_device_to_device(3) • nutscan_add_ip_range(3) • nutscan_add_option_to_device(3) • nutscan_cidr_to_ip(3) • nutscan_display_parsable(3) • nutscan_display_sanity_check(3) • nutscan_display_sanity_check_serial(3) • nutscan_display_ups_conf(3) • nutscan_display_ups_conf_with_sanity_check(3) • nutscan_free_device(3) • nutscan_free_ip_ranges(3) • nutscan_get_serial_ports_list(3) • nutscan_init(3) • nutscan_init_ip_ranges(3) • nutscan_ip_ranges_iter_inc(3) • nutscan_ip_ranges_iter_init(3) • nutscan_new_device(3) • nutscan_scan_avahi(3) • nutscan_scan_eaton_serial(3) • nutscan_scan_ipmi(3) • nutscan_scan_nut(3) • nutscan_scan_nut_simulation(3) • nutscan_scan_snmp(3) • nutscan_scan_usb(3) • nutscan_scan_xml_http_range(3) • nutscan_stringify_ip_ranges(3) :!included-skip-title: INTERNET RESOURCES • The NUT (Network UPS Tools) home page: https://www.networkupstools.org/ 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 Network UPS Tools 2.8.4. 11/02/2025 NUT(7)
NAME | DESCRIPTION | USER MANUAL PAGES | DEVELOPER MANUAL PAGES | INTERNET RESOURCES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nut&sektion=7&manpath=FreeBSD+Ports+15.0>