'\" t
.\"     Title: upslog
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 05/29/2025
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.3
.\"  Language: English
.\"
.TH "UPSLOG" "8" "05/29/2025" "Network UPS Tools 2\&.8\&.3" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
upslog \- UPS status logger
.SH "SYNOPSIS"
.sp
\fBupslog \-h\fR
.sp
\fBupslog\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.sp
\fBupslog\fR 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\&.
.sp
The default format string includes variables that are supported by many common UPS models\&. See the description below to make your own\&.
.SH "OPTIONS"
.PP
\fB\-f\fR \fIformat\fR
.RS 4
Monitor the UPS using this format string\&. Be sure to enclose
\fIformat\fR
in quotes so your shell doesn\(cqt split it up\&. Valid escapes within this string are:
.PP
%%
.RS 4
Insert a single "%"
.RE
.PP
%t
.RS 4
Insert a single TAB character (like
printf("\et"))
.RE
.PP
%TIME format%
.RS 4
Insert the time with
strftime
formatting
.RE
.PP
%ETIME%
.RS 4
Insert the number of seconds since the start of "Epoch", ala
time_t\&. This is now a 10\-digit number\&.
.RE
.PP
%HOST%
.RS 4
Insert the local hostname
.RE
.PP
%UPSHOST%
.RS 4
Insert the host of the UPS being monitored (the
<system>
part of your logging specification, e\&.g\&.
ups[@host[:port]])
.RE
.PP
%PID%
.RS 4
Insert the PID of
upslog
itself
.RE
.PP
%VAR varname%
.RS 4
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)
.RE
.sp
The default format string is:
.sp
.if n \{\
.RS 4
.\}
.nf
%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%
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-N\fR
.RS 4
Prefix
%UPSHOST%%t
before the format string (whether default or custom)\&. Useful when logging many systems into same target\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This option DOES NOT currently check if you already have
%UPSHOST%
in the formatting string (e\&.g\&. specified explicitly)\&.
.sp .5v
.RE
.RE
.PP
\fB\-i\fR \fIinterval\fR
.RS 4
Wait this many seconds between polls\&. This defaults to
\fI30\fR
seconds\&.
.sp
If you require tighter timing, consider writing your own logger using the
\fBupsclient\fR(3)
library\&.
.RE
.PP
\fB\-d\fR \fIcount\fR
.RS 4
Exit after specified amount of updates\&. Default is
\fI0\fR
for infinite loop (until interrupted otherwise)\&.
.RE
.PP
\fB\-l\fR \fIlogfile\fR
.RS 4
Store the results in this file\&.
.sp
You can use
\-
for stdout, but
upslog
will remain in the foreground by default\&.
.sp
Requires that the
\-s <system>
option is also used for the single\-system logging\&.
.sp
Can be used with the
\-m <tuple>, will be added to the list\&.
.RE
.PP
\fB\-D\fR
.RS 4
Raise debugging verbosity level by one;
upslog
will remain in the foreground by default\&.
.RE
.PP
\fB\-F\fR
.RS 4
upslog will run in the foreground, regardless of logging target\&.
.RE
.PP
\fB\-B\fR
.RS 4
upslog will run in the background, regardless of logging target or debugging\&.
.RE
.PP
\fB\-s\fR \fIups\fR
.RS 4
Monitor this UPS\&. The format for this option is
upsname[@hostname[:port]]\&. The default hostname is "localhost"\&.
.sp
The
\fIupsname\fR
may be an asterisk
*
to query UPSes currently served by
\fIhostname\fR, and monitor each of them (into the same logging destination)\&.
.sp
Requires that the
\-l <logfile>
option is also used for the single\-system logging\&.
.sp
Can be used with the
\-m <tuple>, will be added to the list\&.
.RE
.PP
\fB\-m\fR \fItuple\fR
.RS 4
Monitor multiple UPSs (provided several instances of such option)\&.
.sp
The format for this option is a tuple of UPS system and log file specification, separated by commas\&. An example would be:
.sp
.if n \{\
.RS 4
.\}
.nf
upsname@hostname:9999,/var/log/nut/cps\&.log
.fi
.if n \{\
.RE
.\}
.sp
The
\fIupsname\fR
may be an asterisk
*
to query UPSes currently served by
\fIhostname\fR, and monitor each of them (into the same logging destination)\&.
.sp
Tuples may specify
\-
as the logfile, to emit messages on
stdout
(e\&.g\&. to be collected by the system journal for services)\&.
.sp
Use of
stdout
via tuple\-based logging specifications also implies that upslog will remain in the foreground by default\&.
.RE
.PP
\fB\-u\fR \fIusername\fR
.RS 4
If started as
\fIroot\fR,
upslog
will
\fBsetuid\fR(2)
to the user id associated with
\fIusername\fR
for security\&.
.sp
If
\fIusername\fR
is not defined, it will use the value that was compiled into the program\&. This defaults to
\fInobody\fR
(if not otherwise configured), which is far from ideal\&.
.RE
.SH "COMMON OPTIONS"
.PP
\fB\-h\fR
.RS 4
Show the command\-line help message\&.
.RE
.PP
\fB\-V\fR
.RS 4
Show NUT version banner\&. More details may be available if you also
export NUT_DEBUG_LEVEL=1
or greater verbosity level\&.
.RE
.PP
\fB\-W\fR \fIsecs\fR
.RS 4
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\&.
.RE
.SH "SERVICE DELAYS"
.sp
The interval value is merely the number given to \fBsleep\fR(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\&.
.SH "ON\-DEMAND LOGGING"
.sp
Sending a SIGUSR1 to a running \fBupslog\fR process makes it wake from the current sleep and log immediately\&. This is useful when triggered from a \fBupssched\fR 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\&.
.SH "LOG CO\-LOCATION"
.sp
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\&.
.sp
Consider adding %UPSHOST% to your custom formatting string (e\&.g\&. by using the \fB\-N\fR command\-line option), in order to easily differentiate lines corresponding to different systems, when logging them to the same target\&.
.SH "LOG ROTATION"
.sp
\fBupslog\fR 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\&.
.SH "CAVEATS"
.sp
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)\&.
.sp
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)\&.
.sp
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\&.
.SH "SEE ALSO"
.SS "Server:"
.sp
\fBupsd\fR(8)
.SS "Clients:"
.sp
\fBupsc\fR(8), \fBupscmd\fR(8), \fBupsrw\fR(8), \fBupsmon\fR(8), \fBupssched\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: https://www\&.networkupstools\&.org/historic/v2\&.8\&.3/