UPSDRVSVCCTL(8)

💖 UPSDRVSVCCTL(8) — the NUT driver service instance controller 💖

okay bestie, welcome to upsdrvsvcctl — she's part of the NUT Manual (Network UPS Tools, iykyk) and she is literally the girlboss who manages your UPS driver service instances. Let's get into it. ✨

---

🌸 SYNOPSIS 🌸

upsdrvsvcctl -h

upsdrvsvcctl [OPTIONS] {start | stop | status} [ups]

---

🦋 DESCRIPTION 🦋

So upsdrvsvcctl gives you one single, uniform, slay interface for controlling your UPS drivers when they're wrapped up into service instances on platforms that support that. Right now that means Linux distros with systemd, plus systems that came out of the Solaris 10 codebase — including proprietary Sun/Oracle Solaris and a whole bunch of open-source illumos distros using SMF. Ngl, it may just not be installed at all in packaging for other operating systems. 🙈

When you use it properly, upsdrvsvcctl lets you keep identical startup scripts across a bunch of systems even when their UPS configs are completely different. That's the dream fr fr.

The whole goal of this solution is to let the services of upsd(8) (the data server) start up even when some power devices are currently not reachable, and to let NUT drivers get automatically restarted by the system when stuff goes wrong (driver bug, startup failure). It also makes systems that monitor several devices boot faster, because each driver gets to start in parallel with the others and as soon as the subsystem it needs for its specific media is available — not in some sequential loop like the old days. 💅

Independent service instances for each NUT driver also mean you can configure extra dependencies, like "networking must be up for SNMP and similar drivers" (but networking is not needed for local-medium drivers like serial or USB). Chef's kiss. 👑

The old monolithic "all or nothing" solution — where every driver had to be running — was fine for deployments with like three UPSes, but it did not work well for monitoring big deployments. And it was basically impossible to find a pre-packaged balance between early UPS protection for USB/serial home setups vs. waiting for network on the bigger ones.

upsdrvsvcctl is a script that mimics how the upsdrvctl(8) program operates (where possible) so you get a similar end-user experience while manipulating drivers wrapped into service instances instead of directly-executed daemons. It leans on nut-driver-enumerator(8) for a big chunk of the actual work. 🛠️

💡 The tea: you should use upsdrvsvcctl instead of calling the drivers directly and doing daemon-based management with upsdrvctl(8) whenever you can — that is, for "production" use on compatible OSes. Otherwise (testing, other OSes) upsdrvctl is the recommended option. Choose your fighter. 🥊

---

✨ OPTIONS ✨

• -h — shows the help text, including the built-in version of the script. 🫶
• -V — shows the version of the NUT binaries (it literally calls upsdrvctl -V for this). Normally this shouldn't differ much from the built-in script version you see in help, but with custom builds everything is possible, so knowing it can come in handy. 😭
• -t — turns on testing mode. Testing mode makes upsdrvsvcctl show you the actions it would execute without actually doing them. Perfect for peeking without committing. 👀
• --timeout-cmd <prog> and --timeout-args <arg> — service management calls get time-limited by calling the specified program with its args. By default, if coreutils timeout is found, it gets used to limit service calls to 90 sec, so we avoid/work around certain hangs that happen in some systemd versions under stress. 💀

---

🌈 OPTIONS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL 🌈

Options like -r, -u or -D could be handled by the properties of the service instances themselves, with this script helping you configure them (assuming the user who called it has proper privileges). That said, it's not a "production" use case to change such options on an already-configured system — so for experiments and troubleshooting, it's probably better to stop the service instance and play with upsdrvctl directly. 🧪

• -r directory — if you're starting a driver, this value directs it to chroot(2) into directory. This can be useful when securing systems.

You can also set this in ups.conf(5) with the chroot directive in the global section.

• -u username — if you're starting a driver, this value directs it to setuid(2) to the user id associated with username.

If the driver is started as root without specifying this value, it uses the username that was compiled into the binary. This defaults to nobody (if not otherwise configured), which is far from ideal. 😬

