Network UPS Tools Overview

// NOTE: No blank line here, document-header include processing should kick in! //GH_MARKUP_1095//ifdef::top_srcdir[] //GH_MARKUP_1095//include::{top_srcdir}docs/asciidoc-vars.conf[] //GH_MARKUP_1095//endif::top_srcdir[] //GH_MARKUP_1095//ifndef::top_srcdir[] //GH_MARKUP_1095//include::docs/asciidoc-vars.conf[] //GH_MARKUP_1095//endif::top_srcdir[] //GH_MARKUP_1095_INCLUDE_BEGIN//a6bd83d48 (2025-03-20) docs/asciidoc-vars.conf: document that linkdoc may have further args ifndef::asciidoc-vars-nut-included[] :asciidoc-vars-nut-included: true // NOTE: The big block of comments and definitions below comes from // NUT::docs/asciidoc-vars.conf and is included into top-level document // sources by maintenance recipes directly (make maintainer-asciidocs), // due to current limitations of the GitHub Web UI asciidoc renderer. // Hopefully it can be dropped in favor of compact include definitions // (see README.adoc for anticipated example) after this issue is resolved // on their side: // * https://github.com/github/markup/issues/1095 // // This file should be included into NUT documentation sources to consistently // define certain expandable attributes, with contents defined based on the // rendition target (e.g. GitHub Web UI, plain text, locally built HTML/PDF...) // Note that currently GitHub Web UI references lead to nut-website (as of // last built and published revision), not to neighboring documents in the // source browser (which would make sense for branch revisions, etc.) due // to certain complexity about referencing other-document sections with a // partially functional rendering engine there. Exploration and fixes are // welcome (actually working links like // https://github.com/networkupstools/nut/tree/master#installing or // https://github.com/networkupstools/nut/blob/master/UPGRADING.adoc#changes-from-274-to-280 // do seem promising)! // // Since the GitHub UI does not allow use of custom asciidoc configuration // files, or generally does not process the include: requests at this time, // clumsy expandable attributes had to be used (usually a set including a // prefix with meaningful name, and one or more separators and/or a suffix // with shortened names). For our classic documentation renditions, they // should resolve to properly defined macros from docs/asciidoc.conf // (usually named same as the variables defined here, for simplicity): // * linksrcdoc allows to refer to a source of documentation file // relative to the root of NUT code base. // * linkdoc allows to refer to a file under docs/ directory (or // its nut-website rendition). // * xref substitutes the asciidoc shorthand '<< >>' syntax with // attributes that conditionally expand to: // - links on GitHub (references can point at most to a section of // level docs/common.xsl's <chunk.section.depth>), or // - xref asciidoc macros when generating docs. // * linksingledoc guarantees that, when chunked HTML is generated, // the link always points to a non-chunked file. // * linkman2 allows to support different names for the manpage and // the command shown. This is also needed to properly display links // to manpages in both GitHub and generated docs without defining an // attribute for each manpage. // * linkmanext and linkmanext2 macros repeat the behavior of the default ones. // These macros are intended for system man pages (e.g. HTML links might lead // to a generic internet site, or possibly to a distro-provided library // online or locally). // // Optional attributes set by callers: // * website-url (defaulted below) may be used for "historic website" // snapshot builds... hopefully // * website is used as a boolean toggle in our recipes for nut-website // vs. offline documentation renditions // * env-github is used as a boolean toggle, set by GitHub Web-UI renderer // * (top_)srcdir and (top_)builddir can be set by Makefile.am // calling the a2x tool, since some of the files with the asciidoc // mark-up are only generated or post-processed during build and // (due to make dist restrictions) being build products, they may // not reside in same directory as static source text files which // reference or include them. Note that the non-top paths would // normally differ based on location of the Makefile involved // (e.g. workspace root, or the docs, or docs/man directories). // These variables are expected to be absolute paths, or ones relative // to asciidoc-selected :base_dir, and to end with a relevant path // separator, or be empty -- so in all cases letting the resulting // string resolve meaningfully in the filesystem during docs build. // // Please keep the remaining comments and definitions as one big block // so it does not become a series of empty paragraphs in the rendered // documents! // ifndef::website-url[] :website-url: https://www.networkupstools.org/ endif::website-url[] // ifndef::srcdir[] :srcdir: endif::srcdir[] // ifndef::builddir[] :builddir: endif::builddir[] // ifndef::top_srcdir[] :top_srcdir: endif::top_srcdir[] // ifndef::top_builddir[] :top_builddir: endif::top_builddir[] // // // Address links on GitHub vs. docs // (note: 'env-github' attribute is set on GitHub) // // - when generating docs: ifndef::env-github[] // * xref -> xref // syntax: {xref}<id>{x-s}[<caption>] // -> xref:<id>[<caption>] :xref: xref: :x-s: // * link to doc -> our macro // syntax: {linksrcdoc}<document> // -> linksrcdoc:<document>[] :linksrcdoc: linksrcdoc: // * link to doc -> our macro (optional 2/3/4 args) // syntax: {linkdoc}<document>{ld-s}[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}] // -> linkdoc:<document>[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}] :linkdoc: linkdoc: :ld-s: // * link to single doc -> our macro // syntax: {linksingledoc}<document>{lsd-s}[<display title>] // -> linksingledoc:<document>[<display title>] :linksingledoc: linksingledoc: :lsd-s: // * link to manpage -> our macro // syntax: {linkman2}<command-page>{lm-s}<displayed-command>{lm-c}<manpage-section>{lm-e} // -> linkman2:<command-page>[<displayed-command>,<manpage-section>] :linkman2: linkman2: :lm-s: [ :lm-c: , :lm-e: ] :linkmanext: https://www.die.net/search/?q= :linkmanext2: https://www.die.net/search/?q= endif::env-github[] // // - on GitHub: ifdef::env-github[] // In our normal builds, Makefile variables convey the needed paths // (used relatively below as image:images/ci/...png etc.) :imagesdir: docs // * xref -> link // syntax: {xref}<id>{x-s}[<caption>] // In order for it to work, <id> can reference at most a section of // level docs/common.xsl's <chunk.section.depth> // -> {website-url}docs/user-manual.chunked/<id>.html[<caption>] :xref: {website-url}docs/user-manual.chunked/ :x-s: .html // * link to doc -> our macro // syntax: {linksrcdoc}<document> // -> link:<document>[] :linksrcdoc: link:{top_srcdir}/ // * link to doc -> link (FIXME: ignore or use 2/3/4 args; currently they are all pasted as <display title> contents!) // syntax: {linkdoc}<document>{ld-s}[<display title>{,<anchor>{,<srcdoc>{,<chunkname>}}}] // -> {website-url}docs/<document>.chunked/index.html[<display title>] :linkdoc: {website-url}docs/ :ld-s: .chunked/index.html // * link to single doc -> link // syntax: {linksingledoc}<document>{lsd-s}[<display title>] // -> {website-url}docs/<document>.html[<display title>] :linksingledoc: {website-url}docs/ :lsd-s: .html // * link to manpage -> link // syntax: {linkman2}<command-page>{lm-s}<displayed-command>{lm-c}<manpage-section>{lm-e} // All the fields are mandatory. // -> {website-url}docs/man/<command-page>.html[<displayed-command>(<manpage-section>)] :linkman2: {website-url}docs/man/ :lm-s: .html[ :lm-c: ( :lm-e: )] :linkmanext: https://www.die.net/search/?q= :linkmanext2: https://www.die.net/search/?q= endif::env-github[] endif::asciidoc-vars-nut-included[] // //GH_MARKUP_1095_INCLUDE_END//

