upslog - Man Page

upslog -h

upslog [Options]

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​.

-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 <system> 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) 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 <system> option is also used for the single-system logging​.

Can be used with the -m <tuple>, 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 <logfile> option is also used for the single-system logging​.

Can be used with the -m <tuple>, 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) 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​.

-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​.

The interval value is merely the number given to sleep(3) after running through the format string​. Therefore, a query will actually take slightly longer than the interval, depending on the speed of your system​.

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​.

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​.

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​.

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​.

nut(7), nut-recorder(8), nutupsdrv(8), upsc(8), upsd(8).