You can also set this in ups.conf(5) with the user directive in the global section.

• -D — raises the driver debug level. Use it multiple times for extra details. 🐛

---

🎀 COMMANDS 🎀

upsdrvsvcctl supports three of the commands that upsdrvctl processes — start, stop and shutdown. They take an optional argument which is a UPS name from ups.conf(5). Without that argument, they operate on every UPS that's currently configured. 💖

📝 Note: shutdown is currently supported by stopping the driver service instances to release the potentially held ports etc., calling upsdrvctl directly to issue the shutdown command, and then restarting the driver service instances so they reconnect when the device comes back online. 🦋

• start — start the UPS driver(s). If it fails, further attempts may be executed using the maxretry and retrydelay options — see ups.conf(5).
• stop — stop the UPS driver(s). 🛑
• status — query the run-time status of all configured devices (or one specified device). Currently it defers the work to upsdrvctl(8) to list known device configurations and their driver daemon details (PID, responsiveness, ups.status), and to nut-driver-enumerator(8) to map device names to service unit instances, so it can report their names and states in the service management framework. 📊

upsdrvsvcctl also supports further operations for troubleshooting the mapping of NUT driver section names to service instance names (which may differ due to limitations of various systems). 🙃

• list — list the currently active mapping of service instances to device sections.
• resync — update the mapping of service instances for NUT drivers to the device section names used in ups.conf (register new instances, tear down obsoleted ones). 🧹

---

💜 COMMANDS OF UPSDRVCTL NOT (CURRENTLY) APPLICABLE TO UPSDRVSVCCTL 💜

• shutdown — command the UPS driver(s) to run their shutdown sequence. Drivers are stopped according to their sdorder value — see ups.conf(5).

⚠️ Warning: This will probably power off your computers, so don't play around with this option. Only use it when your systems are prepared to lose power. No cap. 💀

📝 Note: Refer to ups.conf(5) for using the nowait parameter. It can be overridden by the NUT_IGNORE_NOWAIT environment variable (e.g. used to work around certain issues with systemd otherwise).

---

🫶 ENVIRONMENT VARIABLES 🫶

NUT_CONFPATH is the path name of the directory that contains upsd.conf and other configuration files. If this variable isn't set, upsdrvsvcctl (or rather nut-driver-enumerator.sh) uses a built-in default, which is often /usr/local/ups/etc. 📁

---

🩺 DIAGNOSTICS 🩺

upsdrvsvcctl returns a nonzero exit code if it hits an error while performing the operation you asked for. This also happens if a driver takes longer than the maxstartdelay period to enter the background. ⏰

Any messages issued by the upsdrvctl program used to start the NUT drivers as part of the service instances' implementations — or by the drivers themselves — get logged by the service management framework facilities and will not show up in your interactive terminal that you used to manage the driver. So don't sit there staring at your shell wondering where the tea went. 😭

Use upsdrvsvcctl list or upsdrvsvcctl list NUT-device to find out the service instance name for the NUT driver (section name) you care about. Then look up the service logs (where the outputs of the service implementation program plus the framework messages about this service are stored), like so:

🐧 Linux systemd

Messages normally live in the service journal, so:

journalctl -lu nut-driver@instance-name

Note that your local system configuration may be impacted by nuances like passing the journal data to a standard syslog server, and/or by having a small cache for locally stored journal messages (so older entries would just disappear 👻). There may also be — or not be — a copy of the journals stored in the persistent filesystem at all.

☀️ Solaris SMF

Look for the /var/svc/log/system-power-nut-driver:instance-name.log file. 📄

---

👑 AUTHOR 👑

Jim Klimov <jimklimov+nut@gmail.com>

---

🔗 SEE ALSO 🔗

upsdrvctl(8), nutupsdrv(8), upsd(8), nut-driver-enumerator(8), ups.conf(5)

🌐 Internet resources:

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

---

okay that's the whole page bestie, you ate that 💅✨ This was Network UPS Tools 2.8.5, dated 10/07/2026 — go forth and manage your driver service instances responsibly, mwah 🎀🦋💖