UPSLOG(8)

💖 UPSLOG(8) — the NUT Manual's own status-logging queen 💅

okay so real talk: this is the upslog page from the NUT Manual (Network UPS Tools, if you're new here 🫶) — version 2.8.5 energy, and she is booked and busy keeping receipts on your UPS. let's get into it bestie ✨

---

🌸 NAME 🌸

upslog — the UPS status logger. that's it, that's the gig 🎀

---

🦋 SYNOPSIS 🦋

upslog -h

upslog [OPTIONS]

---

✨ DESCRIPTION ✨

okay so upslog is a daemon — a little background bestie that never sleeps (well, she does sleep(3), more on that later 👀) — and what she does is: poll a UPS at periodic intervals, grab the variables that interest you, format them all cute, and write them into a file. lowkey iconic 🎀

the default format string already includes variables that lots of common UPS models support, so you can just vibe with that out of the box. but if you wanna build your own, the deets are right down there ⬇️

---

💅 OPTIONS 💅

• -f format — monitor the UPS using this format string. please wrap format in quotes so your shell doesn't go splitting it up on you (rude of it, honestly). the valid escapes inside this string are:
  • %% — drop in a single "%" character. yes, just one. no cap.
  • %t — drop in a single TAB character (same energy as printf("\t"))
  • %TIME format% — drop in the time, formatted with strftime formatting
  • %ETIME% — drop in the number of seconds since the start of "Epoch", ala time_t. this is now a 10-digit number, bestie, she grew up 😭
  • %HOST% — drop in the local hostname
  • %UPSHOST% — drop in the host of the UPS being monitored (that's the <system> part of your logging specification, e.g. ups[@host[:port]])
  • %PID% — drop in the PID of upslog itself
  • %VAR varname% — drop in the value of variable varname. (see the NUT developer documentation chapter "Variables" on-line, or the docs/nut-names.txt file in the sources of the NUT version you have installed, for more details)

and the default format string is literally this, verbatim:

%TIME @Y@m@d @H@M@S% %VAR battery.charge% %VAR input.voltage%
%VAR ups.load% [%VAR ups.status%] %VAR ups.temperature%
%VAR input.frequency%

• -N — prefix %UPSHOST%%t before the format string (whether that's the default one or your custom one). super useful when you're logging a whole bunch of systems into the same target.

note 🫶 this option DOES NOT currently check if you already have %UPSHOST% in the formatting string (like, if you specified it explicitly yourself). so you might end up with two. just so you know 💀

• -i interval — wait this many seconds between polls. -i defaults to 30 seconds.

if you require tighter timing, consider writing your own logger using the upsclient(3) library. (fancy!)

• -d count — exit after the specified amount of updates. default is 0, which means infinite loop (until interrupted otherwise). she'll go forever, fr fr 🔥
• -l logfile — store the results in this file.

you can use - for stdout, but heads up: upslog will remain in the foreground by default.

requires that the -s <system> option is also used for the single-system logging.

can be used with the -m <tuple>, and it'll be added to the list.

• -D — raise the debugging verbosity level by one; upslog will remain in the foreground by default.
• -F — upslog will run in the foreground, regardless of logging target. main character energy, no hiding 💅
• -B — upslog will run in the background, regardless of logging target or debugging.
• -s ups — monitor this UPS. the format for this option is upsname[@hostname[:port]]. the default hostname is "localhost".

the upsname may be an asterisk * to query UPSes currently served by hostname, and monitor each of them (into the same logging destination). slay, collect them all 🌈

requires that the -l <logfile> option is also used for the single-system logging.

can be used with the -m <tuple>, and it'll be added to the list.

• -m tuple — monitor multiple UPSs (provided as several instances of this option). yes, you can repeat it. go off 👑

the format for this option is a tuple of UPS system and log file specification, separated by commas. an example would be:

upsname@hostname:9999,/var/log/nut/cps.log

the upsname may be an asterisk * to query UPSes currently served by hostname, and monitor each of them (into the same logging destination).

tuples may specify - as the logfile, to emit messages on stdout (e.g. to be collected by the system journal for services).

use of stdout via tuple-based logging specifications also implies that upslog will remain in the foreground by default.

• -u username — if started as root, upslog will setuid(2) to the user id associated with username for security. responsible queen 🫶

if username is not defined, it will use the value that was compiled into the program. this defaults to nobody (if not otherwise configured), which is far from ideal. like. far. 😭

---

🎀 COMMON OPTIONS 🎀

• -h — show the command-line help message.
• -V — show the NUT version banner. more details may be available if you also export NUT_DEBUG_LEVEL=1 or a greater verbosity level.
• -W secs — set the timeout for initial network connections (by default they are indefinitely non-blocking, or until the system interrupts the attempt). overrides the optional NUT_DEFAULT_CONNECT_TIMEOUT environment variable.

---

⏰ SERVICE DELAYS ⏰

so here's the tea: the interval value is merely the number given to sleep(3) after running through the format string. which means a query will actually take slightly longer than the interval, depending on the speed of your system. she's doing her best 💀

---

🦋 ON-DEMAND LOGGING 🦋

sending a SIGUSR1 to a running upslog process makes it wake from the current sleep and log immediately. so good ✨

this is useful when triggered from a upssched event trigger (e.g. AT ONBATT or AT ONLINE) to ensure that an entry always exists — even if the power goes away for a period of time shorter than that specified by the -i argument. no missing receipts, periodt 🔥

---

🌸 LOG CO-LOCATION 🌸

it is possible and safe to specify the same log file (including - for stdout) in several tuples, and it would only be opened or closed once, without conflict. teamwork makes the dream work 🫶

consider adding %UPSHOST% to your custom formatting string (e.g. by using the -N command-line option), in order to easily differentiate lines corresponding to different systems when logging them to the same target. iykyk 💅

---

🧚 LOG ROTATION 🧚

upslog writes its PID to upslog.pid, and will reopen the log file if you send it a SIGHUP. this allows it to keep running when the log is rotated by an external program. adaptive icon behavior 👑

---

💀 CAVEATS 💀 (read these bestie, seriously)

historically, this daemon supported logging of data for one UPS system per run (specified by the -s option) into one log file name or stdout (specified by the -l option).

since NUT v2.8.1 it allowed logging several devices (each logged into its individual destination file or common stdout) as specified by multiple -m tuple options. but the two modes were effectively exclusive of each other (single-UPS options were ignored if tuples are also provided). awkward 😬

since NUT v2.8.3, the single-UPS options are added to the list of tuples, so both legacy and new options can be reliably used to monitor multiple devices in the same run. character development, we love to see it 💖

---

⭐ SEE ALSO ⭐

Server:

• upsd(8)

Clients:

• upsc(8), upscmd(8), upsrw(8), upsmon(8), upssched(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 was Network UPS Tools 2.8.5, dated 06/21/2026 — go log something iconic ✨💜