nut/docs/man/upssched.conf.5

'\" t
.\"     Title: upssched.conf
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/26/2022
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "UPSSCHED\&.CONF" "5" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "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"
upssched.conf \- Configuration for upssched timer program
.SH "DESCRIPTION"
.sp
This file controls the operations of \fBupssched\fR(8), the timer\-based helper program for \fBupsmon\fR(8)\&.
.SH "CONFIGURATION DIRECTIVES"
.PP
\fBCMDSCRIPT\fR \fIscriptname\fR
.RS 4
Required\&. This must be above any AT lines\&. This script is used to invoke commands when your timers are triggered\&. It receives a single argument which is the name of the timer that caused it to trigger\&.
.RE
.PP
\fBPIPEFN\fR \fIfilename\fR
.RS 4
Required\&. This sets the file name of the socket which will be used for interprocess communications\&. This should be in a directory where normal users can\(cqt create the file, due to the possibility of symlinking and other evil\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCaution\fR
.ps -1
.br
.sp
if you are running Solaris or similar, the permissions that upssched sets on this file \fBare not enough\fR to keep you safe\&. If your OS ignores the permissions on a FIFO, then you MUST put this in a protected directory!
.sp .5v
.RE
.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
.sp
by default, \fBupsmon\fR(8) will run upssched as whatever user you have defined with RUN_AS_USER in \fBupsmon.conf\fR(8)\&. Make sure that user can create files and write to files in the path you use for PIPEFN and LOCKFN\&.
.sp .5v
.RE
.sp
My recommendation: create a special directory for upssched, make it owned by your upsmon user, then use it for both\&.
.sp
The stock version of the upssched\&.conf ships with PIPEFN disabled to make you visit this portion of the documentation and think about how your system works before potentially opening a security hole\&.
.PP
\fBLOCKFN\fR \fIfilename\fR
.RS 4
Required\&. upssched attempts to create this file in order to avoid a race condition when two events are dispatched from upsmon at nearly the same time\&. This file will only exist briefly\&. It must not be created by any other process\&.
.sp
You should put this in the same directory as PIPEFN\&.
.RE
.PP
\fBAT\fR \fInotifytype\fR \fIupsname\fR \fIcommand\fR
.RS 4
Define a handler for a specific event
\fInotifytype\fR
on UPS
\fIupsname\fR\&.
\fIupsname\fR
can be the special value * to apply this handler to every UPS\&.
.sp
This will perform the command
\fIcommand\fR
when the
\fInotifytype\fR
and
\fIupsname\fR
match the current activity\&. Possible values for
\fIcommand\fR
are:
.PP
\fBSTART\-TIMER\fR \fItimername\fR \fIinterval\fR
.RS 4
Start a timer of
\fIinterval\fR
seconds\&. When it triggers, it will pass the argument
\fItimername\fR
as an argument to your CMDSCRIPT\&.
.sp
Example:
.sp
Start a timer that will execute when any UPS (*) has been gone for 10 seconds
.sp
.if n \{\
.RS 4
.\}
.nf
AT COMMBAD * START\-TIMER upsgone 10
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBCANCEL\-TIMER\fR \fItimername\fR [\fIcmd\fR]
.RS 4
Cancel a running timer called
\fItimername\fR, if possible\&. If the timer has passed then pass the optional argument
\fIcmd\fR
to CMDSCRIPT\&.
.sp
Example:
.sp
If a specific UPS (myups@localhost) comes back online, then stop the timer before it triggers
.sp
.if n \{\
.RS 4
.\}
.nf
AT COMMOK myups@localhost CANCEL\-TIMER upsgone
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBEXECUTE\fR \fIcommand\fR
.RS 4
Immediately pass
\fIcommand\fR
as an argument to CMDSCRIPT\&.
.sp
Example:
.sp
If any UPS (*) reverts to utility power, then execute
ups\-back\-on\-line
via CMDSCRIPT\&.
.sp
.if n \{\
.RS 4
.\}
.nf
AT ONLINE * EXECUTE ups\-back\-on\-line
.fi
.if n \{\
.RE
.\}
.RE
.RE
.sp
Note that any AT that matches both the \fInotifytype\fR and the \fIupsname\fR for the current event will be used\&.
.sp
For a complete list of \fInotifytype\fR possible values, refer to the section NOTIFY EVENTS in \fBupsmon\fR(8)\&.
.SH "SEE ALSO"
.sp
\fBupssched\fR(8), \fBupsmon\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/