{"id":20663625,"url":"https://github.com/networkupstools/nut-archive","last_synced_at":"2026-04-18T22:32:55.216Z","repository":{"id":6879915,"uuid":"8129151","full_name":"networkupstools/nut-archive","owner":"networkupstools","description":"The reposurgeon translation of the NUT SVN repository, including all old branches and tags. (Fork and file issues on https://github.com/networkupstools/nut instead)","archived":false,"fork":false,"pushed_at":"2013-02-10T22:49:04.000Z","size":112396,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T12:26:28.945Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":false,"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","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.txt","support":null}},"created_at":"2013-02-10T22:35:55.000Z","updated_at":"2019-02-25T10:55:44.000Z","dependencies_parsed_at":"2022-08-26T07:11:18.985Z","dependency_job_id":null,"html_url":"https://github.com/networkupstools/nut-archive","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/networkupstools/nut-archive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-archive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-archive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-archive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-archive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/networkupstools","download_url":"https://codeload.github.com/networkupstools/nut-archive/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/networkupstools%2Fnut-archive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31987860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"ssl_error","status_checked_at":"2026-04-18T20:23:29.375Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2024-11-16T19:19:00.191Z","updated_at":"2026-04-18T22:32:55.181Z","avatar_url":"https://github.com/networkupstools.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"Network UPS Tools Overview\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 with\na 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\nInstalling\n----------\n\nIf you are installing these programs for the first time, go read the\n\u003c\u003c_installation_instructions,installation instructions\u003e\u003e\nto find out how to do that.  This document contains more information on what all\nof this stuff does.\n\n\nUpgrading\n---------\n\nWhen upgrading from an older version, always check the\n\u003c\u003cUpgrading_notes,upgrading notes\u003e\u003e to see what may have\nchanged.  Compatibility issues and other changes will be listed there to ease\nthe process.\n\n\nConfiguring and using\n---------------------\n\nOnce NUT is installed, refer to the\n\u003c\u003cConfiguration_notes,configuration notes\u003e\u003e 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 parts\nthat 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.  By default, it will start or\nstop every UPS in the config file:\n\n\t/usr/local/ups/bin/upsdrvctl start\n\t/usr/local/ups/bin/upsdrvctl stop\n\nHowever, you can also just start or stop one by adding its name:\n\n\t/usr/local/ups/bin/upsdrvctl start sparky\n\t/usr/local/ups/bin/upsdrvctl 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 \u003c\u003cHCL,Hardware Compatibility List\u003e\u003e 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:http://www.networkupstools.org/stable-hcl.html[online].\n\n\nIf your driver has vanished, see the link:FAQ.html[FAQ] and\n\u003c\u003cUpgrading_notes,Upgrading notes\u003e\u003e.\n\nGeneric Device Drivers\n~~~~~~~~~~~~~~~~~~~~~~\n\nNUT provides several generic drivers that support a variety of very similar models.\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 linkman:genericups[8] 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 linkman:usbhid-ups[8] man page for more information.\n\n- The `blazer_ser` and `blazer_usb` drivers supports the Megatec / Q1\nprotocol that is used in many brands (Blazer, Energy Sistem, Fenton\nTechnologies, Mustek and many others).\n+\nSee the linkman:blazer[8] 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 linkman:snmp-ups[8] 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 linkman:powerman-pdu[8] man page for more\ninformation.\n\n\nUPS Shutdowns\n~~~~~~~~~~~~~\n\nupsdrvctl can also shut down (power down) all of your UPS hardware.\n\nWARNING: if 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/bin/upsdrvctl shutdown\n\t/usr/local/ups/bin/upsdrvctl shutdown sparky\n\nYou should read the \u003c\u003cUPS_shutdown,Configuring automatic UPS shutdowns\u003e\u003e\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 \u003c\u003cOutlets_PDU_notes,Configuring automatic UPS shutdowns\u003e\u003e\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:\n\nMaster\n~~~~~~\n\nThis UPS supplies power to the system running `upsmon`, and this system is also\nresponsible for shutting it down when the battery is depleted.  This occurs\nafter any slave systems have disconnected safely.\n\nIf your UPS is plugged directly into a system's serial port, the `upsmon`\nprocess on that system should define that UPS as a master.\n\nFor a typical home user, there's one computer connected to one UPS.\nThat means you run a driver, `upsd`, and `upsmon` in master mode.\n\nSlave\n~~~~~\n\nThis UPS may supply power to the system running `upsmon`, but this system can't\nshut it down directly.\n\nUse this mode when you run multiple computers on the same UPS.  Obviously, only\none can be connected to the serial port on the UPS, and that system is the\nmaster.  Everything else is a slave.\n\nFor a typical home user, there's one computer connected to one UPS.\nThat means you run a driver, upsd, and upsmon in master mode.\n\nAdditional Information\n~~~~~~~~~~~~~~~~~~~~~~\n\nMore information on configuring upsmon can be found in these places:\n\n- The linkman:upsmon[8] man page\n- \u003c\u003cBigServers,Typical setups for big servers\u003e\u003e\n- \u003c\u003cUPS_shutdown,Configuring automatic UPS shutdowns\u003e\u003e 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 linkman:upsc[8] man page and\n\u003c\u003cnut-names,NUT command and variable naming scheme\u003e\u003e 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\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\nOn the other hand, one that doesn't support them won't print anything:\n\n\t$ upsrw fenton@gearbox\n\n\t( nothing )\n\n`upsrw` requires administrator powers to change settings in the hardware.\nRefer to linkman:upsd.users[5] 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\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`upscmd` requires administrator powers to start instant commands.\nTo define users and passwords in `upsd`, see\nlinkman:upsd.users[5].\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\thttp://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\thttp://www.libpng.org/pub/png/pngcode.html\n\n\thttp://www.gzip.org/zlib/\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 work like this: if the middle number is odd, it's a\ndevelopment 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 stable tree designated 2.6.  The development trees were 1.1, 1.3,\n1.5, 2.1 and 2.3.  As of the 2.4 release, there is no real development\nbranch anymore since the code is available through a revision control\nsystem (namely Subversion) and snapshots.\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\n\nBackwards and Forwards Compatibility\n------------------------------------\n\nThe old network code spans a range from about 0.41.1 when TCP support \nwas introduced up to the recent 1.4 series.  It used variable names\nlike STATUS, UTILITY, and LOADPCT.  Many of these names go back to the\nearliest prototypes of this software from 1997.  At that point there\nwas no way to know that so many drivers would come along and introduce \nso many new variables and commands.  The resulting mess grew out of\ncontrol over the years.\n\nDuring the 1.3 development cycle, all variables and instant commands\nwere renamed to fit into a tree-like structure.  There are major groups,\nlike input, output and battery.  Members of those groups have been\narranged to make sense - input.voltage and output.voltage compliment\neach other.  The old names were UTILITY and OUTVOLT.  The benefits in\nthis change are obvious.\n\nThe 1.4 clients can talk to either type of server, and can handle either\nnaming scheme.  1.4 servers have a compatibility mode where they can\nanswer queries for both names, even though the drivers are internally\nusing the new format.\n\nWhen 1.4 clients talk to 1.4 or 2.0 (or more recent) servers, they will\nuse the new names.\n\nHere's a table to make it easier to visualize:\n\n[options=\"header\"]\n|=============================================\n|                   4+| Server version\n| *Client version*    | 1.0 | 1.2 | 1.4 | 2.0+\n| 1.0                 | yes | yes | yes | no\n| 1.2                 | yes | yes | yes | no\n| 1.4                 | yes | yes | yes | yes\n| 2.0+                | no  | no  | yes | yes\n|=============================================\n\nVersion 2.0, and more recent, do not contain backwards compatibility for\nthe old protocol and variable/command names.  As a result, 2.0 clients can't \ntalk to anything older than a 1.4 server.  If you ask a 2.0 client to \nfetch \"STATUS\", it will fail.  You'll have to ask for \"ups.status\" \ninstead.\n\nAuthors of separate monitoring programs should have used the 1.4 series\nto write support for the new variables and command names.  Client\nsoftware can easily support both versions as long as they like.  If upsd\nreturns 'ERR UNKNOWN-COMMAND' to a GET request, you need to use REQ.\n\n\nSupport / Help / etc.\n---------------------\n\nIf you are in need of help, refer to the\n\u003c\u003cSupport_Request,Support instructions\u003e\u003e in the user manual.\n\n\nHacking / Development Info\n--------------------------\n\nAdditional documentation can be found in:\n\n- the linkdoc:developer-guide[Developer Guide],\n- the linkdoc:packager-guide[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 \u003c\u003cAcknowledgements,acknowledgements appendix\u003e\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-archive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetworkupstools%2Fnut-archive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetworkupstools%2Fnut-archive/lists"}