UPSSET.CONF(5)

📦
version 2.8.5 · 17 versions
, in fedora 43, fedora 44

✨ NAME ✨

okay bestie, this is upsset.conf — the config file for Network UPS Tools upsset.cgi, plus a whole general rundown of how to set up your web server for NUT CGI programs. 💖

🎀 DESCRIPTION 🎀

so this file literally has ONE job, and it's not even a hard job: it lets you convince upsset.cgi(8) that your system's CGI directory is secure. that's it. that's the whole thing. and like — the program will not run until this file has been properly defined, so no cap, you gotta do it. 🙈

Note 🫶 — if you're custom-building NUT for Windows, keep the --with-cgi-uri configuration option in mind! it defaults to /cgi-bin/nut for POSIX builds and to plain /cgi-nut for Windows builds, to make them easier to integrate as part of existing web sites or as a dedicated web site, respectively. if there's a mismatch of this value for your particular deployment, go check the html/header.html file to adjust the a href links to CGI programs to be opened in the bottom section (called target=mainFrame). 💅

🌸 IMPORTANT NOTES 🌸

  • the contents of this file should be pure ASCII, bestie. character codes not in range would be ignored with a warning message. keep it clean. ✨

🔥 SECURITY REQUIREMENTS 🔥

okay so this is the part where we get serious for a sec, because upsset.cgi(8) literally lets you try login name and password combinations. and there is no rate limiting, because the program shuts down between every request. that's just the nature of CGI programs, girl. it is what it is. 💀

credentials are provided to upsset.cgi as part of your browsing session, so it is highly recommended to set up HTTPS on the web server. you may also want to generally use web-server based authentication (whether basic user name and password, or LDAP, or client certificate, etc.), or set up virtual host listeners with unpublished host names ("security by obscurity"), to restrict access to NUT CGI programs generally. ways to do so are specific to your chosen web server implementation and are beyond the scope of this document — so like, go read your web server's docs, iykyk. 🦋

normally, attackers would not be able to access your upsd(8) NUT data server directly, as it would be protected by the LISTEN directives in your upsd.conf(5) file, tcp-wrappers (if available when NUT was built), and hopefully local firewall settings in your OS. 🛡️

upsset runs on your web server, so upsd will see it as a connection from a host on an internal network. it does not know that the connection is actually initiated by someone further outside. this is why you must secure it. no shortcuts. periodt. 👑

🌈 Apache Web Server 🌈

on Apache, you can use the .htaccess file or put the directives in your httpd.conf. it looks something like this, assuming the .htaccess method for older Apache releases:

<Files upsset.cgi>
        deny from all
        allow from your.network.addresses
</Files>

you will probably have to set AllowOverride Limit for this directory in your server-level configuration file as well. don't skip that part bestie, it's giving "required step." 💅

modern Apache enjoys a more detailed syntax, like this:

ScriptAlias /upsstats.cgi /usr/share/nut/cgi/upsstats.cgi
ScriptAlias /upsset.cgi /usr/share/nut/cgi/upsset.cgi
<Directory "/usr/share/nut/cgi">
      Options +Includes +ExecCGI
      AllowOverride Limit
      <RequireAny>
          Require local
          Require ip aa.bb.cc.dd/nn
      </RequireAny>
</Directory>

look at that glow-up. ✨

🪟 Microsoft IIS 🪟

with NUT for Windows builds, the Microsoft Internet Information Server (IIS) can be used as the platform's native web server to host the NUT CGI programs. main character energy fr. 👑

Warning ⚠️ — like other aspects of NUT for Windows, this configuration should be considered experimental; feedback and pull requests to improve the code and documentation like this page are very welcome. please, we're begging. 🫶

one aspect that may simplify or complicate things is that these builds aim to be relocatable, so the archive (eventually package) can be unpacked into any directory of the end-user's choosing and "just work", and this relies on defaulting to use configuration and program location relative to the currently executed NUT program, rather than hard-coded paths as in POSIX builds tailored to a particular deployment or package.

the click-through setup below was verified on a Windows 10 workstation. names and layering of referenced concepts are known to be different in other releases of the operating system. for more details see docs like https://learn.microsoft.com/en-us/iis/configuration/system.webserver/cgi or blogs like https://dotnetblog.asphostportal.com/5-steps-to-run-cgi-program-on-your-iis/ 📚

