UPSLOG(8)
=========

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 `<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 linkman: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 linkmanext: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.

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.

*-A* '/path/to/nutauth.conf'::

  Require use of the specified linkman:nutauth.conf[5] file (fail if absent,
  not accessible, or has content errors when parsed) to specify connection
  security settings and/or credentials for this run.
+
NOTE: Credentials are not currently required for read-only access to NUT.
+
By silent default, the client tries best-effort (non-fatal) detection of a
  configuration file in per-user locations `${HOME}/.config/nut/nutauth.conf`
  or `${HOME}/.nutauth.conf`, or site default `${NUT_CONFPATH}/nutauth.conf`.
+
NOTE: If the `NUT_AUTHCONF_FILE` environment variable is exported, only that
  exact full (relative or absolute) file path and name would be tried as the
  default; otherwise, if the `NUT_AUTHCONF_PATH` environment variable is
  exported, only a `nutauth.conf` file in that directory would be tried as the
  default (instead of looking at hard-coded default locations listed above).
+
Special values:

* `default`: require a default file in one of the locations found per rules
  listed above;
* `none`: do not even try to find and load any such file (legacy default).

SERVICE DELAYS
--------------

The interval value is merely the number given to linkmanext: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.

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.

Since this client can establish multiple connections, keep in mind that
currently it can only identify itself with some one (first seen) client
certificate, if `CERTIDENT` settings are used in the linkman:nutauth.conf[5]
file. Multiple `CERTHOST` directives for specially trusted servers can be used.

SEE ALSO
--------

Server:
~~~~~~~

linkman:upsd[8]

Clients:
~~~~~~~~

linkman:upsc[8], linkman:upscmd[8],
linkman:upsrw[8], linkman:upsmon[8], linkman:upssched[8],
linkman:nutauth.conf[5]

Internet resources:
~~~~~~~~~~~~~~~~~~~

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