{"id":13577664,"url":"https://github.com/networkupstools/nut","last_synced_at":"2025-05-13T15:10:42.572Z","repository":{"id":6880018,"uuid":"8129257","full_name":"networkupstools/nut","owner":"networkupstools","description":"The Network UPS Tools repository. UPS management protocol Informational RFC 9271 published by IETF at https://www.rfc-editor.org/info/rfc9271 Please star NUT on GitHub, this helps with sponsorships!","archived":false,"fork":false,"pushed_at":"2025-05-01T00:48:49.000Z","size":92068,"stargazers_count":2823,"open_issues_count":854,"forks_count":377,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-05-07T02:23:00.623Z","etag":null,"topics":["epdu","management","modbus","monitoring","netxml","nut","pdu","serial","snmp","ups","usb"],"latest_commit_sha":null,"homepage":"https://networkupstools.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/networkupstools.png","metadata":{"files":{"readme":"README.adoc","changelog":"NEWS.adoc","contributing":null,"funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.txt","support":"docs/support.txt","governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"networkupstools","open_collective":"networkupstools"}},"created_at":"2013-02-10T22:46:07.000Z","updated_at":"2025-05-06T22:44:19.000Z","dependencies_parsed_at":"2023-10-14T18:43:49.940Z","dependency_job_id":"7ae79d67-ba5c-4f73-8dd8-0d5cacc5c309","html_url":"https://github.com/networkupstools/nut","commit_stats":{"total_commits":12663,"total_committers":218,"mean_commits":58.08715596330275,"dds":0.689647003079839,"last_synced_commit":"62c43eaf30e3915d9d85af1c56e114ff275e8c45"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networkupstools","download_url":"https://codeload.github.com/networkupstools/nut/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253969248,"owners_count":21992263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["epdu","management","modbus","monitoring","netxml","nut","pdu","serial","snmp","ups","usb"],"created_at":"2024-08-01T15:01:23.388Z","updated_at":"2025-05-13T15:10:37.558Z","avatar_url":"https://github.com/networkupstools.png","language":"C","readme":"Network UPS Tools Overview\n==========================\n// NOTE: No blank line here, document-header include processing should kick in!\n//GH_MARKUP_1095//ifdef::top_srcdir[]\n//GH_MARKUP_1095//include::{top_srcdir}docs/asciidoc-vars.conf[]\n//GH_MARKUP_1095//endif::top_srcdir[]\n//GH_MARKUP_1095//ifndef::top_srcdir[]\n//GH_MARKUP_1095//include::docs/asciidoc-vars.conf[]\n//GH_MARKUP_1095//endif::top_srcdir[]\n//GH_MARKUP_1095_INCLUDE_BEGIN//a6bd83d48 (2025-03-20) docs/asciidoc-vars.conf: document that linkdoc may have further args\nifndef::asciidoc-vars-nut-included[]\n:asciidoc-vars-nut-included:\ttrue\n// NOTE: The big block of comments and definitions below comes from\n// NUT::docs/asciidoc-vars.conf and is included into top-level document\n// sources by maintenance recipes directly (`make maintainer-asciidocs`),\n// due to current limitations of the GitHub Web UI asciidoc renderer.\n// Hopefully it can be dropped in favor of compact include definitions\n// (see README.adoc for anticipated example) after this issue is resolved\n// on their side:\n// * https://github.com/github/markup/issues/1095\n//\n// This file should be included into NUT documentation sources to consistently\n// define certain expandable attributes, with contents defined based on the\n// rendition target (e.g. GitHub Web UI, plain text, locally built HTML/PDF...)\n// Note that currently GitHub Web UI references lead to nut-website (as of\n// last built and published revision), not to neighboring documents in the\n// source browser (which would make sense for branch revisions, etc.) due\n// to certain complexity about referencing other-document sections with a\n// partially functional rendering engine there. Exploration and fixes are\n// welcome (actually working links like\n// https://github.com/networkupstools/nut/tree/master#installing or\n// https://github.com/networkupstools/nut/blob/master/UPGRADING.adoc#changes-from-274-to-280\n// do seem promising)!\n//\n// Since the GitHub UI does not allow use of custom asciidoc configuration\n// files, or generally does not process the `include:` requests at this time,\n// clumsy expandable attributes had to be used (usually a set including a\n// prefix with meaningful name, and one or more separators and/or a suffix\n// with shortened names). For our classic documentation renditions, they\n// should resolve to properly defined macros from `docs/asciidoc.conf`\n// (usually named same as the variables defined here, for simplicity):\n// * `linksrcdoc` allows to refer to a source of documentation file\n//   relative to the root of NUT code base.\n// * `linkdoc` allows to refer to a file under `docs/` directory (or\n//   its nut-website rendition).\n// * `xref` substitutes the asciidoc shorthand '\u003c\u003c \u003e\u003e' syntax with\n//   attributes that conditionally expand to:\n//   - links on GitHub (references can point at most to a section of\n//     level docs/common.xsl's \u003cchunk.section.depth\u003e), or\n//   - xref asciidoc macros when generating docs.\n// * `linksingledoc` guarantees that, when chunked HTML is generated,\n//   the link always points to a non-chunked file.\n// * `linkman2` allows to support different names for the manpage and\n//   the command shown. This is also needed to properly display links\n//   to manpages in both GitHub and generated docs without defining an\n//   attribute for each manpage.\n// * `linkmanext` and `linkmanext2` macros repeat the behavior of the default ones.\n//   These macros are intended for system man pages (e.g. HTML links might lead\n//   to a generic internet site, or possibly to a distro-provided library\n//   online or locally).\n//\n// Optional attributes set by callers:\n// * `website-url` (defaulted below) may be used for \"historic website\"\n//   snapshot builds... hopefully\n// * `website` is used as a boolean toggle in our recipes for nut-website\n//   vs. offline documentation renditions\n// * `env-github` is used as a boolean toggle, set by GitHub Web-UI renderer\n// * `(top_)srcdir` and `(top_)builddir` can be set by `Makefile.am`\n//   calling the `a2x` tool, since some of the files with the asciidoc\n//   mark-up are only generated or post-processed during build and\n//   (due to `make dist` restrictions) being build products, they may\n//   not reside in same directory as static source text files which\n//   reference or include them. Note that the non-`top` paths would\n//   normally differ based on location of the `Makefile` involved\n//   (e.g. workspace root, or the `docs`, or `docs/man` directories).\n//   These variables are expected to be absolute paths, or ones relative\n//   to asciidoc-selected `:base_dir`, and to end with a relevant path\n//   separator, or be empty -- so in all cases letting the resulting\n//   string resolve meaningfully in the filesystem during docs build.\n//\n// Please keep the remaining comments and definitions as one big block\n// so it does not become a series of empty paragraphs in the rendered\n// documents!\n//\nifndef::website-url[]\n:website-url:\thttps://www.networkupstools.org/\nendif::website-url[]\n//\nifndef::srcdir[]\n:srcdir:\nendif::srcdir[]\n//\nifndef::builddir[]\n:builddir:\nendif::builddir[]\n//\nifndef::top_srcdir[]\n:top_srcdir:\nendif::top_srcdir[]\n//\nifndef::top_builddir[]\n:top_builddir:\nendif::top_builddir[]\n//\n//\n// Address links on GitHub vs. docs\n// (note: 'env-github' attribute is set on GitHub)\n//\n// - when generating docs:\nifndef::env-github[]\n//   * xref -\u003e xref\n//     syntax: {xref}\u003cid\u003e{x-s}[\u003ccaption\u003e]\n//     -\u003e xref:\u003cid\u003e[\u003ccaption\u003e]\n:xref:\t\txref:\n:x-s:\n//   * link to doc -\u003e our macro\n//     syntax: {linksrcdoc}\u003cdocument\u003e\n//     -\u003e linksrcdoc:\u003cdocument\u003e[]\n:linksrcdoc:\tlinksrcdoc:\n//   * link to doc -\u003e our macro (optional 2/3/4 args)\n//     syntax: {linkdoc}\u003cdocument\u003e{ld-s}[\u003cdisplay title\u003e{,\u003canchor\u003e{,\u003csrcdoc\u003e{,\u003cchunkname\u003e}}}]\n//     -\u003e linkdoc:\u003cdocument\u003e[\u003cdisplay title\u003e{,\u003canchor\u003e{,\u003csrcdoc\u003e{,\u003cchunkname\u003e}}}]\n:linkdoc:\tlinkdoc:\n:ld-s:\n//   * link to single doc -\u003e our macro\n//     syntax: {linksingledoc}\u003cdocument\u003e{lsd-s}[\u003cdisplay title\u003e]\n//     -\u003e linksingledoc:\u003cdocument\u003e[\u003cdisplay title\u003e]\n:linksingledoc:\tlinksingledoc:\n:lsd-s:\n//   * link to manpage -\u003e our macro\n//     syntax: {linkman2}\u003ccommand-page\u003e{lm-s}\u003cdisplayed-command\u003e{lm-c}\u003cmanpage-section\u003e{lm-e}\n//     -\u003e linkman2:\u003ccommand-page\u003e[\u003cdisplayed-command\u003e,\u003cmanpage-section\u003e]\n:linkman2:\tlinkman2:\n:lm-s:\t\t[\n:lm-c:\t\t,\n:lm-e:\t\t]\n:linkmanext:\thttps://www.die.net/search/?q=\n:linkmanext2:\thttps://www.die.net/search/?q=\nendif::env-github[]\n//\n// - on GitHub:\nifdef::env-github[]\n//     In our normal builds, Makefile variables convey the needed paths\n//     (used relatively below as `image:images/ci/...png` etc.)\n:imagesdir:\tdocs\n//   * xref -\u003e link\n//     syntax: {xref}\u003cid\u003e{x-s}[\u003ccaption\u003e]\n//     In order for it to work, \u003cid\u003e can reference at most a section of\n//     level docs/common.xsl's \u003cchunk.section.depth\u003e\n//     -\u003e {website-url}docs/user-manual.chunked/\u003cid\u003e.html[\u003ccaption\u003e]\n:xref:\t\t{website-url}docs/user-manual.chunked/\n:x-s:\t\t.html\n//   * link to doc -\u003e our macro\n//     syntax: {linksrcdoc}\u003cdocument\u003e\n//     -\u003e link:\u003cdocument\u003e[]\n:linksrcdoc:\tlink:{top_srcdir}/\n//   * link to doc -\u003e link (FIXME: ignore or use 2/3/4 args; currently they are all pasted as \u003cdisplay title\u003e contents!)\n//     syntax: {linkdoc}\u003cdocument\u003e{ld-s}[\u003cdisplay title\u003e{,\u003canchor\u003e{,\u003csrcdoc\u003e{,\u003cchunkname\u003e}}}]\n//     -\u003e {website-url}docs/\u003cdocument\u003e.chunked/index.html[\u003cdisplay title\u003e]\n:linkdoc:\t{website-url}docs/\n:ld-s:\t\t.chunked/index.html\n//   * link to single doc -\u003e link\n//     syntax: {linksingledoc}\u003cdocument\u003e{lsd-s}[\u003cdisplay title\u003e]\n//     -\u003e {website-url}docs/\u003cdocument\u003e.html[\u003cdisplay title\u003e]\n:linksingledoc:\t{website-url}docs/\n:lsd-s:\t\t.html\n//   * link to manpage -\u003e link\n//     syntax: {linkman2}\u003ccommand-page\u003e{lm-s}\u003cdisplayed-command\u003e{lm-c}\u003cmanpage-section\u003e{lm-e}\n//     All the fields are mandatory.\n//     -\u003e {website-url}docs/man/\u003ccommand-page\u003e.html[\u003cdisplayed-command\u003e(\u003cmanpage-section\u003e)]\n:linkman2:\t{website-url}docs/man/\n:lm-s:\t\t.html[\n:lm-c:\t\t(\n:lm-e:\t\t)]\n:linkmanext:\thttps://www.die.net/search/?q=\n:linkmanext2:\thttps://www.die.net/search/?q=\nendif::env-github[]\nendif::asciidoc-vars-nut-included[]\n//\n//GH_MARKUP_1095_INCLUDE_END//\n\n\nDescription\n-----------\n\nNetwork UPS Tools is a collection of programs which provide a common\ninterface for monitoring and administering UPS, PDU and SCD hardware.\nIt uses a layered approach to connect all of the parts.\n\nDrivers are provided for a wide assortment of equipment.  They\nunderstand the specific language of each device and map it back to a\ncompatibility layer.  This means both an expensive high end UPS, a simple\n\"power strip\" PDU, or any other power device can be handled transparently\nwith a uniform management interface.\n\nThis information is cached by the network server `upsd`, which then\nanswers queries from the clients.  upsd contains a number of access\ncontrol features to limit the abilities of the clients.  Only authorized\nhosts may monitor or control your hardware if you wish.  Since the\nnotion of monitoring over the network is built into the software, you\ncan hang many systems off one large UPS, and they will all shut down\ntogether. You can also use NUT to power on, off or cycle your data center\nnodes, individually or globally through PDU outlets.\n\nClients such as `upsmon` check on the status of the hardware and do things\nwhen necessary.  The most important task is shutting down the operating\nsystem cleanly before the UPS runs out of power.  Other programs are\nalso provided to log information regularly, monitor status through your\nweb browser, and more.\n\n\nNUT and the ecosystem\n---------------------\n\nNUT comes pre-packaged for many operating systems and embedded in storage,\nautomation or virtualization appliances, and is also often shipped as the\nsoftware companion by several UPS vendors. Of course, it is quite normal\nand supported to build your own -- whether for an operating system which\nlacks it yet, or for an older distribution which lacks the current NUT\nversion; whether to take advantage of new features or to troubleshoot a\nnew UPS deployment with a debugger in hand.\n\nGiven its core position at the heart of your systems' lifecycle, we make\nit a point to have current NUT building and running anywhere, especially\nwhere older releases did work before (including \"abandonware\" like the\nservers and OSes from the turn of millennium): if those boxes are still\nalive and in need of power protection, they should be able to get it.\n\n[TIP]\n=====\nIf you like how the NUT project helps protect your systems from power\noutages, please consider sponsoring or at least \"starring\" it on GitHub at\nhttps://github.com/networkupstools/nut/ - these stars are among metrics\nwhich the larger potential sponsors consider when choosing how to help\nFOSS projects. Keeping the lights shining in such a large non-regression\nbuild matrix is a big undertaking!\n\nifndef::pdf_format[]\nimage:https://api.star-history.com/svg?repos=networkupstools/nut\u0026type=Date[link=\"https://star-history.com/#networkupstools/nut\u0026Date\" alt=\"NUT GitHub Star History Chart\"]\nendif::pdf_format[]\n\nSee \u003c\u003cacknowledgements-ci-ops,acknowledgements of organizations which help\nwith NUT CI and other daily operations\u003e\u003e for an overview of the shared effort.\n=====\n\nAs a FOSS project, for over a quarter of a century we welcome contributions\nof both core code (drivers and other features), build recipes and other\nintegration elements to make it work on your favourite system, documentation\nrevisions to make it more accessible to newcomers, as well as hardware vendor\ncooperation with first-hand driver and protocol submissions, and just about\nanything else you can think of.\n\nNUT Support Policy\n~~~~~~~~~~~~~~~~~~\n\nThe Network UPS Tools project is a community-made open-source effort, primarily\nmade and maintained by people donating their spare time.\n\nThe support channels are likewise open, with preferred ones being\nlink:https://github.com/networkupstools/nut/issues[the NUT project issue\ntracker on GitHub] and the NUT Users mailing list, as detailed at\nhttps://networkupstools.org/support.html page.\n\nPlease keep in mind that any help is provided by community members just like\nyourself, as a best effort, and subject to their availability and experience.\nIt is expected that you have read the Frequently Asked Questions, looked at\nthe link:https://github.com/networkupstools/nut/wiki[NUT wiki], and have a\ngood grasp about the three-layer design and programs involved in a running\ndeployment of NUT, for a discussion to be constructive and efficient.\n\nBe patient, polite, and prepare to learn and provide information about your\nNUT deployment (version, configuration, OS...) and the device, to collect\nlogs, and to answer any follow-up questions about your situation.\n\nFinally, note that NUT is packaged and delivered by packaging into numerous\noperating systems, appliances and monitoring projects, and may be bundled\nwith third-party GUI clients.  It may be wise of end-users to identify such\ncases and ask for help on the most-relevant forum (or several, including the\nNUT support channels).  It is important to highlight that the NUT project\nreleases have for a long time been essentially snapshots of better-tested\ncode, and we do not normally issue patches to \"hot-fix\" any older releases.\n\nAny improvements of NUT itself are made in the current code base, same as\nany other feature development, so to receive desired fixes on your system\n(and/or to check that they do solve your particular issue), expect to be\nasked to build the recent development iteration from GitHub or work with\nyour appliance vendor to get a software upgrade.\n\nOver time, downstream OS packaging or other integrations which use NUT, may\nissue patches as new package revisions, or new baseline versions of NUT,\naccording to *their* release policies. It is not uncommon for distributions,\nespecially \"stable\" flavours, to be a few years behind upstream projects.\n\n\nInstalling\n----------\n\nIf you are installing these programs for the first time, go read the\n{xref}_installation_instructions{x-s}[installation instructions]\nto find out how to do that.  This document contains more information\non what all of this stuff does.\n\n\nUpgrading\n---------\n\nWhen upgrading from an older version, always check the\n{xref}Upgrading_notes{x-s}[upgrading notes] to see what may have\nchanged.  Compatibility issues and other changes will be listed there\nto ease the process.\n\n\nConfiguring and using\n---------------------\n\nOnce NUT is installed, refer to the\n{xref}Configuration_notes{x-s}[configuration notes] for directions.\n\n\nDocumentation\n-------------\n\nThis is just an overview of the software.  You should read the man pages,\nincluded example configuration files, and auxiliary documentation for the\nparts that you intend to use.\n\n\nNetwork Information\n-------------------\n\nThese programs are designed to share information over the network.  In\nthe examples below, `localhost` is used as the hostname.  This can also\nbe an IP address or a fully qualified domain name.  You can specify a\nport number if your upsd process runs on another port.\n\nIn the case of the program `upsc`, to view the variables on the UPS called\nsparky on the `upsd` server running on the local machine, you'd do this:\n\n\t/usr/local/ups/bin/upsc sparky@localhost\n\nThe default port number is 3493.  You can change this with\n\"configure --with-port\" at compile-time.  To make a client talk to upsd\non a specific port, add it after the hostname with a colon, like this:\n\n\t/usr/local/ups/bin/upsc sparky@localhost:1234\n\nThis is handy when you have a mixed environment and some of the systems\nare on different ports.\n\nThe general form for UPS identifiers is this:\n\n\t\u003cupsname\u003e[@\u003chostname\u003e[:\u003cport\u003e]]\n\nKeep this in mind when viewing the examples below.\n\n\nManifest\n--------\n\nThis package is broken down into several categories:\n\n- *drivers*\t- These programs talk directly to your UPS hardware.\n- *server*\t- upsd serves data from the drivers to the network.\n- *clients*\t- They talk to upsd and do things with the status data.\n- *cgi-bin*\t- Special class of clients that you can use with your web server.\n- *scripts*\t- Contains various scripts, like the Perl and Python binding,\nintegration bits and applications.\n\nDrivers\n-------\n\nThese programs provide support for specific UPS models.  They understand\nthe protocols and port specifications which define status information\nand convert it to a form that upsd can understand.\n\nTo configure drivers, edit ups.conf.  For this example, we'll have a UPS\ncalled \"sparky\" that uses the apcsmart driver and is connected to\n`/dev/ttyS1`.  That's the second serial port on most Linux-based systems.\nThe entry in `ups.conf` looks like this:\n\n\t[sparky]\n\t\tdriver = apcsmart\n\t\tport = /dev/ttyS1\n\nTo start and stop drivers, use upsdrvctl of upsdrvsvcctl (installed on\noperating systems with a service management framework supported by NUT).\nBy default, it will start or stop every UPS in the config file:\n\n\t/usr/local/ups/sbin/upsdrvctl start\n\t/usr/local/ups/sbin/upsdrvctl stop\n\nHowever, you can also just start or stop one by adding its name:\n\n\t/usr/local/ups/sbin/upsdrvctl start sparky\n\t/usr/local/ups/sbin/upsdrvctl stop sparky\n\nOn operating systems with a supported service management framework,\nyou might wrap your NUT drivers into individual services instances\nwith:\n\n\t/usr/local/ups/sbin/upsdrvsvcctl resync\n\nand then manage those service instances with commands like:\n\n\t/usr/local/ups/sbin/upsdrvsvcctl start sparky\n\t/usr/local/ups/sbin/upsdrvsvcctl stop sparky\n\nTo find the driver name for your device, refer to the section below\ncalled \"HARDWARE SUPPORT TABLE\".\n\nExtra Settings\n~~~~~~~~~~~~~~\n\nSome drivers may require additional settings to properly communicate\nwith your hardware.  If it doesn't detect your UPS by default, check the\ndriver's man page or help (-h) to see which options are available.\n\nFor example, the usbhid-ups driver allows you to use USB serial numbers to\ndistinguish between units via the \"serial\" configuration option.  To use this\nfeature, just add another line to your ups.conf section for that UPS:\n\n\t[sparky]\n\t\tdriver = usbhid-ups\n\t\tport = auto\n\t\tserial = 1234567890\n\nHardware Compatibility List\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe {xref}HCL{x-s}[Hardware Compatibility List] is available in the source directory\n('nut-X.Y.Z/data/driver.list'), and is generally distributed with packages.\nFor example, it is available on Debian systems as:\n\n\t/usr/share/nut/driver.list\n\nThis table is also available link:{website-url}stable-hcl.html[online].\n\n\nIf your driver has vanished, see the {linksingledoc}FAQ{lsd-s}[FAQ] and\n{xref}Upgrading_notes{x-s}[Upgrading notes].\n\nGeneric Device Drivers\n~~~~~~~~~~~~~~~~~~~~~~\n\nNUT provides several generic drivers that support a variety of very similar\nmodels.\n\n- The `genericups` driver supports many serial models that use the same basic\nprinciple to communicate with the computer.  This is known as \"contact\nclosure\", and basically involves raising or lowering signals to indicate\npower status.\n+\nThis type of UPS tends to be cheaper, and only provides the very simplest\ndata about power and battery status.  Advanced features like battery\ncharge readings and such require a \"smart\" UPS and a driver which\nsupports it.\n+\nSee the {linkman2}genericups{lm-s}genericups{lm-c}8{lm-e} man page for more information.\n\n- The `usbhid-ups` driver attempts to communicate with USB HID Power Device\nClass (PDC) UPSes. These units generally implement the same basic protocol,\nwith minor variations in the exact set of supported attributes. This driver\nalso applies several correction factors when the UPS firmware reports values\nwith incorrect scale factors.\n+\nSee the {linkman2}usbhid-ups{lm-s}usbhid-ups{lm-c}8{lm-e} man page for more information.\n\n- The `nutdrv_qx` driver supports the Megatec / Q1 protocol that is used in\nmany brands (Blazer, Energy Sistem, Fenton Technologies, Mustek, Voltronic\nPower and many others).\n+\nSee the {linkman2}nutdrv_qx{lm-s}nutdrv_qx{lm-c}8{lm-e} man page for more information.\n\n- The `snmp-ups` driver handles various SNMP enabled devices, from many\ndifferent manufacturers. In SNMP terms, `snmp-ups` is a manager, that\nmonitors SNMP agents.\n+\nSee the {linkman2}snmp-ups{lm-s}snmp-ups{lm-c}8{lm-e} man page for more information.\n\n- The `powerman-pdu` is a bridge to the PowerMan daemon, thus handling all\nPowerMan supported devices. The PowerMan project supports several serial\nand networked PDU, along with Blade and IPMI enabled servers.\n+\nSee the {linkman2}powerman-pdu{lm-s}powerman-pdu{lm-c}8{lm-e} man page for more\ninformation.\n\n- The `apcupsd-ups` driver is a bridge to the Apcupsd daemon, thus handling\nall Apcupsd supported devices. The Apcupsd project supports many serial,\nUSB and networked APC UPS.\n+\nSee the {linkman2}apcupsd-ups{lm-s}apcupsd-ups{lm-c}8{lm-e} man page for more information.\n\nUPS Shutdowns\n~~~~~~~~~~~~~\n\nupsdrvctl can also shut down (power down) all of your UPS hardware.\n\n[WARNING]\n=========\nIf you play around with this command, expect your filesystems\nto die.  Don't power off your computers unless they're ready for it:\n\n\t/usr/local/ups/sbin/upsdrvctl shutdown\n\t/usr/local/ups/sbin/upsdrvctl shutdown sparky\n=========\n\nYou should read the {xref}UPS_shutdown{x-s}[Configuring automatic UPS shutdowns]\nchapter to learn more about when to use this feature.  If called at the wrong\ntime, you may cause data loss by turning off a system with a filesystem\nmounted read-write.\n\nPower distribution unit management\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nNUT also provides an advanced support for power distribution units.\n\nYou should read the\n{xref}outlet_management{x-s}[NUT outlets management and PDU notes]\nchapter to learn more about when to use this feature.\n\nNetwork Server\n--------------\n\n`upsd` is responsible for passing data from the drivers to the client\nprograms via the network.  It should be run immediately after `upsdrvctl`\nin your system's startup scripts.\n\n`upsd` should be kept running whenever possible, as it is the only source\nof status information for the monitoring clients like `upsmon`.\n\n\nMonitoring client\n-----------------\n\n`upsmon` provides the essential feature that you expect to find in UPS\nmonitoring software: safe shutdowns when the power fails.\n\nIn the layered scheme of NUT software, it is a client.  It has this\nseparate section in the documentation since it is so important.\n\nYou configure it by telling it about UPSes that you want to monitor in\nupsmon.conf.  Each UPS can be defined as one of two possible types:\na \"primary\" or \"secondary\".\n\nPrimary\n~~~~~~~\n\nThe monitored UPS possibly supplies power to this system running `upsmon`,\nbut more importantly -- this system can manage the UPS (typically, this\ninstance of `upsmon` runs on the same system as the `upsd` and driver(s)):\nit is capable and responsible for shutting it down when the battery is\ndepleted (or in another approach, lingering to deplete it or to tell the\nUPS to reboot its load after too much time has elapsed and this system\nis still alive -- meaning wall power returned at a  \"wrong\" moment).\n\nThe shutdown of this (primary) system itself, as well as eventually an\nUPS shutdown, occurs after any secondary systems ordered to shut down\nfirst have disconnected, or a critical urgency threshold was passed.\n\nIf your UPS is plugged directly into a system's serial or USB port, the\n`upsmon` process on that system should define its relation to that UPS\nas a primary. It may be more complicated for higher-end UPSes with a\nshared network management capability (typically via SNMP) or several\nserial/USB ports that can be used simultaneously, and depends on what\nvendors and drivers implement. Setups with several competing primaries\n(for redundancy) are technically possible, if each one runs its own\nfull stack of NUT, but results can be random (currently NUT does not\nprovide a way to coordinate several entities managing the same device).\n\nFor a typical home user, there's one computer connected to one UPS.\nThat means you would run on the same computer the whole NUT stack --\na suitable driver, `upsd`, and `upsmon` in primary mode.\n\nSecondary\n~~~~~~~~~\n\nThe monitored UPS may supply power to the system running `upsmon` (or\nalternatively, it may be a monitoring station with zero PSUs fed by\nthat UPS), but more importantly, this system can't manage the UPS --\ne.g. shut it down directly (through a locally running NUT driver).\n\nUse this mode when you run multiple computers on the same UPS.\nObviously, only one can be connected to the serial or USB port\non a typical UPS, and that system is the primary. Everything\nelse is a secondary.\n\nFor a typical home user, there's one computer connected to one UPS.\nThat means you run a driver, `upsd`, and `upsmon` in primary mode.\n\nAdditional Information\n~~~~~~~~~~~~~~~~~~~~~~\n\nMore information on configuring upsmon can be found in these places:\n\n- The {linkman2}upsmon{lm-s}upsmon{lm-c}8{lm-e} man page\n- {xref}BigServers{x-s}[Typical setups for big servers]\n- {xref}UPS_shutdown{x-s}[Configuring automatic UPS shutdowns] chapter\n- The stock `upsmon.conf` that comes with the package\n\n\nClients\n-------\n\nClients talk to upsd over the network and do useful things with the data\nfrom the drivers.  There are tools for command line access, and a few\nspecial clients which can be run through your web server as CGI\nprograms.\n\nFor more details on specific programs, refer to their man pages.\n\nupsc\n~~~~\n\n`upsc` is a simple client that will display the values of variables known\nto `upsd` and your UPS drivers.  It will list every variable by default,\nor just one if you specify an additional argument.  This can be useful\nin shell scripts for monitoring something without writing your own\nnetwork code.\n\n`upsc` is a quick way to find out if your driver(s) and upsd are working\ntogether properly.  Just run `upsc \u003cups\u003e` to see what's going on, i.e.:\n\n\tmorbo:~$ upsc sparky@localhost\n\tambient.humidity: 035.6\n\tambient.humidity.alarm.maximum: NO,NO\n\tambient.humidity.alarm.minimum: NO,NO\n\tambient.temperature: 25.14\n\t...\n\nIf you are interested in writing a simple client that monitors `upsd`,\nthe source code for `upsc` is a good way to learn about using the\nupsclient functions.\n\nSee the {linkman2}upsc{lm-s}upsc{lm-c}8{lm-e} man page and\n{xref}nut-names{x-s}[NUT command and variable naming scheme] for more information.\n\nupslog\n~~~~~~\n\n`upslog` will write status information from `upsd` to a file at set\nintervals.  You can use this to generate graphs or reports with other\nprograms such as `gnuplot`.\n\nupsrw\n~~~~~\n\n`upsrw` allows you to display and change the read/write variables in your\nUPS hardware.  Not all devices or drivers implement this, so this may\nnot have any effect on your system.\n\nA driver that supports read/write variables will give results like this:\n\n----\n\t$ upsrw sparky@localhost\n\n\t( many skipped )\n\n\t[ups.test.interval]\n\tInterval between self tests\n\tType: ENUM\n\tOption: \"1209600\"\n\tOption: \"604800\" SELECTED\n\tOption: \"0\"\n\n\t( more skipped )\n----\n\nOn the other hand, one that doesn't support them won't print anything:\n\n----\n\t$ upsrw fenton@gearbox\n\n\t( nothing )\n----\n\n`upsrw` requires administrator powers to change settings in the hardware.\nRefer to {linkman2}upsd.users{lm-s}upsd.users{lm-c}5{lm-e} for information on defining\nusers in `upsd`.\n\nupscmd\n~~~~~~\n\nSome UPS hardware and drivers support the notion of an instant command -\na feature such as starting a battery test, or powering off the load.\nYou can use upscmd to list or invoke instant commands if your\nhardware/drivers support them.\n\nUse the -l command to list them, like this:\n\n----\n\t$ upscmd -l sparky@localhost\n\tInstant commands supported on UPS [sparky@localhost]:\n\n\tload.on - Turn on the load immediately\n\ttest.panel.start - Start testing the UPS panel\n\tcalibrate.start - Start run time calibration\n\tcalibrate.stop - Stop run time calibration\n\t...\n----\n\n`upscmd` requires administrator powers to start instant commands.\nTo define users and passwords in `upsd`, see\n{linkman2}upsd.users{lm-s}upsd.users{lm-c}5{lm-e}.\n\n\nCGI Programs\n------------\n\nThe CGI programs are clients that run through your web server.  They\nallow you to see UPS status and perform certain administrative commands\nfrom any web browser.  Javascript and cookies are not required.\n\nThese programs are not installed or compiled by default.  To compile\nand install them, first run `configure --with-cgi`, then do `make` and\n`make install`.  If you receive errors about \"gd\" during configure, go\nget it and install it before continuing.\n\nYou can get the source here:\n\n- http://www.libgd.org/\n\nIn the event that you need libpng or zlib in order to compile gd,\nthey can be found at these URLs:\n\n- http://www.libpng.org/pub/png/pngcode.html\n- http://www.zlib.net/\n\n\nAccess Restrictions\n~~~~~~~~~~~~~~~~~~~\n\nThe CGI programs use hosts.conf to see if they are allowed to talk to a\nhost.  This keeps malicious visitors from creating queries from your web\nserver to random hosts on the Internet.\n\nIf you get error messages that say \"Access to that host is not\nauthorized\", you're probably missing an entry in your hosts.conf.\n\nupsstats\n~~~~~~~~\n\n`upsstats` generates web pages from HTML templates, and plugs in status\ninformation in the right places.  It looks like a distant relative of\nAPC's old Powerchute interface.  You can use it to monitor several\nsystems or just focus on one.\n\nIt also can generate IMG references to `upsimage`.\n\nupsimage\n~~~~~~~~\n\nThis is usually called by upsstats via IMG SRC tags to draw either the\nutility or outgoing voltage, battery charge percent, or load percent.\n\nupsset\n~~~~~~\n\n`upsset` provides several useful administration functions through a web\ninterface.  You can use `upsset` to kick off instant commands on your UPS\nhardware like running a battery test.  You can also use it to change\nvariables in your UPS that accept user-specified values.\n\nEssentially, `upsset` provides the functions of `upsrw` and `upscmd`, but\nwith a happy pointy-clicky interface.\n\n`upsset` will not run until you convince it that you have secured your\nsystem.  You *must* secure your CGI path so that random interlopers\ncan't run this program remotely.  See the `upsset.conf` file.  Once you\nhave secured the directory, you can enable this program in that\nconfiguration file.  It is not active by default.\n\n\nVersion Numbering\n-----------------\n\nThe version numbers historically worked like this: if the middle number\nis odd, it's a development tree, otherwise it is the stable tree.\n\nThe past stable trees were 1.0, 1.2, 1.4, 2.0, 2.2 and 2.4, with the\nlatest such stable tree designated 2.6.  The development trees were 1.1,\n1.3, 1.5, 2.1 and 2.3.  Since the 2.4 release, there is no real separate\ndevelopment branch anymore since the code is available through a revision\ncontrol system (namely, Git -- or actually Subversion back then), development\nhappens in feature branches that are eventually merged into the main trunk,\nand its snapshots become published releases. As a result, subsequent versions\n(2.7 and 2.8) were released without regard for even/odd values of the minor\nversion component.\n\nSince 2.7 line of releases, sources are tracked in Git revision control\nsystem, with the project ecosystem being hosted on GitHub, and any code\nimprovements or other contributions merged through common pull request\napproach and custom NUT CI testing on multiple platforms.\n\nMajor release jumps are mostly due to large changes to the features\nlist.  There have also been a number of architectural changes which\nmay not be noticeable to most users, but which can impact developers.\n\nSince NUT v2.8.2 or so, development iterations have additional version\ncomponents, to account for the amount of commits on the main branch\n(`master`) since the last known Git tag, and amount of commits on the\ndeveloped feature branch that are unique to it compared to main branch.\nThis allows for a reasonably growing version of stable baseline and\nlocal development, so that experimental packages can be installed as\nupgrades (or well-exposed downgrades).\n\nWhile the NUT releases retain the semantic versioning three-component\nstandard, interim builds (trunk snapshots and development branches)\ncan expose a much more complex structure with the amount of commits\nin the trunk since last release, and amount of commits on the branch\nunique to it (not in the trunk). Additional data may include overall\namount of commits in the current build since last release, and the\ngit commit has identifier of the built code base.\n\nMore details can be seen in `docs/nut-versioning.adoc` file in the\nNUT source code base.\n\nBackwards and Forwards Compatibility\n------------------------------------\n\nThe network protocol for the current version of NUT should be\nbackwards-compatible all the way back to version 1.4. A newer client should\nfail gracefully when querying an older server.\n\nIf you need more details about cross-compatibility of older NUT releases\n(1.x vs. 2.x), please see the {xref}Project_History{x-s}[Project history] chapter.\n\nSupport / Help / etc.\n---------------------\n\nIf you are in need of help, refer to the\n{xref}Support_Request{x-s}[Support instructions] in the user manual.\n\n\nHacking / Development Info\n--------------------------\n\nAdditional documentation can be found in:\n\n- the {linkdoc}developer-guide{ld-s}[Developer Guide],\n- the {linkdoc}packager-guide{ld-s}[Packager Guide].\n\n\nAcknowledgements / Contributions\n--------------------------------\n\nThe many people who have participated in creating and improving NUT are\nlisted in the user manual {xref}Acknowledgements{x-s}[acknowledgements appendix].\n\n[[acknowledgements-ci-ops]]\n\nWe would like to highlight some organizations which provide continuous\nsupport to the NUT project (and many other FOSS projects) on technological\nand organizational sides, such as helping keep the donations transparent,\nNUT CI farm afloat, and public resources visible. Thanks for keeping the\nclocks ticking, day and night:\n\n////////////\nFIXME: Use different (better-resolution) images for PDF rendering?\n\nFIXME: PDF cells seem to align weirdly, like setting the bottom of the first\nline of text to be on the same level as bottom of the image, or similar to that.\n\nNOTE: GitHub renderer (or CSS stack?) ignores style settings and squashes the\nlogo column into a fixed-width monster with either our specified heights, or\nwith teeny-tiny thumbnail magnitude images, so it is prettier to leave it as\na \"single-column table\" by default. Grid/Frame settings are also ignored, but\nwe can try our best anyway.\n\nNOTE: The classic asciidoc/a2x renderer seems to not support link/url options,\nbut at least does not complain about them either.\n////////////\n\nifndef::env-github[]\n[frame=\"none\",grid=\"none\",cols=\"^.\u003c1,\u003c.\u003c2\"]\nendif::env-github[]\nifdef::env-github[]\n[frame=\"none\",grid=\"none\",cols=\"\u003c1*\"]\nendif::env-github[]\n|===\n| image:images/ci/GitHub-Mark-140pxW.png[alt=\"GitHub logo\",width=\"140\",height=\"140\",link=\"https://github.com/\"]\n| The link:https://github.com/networkupstools/[\"NetworkUPSTools\" organization\n  on GitHub] arranges a lot of things, including source code hosting for NUT\n  itself and several related projects, team management, projects, issue and\n  pull request discussions, sponsorship, nut-website rendering and hosting,\n  some automated actions, and more...\n\n| image:images/ci/jenkins-nut-transparent-bg-140pxW.png[alt=\"Jenkins and NUT logo\",width=\"139\",height=\"104\",link=\"https://www.jenkins.io/\"]\n| The link:https://www.jenkins.io/[Jenkins CI] project and its huge plugin\n  ecosystem provides the technological foundation for the largest island of\n  the link:https://ci.networkupstools.org/[self-hosted NUT CI farm].\n  There is a fair amount of cross-pollination between the upstream project\n  and community, and the development done originally for the NUT CI farm.\n\n  See more at link:https://stories.jenkins.io/user-story/jenkins-is-the-way-for-networkupstools/[Jenkins\n  is the way to build multi-platform NUT] article.\n\n| image:images/ci/fosshost_org_Host_Light_38px.png[alt=\"Fosshost logo\",width=\"112\",height=\"38\"]\n| Fosshost provided virtual machines where the multi-platform NUT CI farm with\n  a link:https://github.com/networkupstools/jenkins-dynamatrix/[jenkins-dynamatrix]\n  link:https://github.com/networkupstools/nut/blob/master/Jenkinsfile-dynamatrix[setup]\n  runs to arrange builds in numerous operating environments and a lot of toolkit\n  versions and implementations. Some workers running on NUT community members'\n  machines can also dial in to provide an example of their favourite platforms.\n  Literally hundreds of NUT builds run for each iteration, to make sure NUT can\n  always build and work everywhere.\n\n  This allows us to ensure that NUT remains portable across two decades' worth\n  of operating systems, compilers, script interpreters, tools and third-party\n  dependencies.\n\n| image:images/ci/CircleCI_vertical_black_logo.png[alt=\"CircleCI logo\",width=\"130\",height=\"107\",link=\"https://circleci.com/\"]\n| The\n  link:https://app.circleci.com/pipelines/github/networkupstools/nut/[CircleCI\n  NUT pipeline] allows us to test NUT CI builds on MacOS.\n\n| image:images/ci/AppVeyor_logo-ar21.png[alt=\"AppVeyor logo\",width=\"120\",height=\"60\",link=\"https://www.appveyor.com/\"]\n| The link:https://ci.appveyor.com/project/nut-travis/nut/[AppVeyor\n  NUT pipeline] allows us to test NUT CI builds on Windows (and publish\n  preview tarballs with binaries).\n\n| image:images/ci/DO_Powered_by_Badge_blue_140pxW.png[alt=\"DigitalOcean logo\",width=\"140\",height=\"29\",link=\"https://www.digitalocean.com/?refcode=d2fbf2b9e082\u0026utm_campaign=Referral_Invite\u0026utm_medium=Referral_Program\u0026utm_source=badge\"]\n| The link:https://www.digitalocean.com/?refcode=d2fbf2b9e082\u0026utm_campaign=Referral_Invite\u0026utm_medium=Referral_Program\u0026utm_source=badge[DigitalOcean]\n  droplets allow us to host NUT CI farm Jenkins controller and the build agents\n  for multiple operating systems.\n\n| image:images/ci/gandi-ar21.png[alt=\"Gandi.Net logo\",width=\"120\",height=\"60\",link=\"https://www.gandi.net/\"]\n| link:https://www.gandi.net/[Gandi.Net] took up the costs of NUT DNS hosting.\n\n| image:images/ci/OC_logo_merged_140x26.png[alt=\"Open Collective logo\",width=\"140\",height=\"26\",link=\"https://opencollective.com/\"]\n| https://opencollective.com/networkupstools allows us to arrange monetary\n  donations and spending, with public transparency of everything that happens.\n|===\n","funding_links":["https://github.com/sponsors/networkupstools","https://opencollective.com/networkupstools","https://opencollective.com/"],"categories":["C","monitoring"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworkupstools%2Fnut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut/lists"}