Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork423
The Network UPS Tools repository. UPS management protocol Informational RFC 9271 published by IETF athttps://www.rfc-editor.org/info/rfc9271 Please star NUT on GitHub, this helps with sponsorships!
License
Unknown and 3 other licenses found
Licenses found
networkupstools/nut
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Network UPS Tools is a collection of programs which provide a commoninterface 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. Theyunderstand the specific language of each device and map it back to acompatibility layer. This means both an expensive high end UPS, a simple"power strip" PDU, or any other power device can be handled transparentlywith a uniform management interface.
This information is cached by the network serverupsd, which thenanswers queries from the clients. upsd contains a number of accesscontrol features to limit the abilities of the clients. Only authorizedhosts may monitor or control your hardware if you wish. Since thenotion of monitoring over the network is built into the software, youcan hang many systems off one large UPS, and they will all shut downtogether. You can also use NUT to power on, off or cycle your data centernodes, individually or globally through PDU outlets.
Clients such asupsmon check on the status of the hardware and do thingswhen necessary. The most important task is shutting down the operatingsystem cleanly before the UPS runs out of power. Other programs arealso provided to log information regularly, monitor status through yourweb browser, and more.
NUT comes pre-packaged for many operating systems and embedded in storage,automation or virtualization appliances, and is also often shipped as thesoftware companion by several UPS vendors. Of course, it is quite normaland supported to build your own — whether for an operating system whichlacks it yet, or for an older distribution which lacks the current NUTversion; whether to take advantage of new features or to troubleshoot anew UPS deployment with a debugger in hand.
Given its core position at the heart of your systems' lifecycle, we makeit a point to have current NUT building and running anywhere, especiallywhere older releases did work before (including "abandonware" like theservers and OSes from the turn of millennium): if those boxes are stillalive and in need of power protection, they should be able to get it.
Tip | If you like how the NUT project helps protect your systems from poweroutages, please consider sponsoring or at least "starring" it on GitHub athttps://github.com/networkupstools/nut/ - these stars are among metricswhich the larger potential sponsors consider when choosing how to helpFOSS projects. Keeping the lights shining in such a large non-regressionbuild matrix is a big undertaking! Seeacknowledgements of organizations which helpwith NUT CI and other daily operations for an overview of the shared effort. |
As a FOSS project, for over a quarter of a century we welcome contributionsof both core code (drivers and other features), build recipes and otherintegration elements to make it work on your favourite system, documentationrevisions to make it more accessible to newcomers, as well as hardware vendorcooperation with first-hand driver and protocol submissions, and just aboutanything else you can think of.
The Network UPS Tools project is a community-made open-source effort, primarilymade and maintained by people donating their spare time.
The support channels are likewise open, with preferred ones beingthe NUT project issuetracker on GitHub and the NUT Users mailing list, as detailed athttps://networkupstools.org/support.html page.
Please keep in mind that any help is provided by community members just likeyourself, as a best effort, and subject to their availability and experience.It is expected that you have read the Frequently Asked Questions, looked attheNUT wiki, and have agood grasp about the three-layer design and programs involved in a runningdeployment of NUT, for a discussion to be constructive and efficient.
Be patient, polite, and prepare to learn and provide information about yourNUT deployment (version, configuration, OS…) and the device, to collectlogs, and to answer any follow-up questions about your situation.
Finally, note that NUT is packaged and delivered by packaging into numerousoperating systems, appliances and monitoring projects, and may be bundledwith third-party GUI clients. It may be wise of end-users to identify suchcases and ask for help on the most-relevant forum (or several, including theNUT support channels). It is important to highlight that the NUT projectreleases have for a long time been essentially snapshots of better-testedcode, and we do not normally issue patches to "hot-fix" any older releases.
Any improvements of NUT itself are made in the current code base, same asany other feature development, so to receive desired fixes on your system(and/or to check that they do solve your particular issue), expect to beasked to build the recent development iteration from GitHub or work withyour appliance vendor to get a software upgrade.
Over time, downstream OS packaging or other integrations which use NUT, mayissue patches as new package revisions, or new baseline versions of NUT,according totheir release policies. It is not uncommon for distributions,especially "stable" flavours, to be a few years behind upstream projects.
If you are installing these programs for the first time, go read theinstallation instructionsto find out how to do that. This document contains more informationon what all of this stuff does.
When upgrading from an older version, always check theupgrading notes to see what may havechanged. Compatibility issues and other changes will be listed thereto ease the process.
Once NUT is installed, refer to theconfiguration notes for directions.
This is just an overview of the software. You should read the man pages,included example configuration files, and auxiliary documentation for theparts that you intend to use.
These programs are designed to share information over the network. Inthe examples below,localhost is used as the hostname. This can alsobe an IP address or a fully qualified domain name. You can specify aport number if your upsd process runs on another port.
In the case of the programupsc, to view the variables on the UPS calledsparky on theupsd server running on the local machine, you’d do this:
/usr/local/ups/bin/upsc sparky@localhost
The default port number is 3493. You can change this with"configure --with-port" at compile-time. To make a client talk to upsdon a specific port, add it after the hostname with a colon, like this:
/usr/local/ups/bin/upsc sparky@localhost:1234
This is handy when you have a mixed environment and some of the systemsare on different ports.
The general form for UPS identifiers is this:
<upsname>[@<hostname>[:<port>]]
Keep this in mind when viewing the examples below.
This package is broken down into several categories:
drivers- These programs talk directly to your UPS hardware.
server- upsd serves data from the drivers to the network.
clients- They talk to upsd and do things with the status data.
cgi-bin- Special class of clients that you can use with your web server.
scripts- Contains various scripts, like the Perl and Python binding,integration bits and applications.
These programs provide support for specific UPS models. They understandthe protocols and port specifications which define status informationand convert it to a form that upsd can understand.
To configure drivers, edit ups.conf. For this example, we’ll have a UPScalled "sparky" that uses the apcsmart driver and is connected to/dev/ttyS1. That’s the second serial port on most Linux-based systems.The entry inups.conf looks like this:
[sparky]driver = apcsmartport = /dev/ttyS1
To start and stop drivers, use upsdrvctl of upsdrvsvcctl (installed onoperating systems with a service management framework supported by NUT).By default, it will start or stop every UPS in the config file:
/usr/local/ups/sbin/upsdrvctl start/usr/local/ups/sbin/upsdrvctl stop
However, you can also just start or stop one by adding its name:
/usr/local/ups/sbin/upsdrvctl start sparky/usr/local/ups/sbin/upsdrvctl stop sparky
On operating systems with a supported service management framework,you might wrap your NUT drivers into individual services instanceswith:
/usr/local/ups/sbin/upsdrvsvcctl resync
and then manage those service instances with commands like:
/usr/local/ups/sbin/upsdrvsvcctl start sparky/usr/local/ups/sbin/upsdrvsvcctl stop sparky
To find the driver name for your device, refer to the section belowcalled "HARDWARE SUPPORT TABLE".
Some drivers may require additional settings to properly communicatewith your hardware. If it doesn’t detect your UPS by default, check thedriver’s man page or help (-h) to see which options are available.
For example, the usbhid-ups driver allows you to use USB serial numbers todistinguish between units via the "serial" configuration option. To use thisfeature, just add another line to your ups.conf section for that UPS:
[sparky]driver = usbhid-upsport = autoserial = 1234567890
TheHardware Compatibility List is available in the source directory(nut-X.Y.Z/data/driver.list), and is generally distributed with packages.For example, it is available on Debian systems as:
/usr/share/nut/driver.list
This table is also availableonline.
If your driver has vanished, see theFAQ andUpgrading notes.
NUT provides several generic drivers that support a variety of very similarmodels.
The
genericupsdriver supports many serial models that use the same basicprinciple to communicate with the computer. This is known as "contactclosure", and basically involves raising or lowering signals to indicatepower status.This type of UPS tends to be cheaper, and only provides the very simplestdata about power and battery status. Advanced features like batterycharge readings and such require a "smart" UPS and a driver whichsupports it.
See thegenericups(8) man page for more information.
The
usbhid-upsdriver attempts to communicate with USB HID Power DeviceClass (PDC) UPSes. These units generally implement the same basic protocol,with minor variations in the exact set of supported attributes. This driveralso applies several correction factors when the UPS firmware reports valueswith incorrect scale factors.See theusbhid-ups(8) man page for more information.
The
nutdrv_qxdriver supports the Megatec / Q1 protocol that is used inmany brands (Blazer, Energy Sistem, Fenton Technologies, Mustek, VoltronicPower and many others).See thenutdrv_qx(8) man page for more information.
The
snmp-upsdriver handles various SNMP enabled devices, from manydifferent manufacturers. In SNMP terms,snmp-upsis a manager, thatmonitors SNMP agents.See thesnmp-ups(8) man page for more information.
The
powerman-pduis a bridge to the PowerMan daemon, thus handling allPowerMan supported devices. The PowerMan project supports several serialand networked PDU, along with Blade and IPMI enabled servers.See thepowerman-pdu(8) man page for moreinformation.
The
apcupsd-upsdriver is a bridge to the Apcupsd daemon, thus handlingall Apcupsd supported devices. The Apcupsd project supports many serial,USB and networked APC UPS.See theapcupsd-ups(8) man page for more information.
upsdrvctl can also shut down (power down) all of your UPS hardware.
Warning | If you play around with this command, expect your filesystemsto die. Don’t power off your computers unless they’re ready for it: /usr/local/ups/sbin/upsdrvctl shutdown/usr/local/ups/sbin/upsdrvctl shutdown sparky |
You should read theConfiguring automatic UPS shutdownschapter to learn more about when to use this feature. If called at the wrongtime, you may cause data loss by turning off a system with a filesystemmounted read-write.
NUT also provides an advanced support for power distribution units.
You should read theNUT outlets management and PDU noteschapter to learn more about when to use this feature.
upsd is responsible for passing data from the drivers to the clientprograms via the network. It should be run immediately afterupsdrvctlin your system’s startup scripts.
upsd should be kept running whenever possible, as it is the only sourceof status information for the monitoring clients likeupsmon.
upsmon provides the essential feature that you expect to find in UPSmonitoring software: safe shutdowns when the power fails.
In the layered scheme of NUT software, it is a client. It has thisseparate section in the documentation since it is so important.
You configure it by telling it about UPSes that you want to monitor inupsmon.conf. Each UPS can be defined as one of two possible types:a "primary" or "secondary".
The monitored UPS possibly supplies power to this system runningupsmon,but more importantly — this system can manage the UPS (typically, thisinstance ofupsmon runs on the same system as theupsd and driver(s)):it is capable and responsible for shutting it down when the battery isdepleted (or in another approach, lingering to deplete it or to tell theUPS to reboot its load after too much time has elapsed and this systemis still alive — meaning wall power returned at a "wrong" moment).
The shutdown of this (primary) system itself, as well as eventually anUPS shutdown, occurs after any secondary systems ordered to shut downfirst have disconnected, or a critical urgency threshold was passed.
If your UPS is plugged directly into a system’s serial or USB port, theupsmon process on that system should define its relation to that UPSas a primary. It may be more complicated for higher-end UPSes with ashared network management capability (typically via SNMP) or severalserial/USB ports that can be used simultaneously, and depends on whatvendors and drivers implement. Setups with several competing primaries(for redundancy) are technically possible, if each one runs its ownfull stack of NUT, but results can be random (currently NUT does notprovide a way to coordinate several entities managing the same device).
For a typical home user, there’s one computer connected to one UPS.That means you would run on the same computer the whole NUT stack — a suitable driver,upsd, andupsmon in primary mode.
The monitored UPS may supply power to the system runningupsmon (oralternatively, it may be a monitoring station with zero PSUs fed bythat UPS), but more importantly, this system can’t manage the UPS — e.g. shut it down directly (through a locally running NUT driver).
Use this mode when you run multiple computers on the same UPS.Obviously, only one can be connected to the serial or USB porton a typical UPS, and that system is the primary. Everythingelse is a secondary.
For a typical home user, there’s one computer connected to one UPS.That means you run a driver,upsd, andupsmon in primary mode.
More information on configuring upsmon can be found in these places:
Theupsmon(8) man page
The stock
upsmon.confthat comes with the package
Clients talk to upsd over the network and do useful things with the datafrom the drivers. There are tools for command line access, and a fewspecial clients which can be run through your web server as CGIprograms.
For more details on specific programs, refer to their man pages.
upsc is a simple client that will display the values of variables knowntoupsd and your UPS drivers. It will list every variable by default,or just one if you specify an additional argument. This can be usefulin shell scripts for monitoring something without writing your ownnetwork code.
upsc is a quick way to find out if your driver(s) and upsd are workingtogether properly. Just runupsc <ups> to see what’s going on, i.e.:
morbo:~$ upsc sparky@localhostambient.humidity: 035.6ambient.humidity.alarm.maximum: NO,NOambient.humidity.alarm.minimum: NO,NOambient.temperature: 25.14...
If you are interested in writing a simple client that monitorsupsd,the source code forupsc is a good way to learn about using theupsclient functions.
See theupsc(8) man page andNUT command and variable naming scheme for more information.
upslog will write status information fromupsd to a file at setintervals. You can use this to generate graphs or reports with otherprograms such asgnuplot.
upsrw allows you to display and change the read/write variables in yourUPS hardware. Not all devices or drivers implement this, so this maynot have any effect on your system.
A driver that supports read/write variables will give results like this:
$ upsrw sparky@localhost( many skipped )[ups.test.interval]Interval between self testsType: ENUMOption: "1209600"Option: "604800" SELECTEDOption: "0"( more skipped )
On the other hand, one that doesn’t support them won’t print anything:
$ upsrw fenton@gearbox( nothing )
upsrw requires administrator powers to change settings in the hardware.Refer toupsd.users(5) for information on definingusers inupsd.
Some UPS hardware and drivers support the notion of an instant command -a feature such as starting a battery test, or powering off the load.You can use upscmd to list or invoke instant commands if yourhardware/drivers support them.
Use the -l command to list them, like this:
$ upscmd -l sparky@localhostInstant commands supported on UPS [sparky@localhost]:load.on - Turn on the load immediatelytest.panel.start - Start testing the UPS panelcalibrate.start - Start run time calibrationcalibrate.stop - Stop run time calibration...
upscmd requires administrator powers to start instant commands.To define users and passwords inupsd, seeupsd.users(5).
The CGI programs are clients that run through your web server. Theyallow you to see UPS status and perform certain administrative commandsfrom any web browser. Javascript and cookies are not required.
These programs are not installed or compiled by default. To compileand install them, first runconfigure --with-cgi, then domake andmake install. If you receive errors about "gd" during configure, goget it and install it before continuing.
You can get the source here:
In the event that you need libpng or zlib in order to compile gd,they can be found at these URLs:
The CGI programs use hosts.conf to see if they are allowed to talk to ahost. This keeps malicious visitors from creating queries from your webserver to random hosts on the Internet.
If you get error messages that say "Access to that host is notauthorized", you’re probably missing an entry in your hosts.conf.
upsstats generates web pages from HTML templates, and plugs in statusinformation in the right places. It looks like a distant relative ofAPC’s old Powerchute interface. You can use it to monitor severalsystems or just focus on one.
It also can generate IMG references toupsimage.
This is usually called by upsstats via IMG SRC tags to draw either theutility or outgoing voltage, battery charge percent, or load percent.
upsset provides several useful administration functions through a webinterface. You can useupsset to kick off instant commands on your UPShardware like running a battery test. You can also use it to changevariables in your UPS that accept user-specified values.
Essentially,upsset provides the functions ofupsrw andupscmd, butwith a happy pointy-clicky interface.
upsset will not run until you convince it that you have secured yoursystem. Youmust secure your CGI path so that random interloperscan’t run this program remotely. See theupsset.conf file. Once youhave secured the directory, you can enable this program in thatconfiguration file. It is not active by default.
The version numbers historically worked like this: if the middle numberis odd, it’s a development tree, otherwise it is the stable tree.
The past stable trees were 1.0, 1.2, 1.4, 2.0, 2.2 and 2.4, with thelatest such stable tree designated 2.6. The development trees were 1.1,1.3, 1.5, 2.1 and 2.3. Since the 2.4 release, there is no real separatedevelopment branch anymore since the code is available through a revisioncontrol system (namely, Git — or actually Subversion back then), developmenthappens in feature branches that are eventually merged into the main trunk,and its snapshots become published releases. As a result, subsequent versions(2.7 and 2.8) were released without regard for even/odd values of the minorversion component.
Since 2.7 line of releases, sources are tracked in Git revision controlsystem, with the project ecosystem being hosted on GitHub, and any codeimprovements or other contributions merged through common pull requestapproach and custom NUT CI testing on multiple platforms.
Major release jumps are mostly due to large changes to the featureslist. There have also been a number of architectural changes whichmay not be noticeable to most users, but which can impact developers.
Since NUT v2.8.2 or so, development iterations have additional versioncomponents, to account for the amount of commits on the main branch(master) since the last known Git tag, and amount of commits on thedeveloped feature branch that are unique to it compared to main branch.This allows for a reasonably growing version of stable baseline andlocal development, so that experimental packages can be installed asupgrades (or well-exposed downgrades).
While the NUT releases retain the semantic versioning three-componentstandard, interim builds (trunk snapshots and development branches)can expose a much more complex structure with the amount of commitsin the trunk since last release, and amount of commits on the branchunique to it (not in the trunk). Additional data may include overallamount of commits in the current build since last release, and thegit commit has identifier of the built code base.
More details can be seen indocs/nut-versioning.adoc file in theNUT source code base.
The network protocol for the current version of NUT should bebackwards-compatible all the way back to version 1.4. A newer client shouldfail gracefully when querying an older server.
If you need more details about cross-compatibility of older NUT releases(1.x vs. 2.x), please see theProject history chapter.
If you are in need of help, refer to theSupport instructions in the user manual.
Additional documentation can be found in:
theDeveloper Guide,
thePackager Guide.
The many people who have participated in creating and improving NUT arelisted in the user manualacknowledgements appendix.
We would like to highlight some organizations which provide continuoussupport to the NUT project (and many other FOSS projects) on technologicaland organizational sides, such as helping keep the donations transparent,NUT CI farm afloat, and public resources visible. Thanks for keeping theclocks ticking, day and night:
|
The"NetworkUPSTools" organization on GitHub arranges a lot of things, including source code hosting for NUT itself and several related projects, team management, projects, issue and pull request discussions, sponsorship, nut-website rendering and hosting, some automated actions, and more… |
|
TheJenkins CI project and its huge plugin ecosystem provides the technological foundation for the largest island of theself-hosted NUT CI farm. There is a fair amount of cross-pollination between the upstream project and community, and the development done originally for the NUT CI farm. See more atJenkins is the way to build multi-platform NUT article. |
|
TheDigitalOcean droplets allow us to host NUT CI farm Jenkins controller and the build agents for multiple operating systems. They are essentially virtual machines where the multi-platform NUT CI farm with ajenkins-dynamatrixsetup runs to arrange builds in numerous operating environments and a lot of toolkit versions and implementations. Some workers running on NUT community members' machines can also dial in to provide an example of their favourite platforms. Literally hundreds of NUT builds run for each iteration, to make sure NUT can always build and work everywhere. This allows us to ensure that NUT remains portable across two decades' worth of operating systems, compilers, script interpreters, tools and third-party dependencies. |
|
The several variants ofOBS NUT packaging project hosted on theopenSUSE Build Service (OBS) allow us to propose reference packaging recipes for a number of Linux distributions, as well as to test NUT PR and stable branch iterations on those across several CPU architectures not available elsewhere. |
|
TheCircleCI NUT pipeline allows us to test NUT CI builds on MacOS. |
|
TheAppVeyor NUT pipeline allows us to test NUT CI builds on Windows (and publish preview tarballs with binaries). |
|
Fosshost used to provide virtual machines where the multi-platform NUT CI farm ran, following up from a take on multi-platform builds with Travis CI while it was free for FOSS projects. In turn, DigitalOcean helped us move on from there after the Fosshost project went defunct. |
|
Gandi.Net ultimately took up the costs of NUT DNS hosting, which they have provided commercially for years before that. |
|
https://opencollective.com/networkupstools allows us to arrange monetary donations and spending, with public transparency of everything that happens. |
About
The Network UPS Tools repository. UPS management protocol Informational RFC 9271 published by IETF athttps://www.rfc-editor.org/info/rfc9271 Please star NUT on GitHub, this helps with sponsorships!
Topics
Resources
License
Unknown and 3 other licenses found
Licenses found
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Sponsor this project
Uh oh!
There was an error while loading.Please reload this page.
Packages0
Uh oh!
There was an error while loading.Please reload this page.