Description

Network UPS Tools is a collection of programs which provide a common interface for monitoring and administering UPS, PDU and SCD hardware. It uses a layered approach to connect all of the parts.

Drivers are provided for a wide assortment of equipment. They understand the specific language of each device and map it back to a compatibility layer. This means both an expensive high end UPS, a simple "power strip" PDU, or any other power device can be handled transparently with a uniform management interface.

This information is cached by the network server upsd, which then answers queries from the clients. upsd contains a number of access control features to limit the abilities of the clients. Only authorized hosts may monitor or control your hardware if you wish. Since the notion of monitoring over the network is built into the software, you can hang many systems off one large UPS, and they will all shut down together. You can also use NUT to power on, off or cycle your data center nodes, individually or globally through PDU outlets.

Clients such as upsmon check on the status of the hardware and do things when necessary. The most important task is shutting down the operating system cleanly before the UPS runs out of power. Other programs are also provided to log information regularly, monitor status through your web browser, and more.

NUT and the ecosystem

NUT comes pre-packaged for many operating systems and embedded in storage, automation or virtualization appliances, and is also often shipped as the software companion by several UPS vendors. Of course, it is quite normal and supported to build your own -- whether for an operating system which lacks it yet, or for an older distribution which lacks the current NUT version; whether to take advantage of new features or to troubleshoot a