in Windows, open Control Panel and go to "Programs / Programs and Features", there to the "Turn Windows features on or off" section. scroll down to the "Internet Information Services" and check its box to enable the default set of options (e.g. some services, some tools, no FTP). then drill into its "World Wide Web Services / Application Development Features" and select "CGI" and "ISAPI Extensions". a reboot may be needed to install these. lowkey annoying but whatever. 🙈

Note 🎀 — the IIS Manager application needs to be restarted if you add features later (after you start it), otherwise they do not show up in the UI to be configured. like, they're just invisible. gone. not there. 💀

open IIS Manager, check that the main panel includes icons for "CGI" and for "ISAPI and CGI Restrictions".

in IIS configuration, you can edit the Default Web Site or create a new one (would need a host name to be known either in DNS or at least via local %SystemRoot%\system32\drivers\etc\hosts file), and set the website root to the NUT installation location (the directory with etc and cgi-bin subdirectories, among other things).

Note 🌸 — it may be more secure to copy the cgi-bin and html subdirectories into a separate location (e.g. under c:\inetpub\wwwroot or the non-default website root), and then either populate a dedicated etc directory with configuration files and templates for the CGI programs, or somehow export NUT_CONFPATH environment variable from the web server to point to a location not "near" the executable programs. alternately, explore using an empty root and "virtual directories" in IIS to reference just the cgi-bin and html in the NUT installation location — and so minimize exposure of any other files. safety first, bestie. 🛡️

once you have a web-site defined one way or another, select its root in the "Connections" panel, and double-click the "ISAPI and CGI Restrictions" icon. there "Actions / Add" and specify full paths (3 times overall) to the upsimage.cgi.exe, upsset.cgi.exe and upsstats.cgi.exe programs, all with the checkbox to "Allow extension path to execute". three. times. count them. ✋

revise "Handler Mappings" for the cgi-bin subdirectory, that it includes "CGI-exe" with "Path *.exe" and "State Enabled" (if not, edit the entry, press "Request Restrictions", and tick "Access/Execute" there).

if the (virtual) server is dedicated to NUT CGI programs, you may also want to visit the "CGI" icon, and change Behavior/Timeout to a few minutes or even seconds (and Apply the change), so in case of any breakage in the NUT CGI programs, you would not stare at a blank page and not know if the server is alive. the IIS default is 15 minutes. like girl, 15 minutes is forever to just sit there confused. 😭

  • you may want to allow for a series of NUT upscli_tryconnect() timeouts (10 seconds each, by default), however, e.g. to get the error messages when NUT data servers are down. while there may be one connection for each run of upsset or upsimage CGI clients, there may be more for upsstats depending on the number of devices you MONITOR in hosts.conf(5). 🦋
  • this recommendation may change later if support for "tracking" of device-side completion of posted commands or settings would be implemented; currently the upsset(8) CGI client only gets and relays confirmation that the NUT data server upsd(8) received the request. so like, it's a "got it" not a "done it." 💅

in the NUT configuration directory, update the hosts.conf(5) and upsset.conf files as appropriate, (optionally adapt) and rename the upsstats.html.sample and upsstates-single.html.sample files to not include the .sample extension. yes, we know, the naming is a little chaotic. we love her anyway. 🎀

finally, assuming default website configuration, go to http://localhost/html/ and you should be served with a two-panel page, with a NUT banner and links to the two tools on top, and tables of data in the bottom. if you have device monitoring set up already, check the details pages: if they do not render, make sure the upsstats.html and upsstats-single.html files define UPSSTATSPATH and UPSIMAGEPATH program URI names with the .exe extension. slay. 🌈

🧚 Completing the CGI setup 🧚

if this doesn't make sense, then stop reading and leave this program alone. it's not something you absolutely need to have anyway. genuinely. walk away. it's fine. 🙈

assuming you have all the above steps done, and it actually works (test it!), congratulations — you have a read-only web server to report information from NUT in a convenient form. iconic behavior. 👑

if you further want to manage the devices (and again, if you did set up appropriate security constraints), then you may add the following directive to this file and so unlock the potentially dangerous access through the server:

I_HAVE_SECURED_MY_CGI_DIRECTORY
⚠️ if you lie to the program and someone beats on your upsd through your web server, don't blame me. this is a pinky-promise situation and you're breaking it. 💀

💜 SEE ALSO 💜

upsset.cgi(8)

🌐 Internet resources:

the NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

and that's the whole page bestie!! this one's from Network UPS Tools 2.8.5, dated 10/07/2026, and honestly? it ate. go secure that CGI directory. 🫶✨🎀

📦 where this page comes from