--- name: "upslog" section: "8" platform: "linux" package: "nut" version: "2.8.5-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/upslog" --- # upslog(8) UPS status logger ## NAME upslog - UPS status logger ## SYNOPSIS **upslog -h** **upslog** \[*OPTIONS*\] ## DESCRIPTION **upslog** is a daemon that will poll a UPS at periodic intervals, fetch the variables that interest you, format them, and write them to a file. The default format string includes variables that are supported by many common UPS models. See the description below to make your own. ## OPTIONS - **-f** *format* Monitor the UPS using this format string. Be sure to enclose *format* in quotes so your shell doesn’t split it up. Valid escapes within this string are: %% Insert a single "%" %t Insert a single TAB character (like printf("\\t")) %TIME format% Insert the time with strftime formatting %ETIME% Insert the number of seconds since the start of "Epoch", ala time\_t. This is now a 10-digit number. %HOST% Insert the local hostname %UPSHOST% Insert the host of the UPS being monitored (the \ part of your logging specification, e.g. ups\[@host\[:port\]\]) %PID% Insert the PID of upslog itself %VAR varname% Insert the value of variable varname (see NUT developer documentation chapter "Variables" on-line or in the docs/nut-names.txt file in sources of the NUT version you have installed for more details) The default format string is: ``` %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 default or custom). Useful when logging many systems into same target. **Note**\ This option DOES NOT currently check if you already have %UPSHOST% in the formatting string (e.g. specified explicitly). - **-i** *interval* Wait this many seconds between polls. This defaults to *30* seconds. If you require tighter timing, consider writing your own logger using the [**upsclient**(3)](/upsclient/3.md) library. - **-d** *count* Exit after specified amount of updates. Default is *0* for infinite loop (until interrupted otherwise). - **-l** *logfile* Store the results in this file. You can use - for stdout, but upslog will remain in the foreground by default. Requires that the -s \ option is also used for the single-system logging. Can be used with the -m \, will be added to the list. - **-D** Raise debugging verbosity level by one; upslog will remain in the foreground by default. - **-F** upslog will run in the foreground, regardless of logging target. - **-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). Requires that the -l \ option is also used for the single-system logging. Can be used with the -m \, will be added to the list. - **-m** *tuple* Monitor multiple UPSs (provided several instances of such option). 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)](/setuid/2.md) to the user id associated with *username* for security. 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. ## COMMON OPTIONS - **-h** Show the command-line help message. - **-V** Show NUT version banner. More details may be available if you also export NUT\_DEBUG\_LEVEL=1 or 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 The interval value is merely the number given to [**sleep**(3)](/sleep/3.md) after running through the format string. Therefore, a query will actually take slightly longer than the interval, depending on the speed of your system. ## ON-DEMAND LOGGING Sending a SIGUSR1 to a running **upslog** process makes it wake from the current sleep and log immediately. 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. ## 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. 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. ## 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. ## CAVEATS 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 to log 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). 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. ## SEE ALSO ### Server: [**upsd**(8)](/upsd/8.md) ### Clients: [**upsc**(8)](/upsc/8.md), [**upscmd**(8)](/upscmd/8.md), [**upsrw**(8)](/upsrw/8.md), [**upsmon**(8)](/upsmon/8.md), [**upssched**(8)](/upssched/8.md) ### Internet resources: The NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/