ConfigExamples.tex

%% ConfigExamples.tex
%% Introduction to Network UPS Tools (NUT)
%% Configuration Examples
%% (C) 2017-2023 Roger Price

%% This program is free software; you can redistribute it and/or
%% modify it under the terms of the GNU General Public License
%% as published by the Free Software Foundation; either version 3
%% of the License, or (at your option) any later version.

%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.

%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 59 Temple Place - Suite 330, 
%% Boston, MA  02111-1307, USA.

\documentclass[12pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00AB}{<<}         % LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
\DeclareUnicodeCharacter{00BB}{>>}         % LEFT-POINTING DOUBLE ANGLE QUOTATION MARK
\DeclareUnicodeCharacter{23A1}{$\lceil$}   % LEFT SQUARE BRACKET UPPER CORNER
%\DeclareUnicodeCharacter{23A4}{$\rceil$}  % RIGHT SQUARE BRACKET UPPER CORNER
\DeclareUnicodeCharacter{23A6}{$\rfloor$}  % RIGHT SQUARE BRACKET LOWER CORNER
\DeclareUnicodeCharacter{2E22}{\rule[0.6ex]{0.2ex}{1.2ex}\rule[1.6ex]{1.0ex}{0.2ex}}    % TOP LEFT HALF BRACKET
%\DeclareUnicodeCharacter{2E23}{⸣}         % TOP RIGHT HALF BRACKET
\DeclareUnicodeCharacter{2E25}{\rule[-0.3ex]{1.0ex}{0.2ex}\rule[-0.3ex]{0.2ex}{1.2ex}}  % BOTTOM RIGHT HALF BRACKET

\usepackage{printlen}                % http://mirrors.ircam.fr/pub/CTAN/macros/latex/contrib/printlen/printlen-doc.pdf
\usepackage{epsfig}                  % See The LaTeX Companion 11.3
\usepackage{lineprinter}             % Distributed with this file
\usepackage{wrapfig}                 % See The LaTeX Companion 6.4.2
%\usepackage{fancyheadings}           % See The LaTeX Companion 4.3.2 p.96  Obsolete?
\usepackage{fancyhdr}                % Almost compatible with fancy headings
\usepackage{color}                   % See the LaTeX Companion 9.2.2
\usepackage{caption}                 % http://ctan.mines-albi.fr/macros/latex/contrib/caption/caption-eng.pdf
% I need the date in iso format      % \isodate gives yyyy-mm-dd
% https://tex.stackexchange.com/questions/152392/date-format-yyyy-mm-dd
\def\isodate{\leavevmode\hbox{\the\year-\twodigits\month-\twodigits\day}}
\def\twodigits#1{\ifnum#1<10 0\fi\the#1}
\usepackage{hyperref}                % https://en.wikibooks.org/wiki/LaTeX/Hyperlinks
\usepackage{xcolor}                  % Other colours for hyperlinks
\usepackage[all]{hypcap}             % https://en.wikibooks.org/wiki/LaTeX/Hyperlinks#Problems_with_tables_and_figures
\usepackage{framed}                  % Draw frame around anything, including minipages.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Remove unhelpful warnings
\pdfsuppresswarningpagegroup=1
% https://tex.stackexchange.com/questions/76273/multiple-pdfs-with-page-group-included-in-a-single-page-warning
% Thanks to Martin Schröder

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\listfiles                           % Which files did I use?

% Version of this document
\newcommand{\Version}{3.0}

% Set up page dimensions for 1 column or 2 column formatting.
\ifthenelse{\equal{\ncols}{one}}%
   {\newcommand{\pagesize}{A5.1col.tex}}%
   {\newcommand{\pagesize}{A4.2col.tex}}
\input{\pagesize}

% Specify to what depth the sections are to be numbered.
% See the LaTeX Guide p.176.
\setcounter{secnumdepth}{4}
\pagenumbering{roman}                % Restart count of i, ii, iii, ...
\renewcommand{\thepage}{}            % Hide page number on cover sheet
% Parts are to be numbered with upper case letters
\renewcommand{\thepart}{\arabic{part}}
% Sections are to be numbered part.section
\renewcommand{\thesection}{\arabic{section}}
\renewcommand{\thesubsection}{\arabic{section}.\arabic{subsection}}
\renewcommand{\thesubsubsection}{\arabic{section}.\arabic{subsection}.\arabic{subsubsection}}
% Length separates the section number and the section title
\newlength{\headersep}\setlength{\headersep}{3mm}
% Horizontal space preceeding section titles
\newcommand{\Hsep}{\hspace{\headersep}}

% Some useful abbreviations
\newcommand{\newcolumn}{\vfill\eject}
\newcommand{\bsl}{$\setminus$}       % Back slash
\newcommand{\tl}{$\lceil$}
\newcommand{\br}{$\rfloor$}
\newcommand{\U}{$\_$}
\newcommand{\emspace}{\hphantom{1em}}

% Colours, see plate XIII in the LaTeX Graphics Companion
\definecolor{NUTCOLOUR}{rgb}{0, 0, 0}
\definecolor{UPSDCOLOUR}{rgb}{0.75, 0, 0}
\definecolor{MKNUTCERTCOLOUR}{rgb}{0.75, 0, 0}
\definecolor{MONCOLOUR}{rgb}{0, 0.4, 0}        % Dark green, xfig green4
\definecolor{SCHEDCOLOUR}{rgb}{0, 0, 0.5}
\definecolor{CMDCOLOUR}{rgb}{0.54, 0, 0.54}    % Dark magenta #8B008B, xfig magenta4
\definecolor{NOTIFYCOLOUR}{rgb}{1.0, 0.35, 0}  % (Very) Dark orange, rgb 255, 140, 0
\definecolor{GOLD}{rgb}{1.0, 0.84, 0}          % Gold, rgb 255, 215, 0
\definecolor{GRAY}{gray}{0.85}                 % Grey
\definecolor{UPSMONCOLOUR}{rgb}{0, 0.4 0}      % Dark green, xfig green4

% The names of our heroes, in glorious colour
\newcommand{\AD}{\mbox{\textcolor{UPSDCOLOUR}{Attachment Daemon}}} 
\newcommand{\ad}{\mbox{\textcolor{UPSDCOLOUR}{attachment daemon}}} 
\newcommand{\upsd}{\mbox{\textcolor{UPSDCOLOUR}{upsd}}} 
\newcommand{\driver}{\mbox{\textcolor{UPSDCOLOUR}{driver}}} 
\newcommand{\upsdrvctl}{\mbox{\textcolor{UPSDCOLOUR}{upsdrvctl}}} 
\newcommand{\dummyups}{\mbox{\textcolor{UPSDCOLOUR}{dummy-ups}}} 
\newcommand{\usbhidups}{\mbox{\textcolor{UPSDCOLOUR}{usbhid-ups}}} 
\newcommand{\bcmxcpusb}{\mbox{\textcolor{UPSDCOLOUR}{bcmxcp\_usb}}} 
\newcommand{\trippliteusb}{\mbox{\textcolor{UPSDCOLOUR}{tripplite\_usb}}} 
\newcommand{\blazerusb}{\mbox{\textcolor{UPSDCOLOUR}{blazer\_usb}}}
\newcommand{\richcommusb}{\mbox{\textcolor{UPSDCOLOUR}{richcomm\_usb}}}
\newcommand{\apcupsdups}{\mbox{\textcolor{UPSDCOLOUR}{apcupsd-ups}}} 
\newcommand{\MD}{\mbox{\textcolor{MONCOLOUR}{Management Daemon}}} 
\newcommand{\md}{\mbox{\textcolor{MONCOLOUR}{management daemon}}} 
\newcommand{\upsmon}{\mbox{\textcolor{MONCOLOUR}{upsmon}}} 
\newcommand{\upsc}{\mbox{\textcolor{UPSMONCOLOUR}{upsc}}} 
\newcommand{\upsrw}{\mbox{\textcolor{UPSMONCOLOUR}{upsrw}}} 
\newcommand{\upscmd}{\mbox{\textcolor{UPSMONCOLOUR}{upscmd}}} 
\newcommand{\upssched}{\mbox{\textcolor{SCHEDCOLOUR}{upssched}}} 
\newcommand{\upsschedcmd}{\mbox{\textcolor{CMDCOLOUR}{upssched-cmd}}} 
\newcommand{\notifysend}{\mbox{\textcolor{NOTIFYCOLOUR}{notify-send}}} 
\newcommand{\notifysendall}{\mbox{\textcolor{NOTIFYCOLOUR}{notify-send-all}}}
\setlength\fboxsep{0.5mm}              % Margin around colorbox boxes
\newcommand{\gold}[1][gold]{\colorbox{GOLD}{#1}} 
\newcommand{\mgmt}[1][mgmt]{\colorbox{GRAY}{#1}} 
\newcommand{\mkNUTcert}{\mbox{\textcolor{MKNUTCERTCOLOUR}{mkNUTcert.py}}} 
\newcommand{\upsdTLS}{\mbox{\textcolor{UPSDCOLOUR}{upsdTLS.py}}} 
\newcommand{\upsmonTLS}{\mbox{\textcolor{UPSMONCOLOUR}{upsmonTLS.py}}} 
\newcommand{\UPSmon}{\mbox{\textcolor{UPSMONCOLOUR}{UPSmon.py}}} 
\newcommand{\mkUPSmonconf}{\mbox{\textcolor{UPSMONCOLOUR}{mkUPSmonconf.py}}} 
\newcommand{\pylintrc}{\mbox{\textcolor{NUTCOLOUR}{pylintrc}}} 
% Coloured warnings
\newcommand{\upsdTLSonly}{\mbox{\textcolor{UPSDCOLOUR}{(For upsdTLS only)}}}
\newcommand{\upsmonTLSonly}{\mbox{\textcolor{UPSMONCOLOUR}{(For upsmonTLS only)}}}

% Statuses
\newcommand{\ALARM}{\textcolor{UPSDCOLOUR}{\textsc{alarm}}}
\newcommand{\BOOST}{\textcolor{UPSDCOLOUR}{\textsc{boost}}}
\newcommand{\BYPASS}{\textcolor{UPSDCOLOUR}{\textsc{bypass}}}
\newcommand{\CAL}{\textcolor{UPSDCOLOUR}{\textsc{cal}}}
\newcommand{\CHRG}{\textcolor{UPSDCOLOUR}{\textsc{chrg}}}
\newcommand{\DISCHRG}{\textcolor{UPSDCOLOUR}{\textsc{dischrg}}}
\newcommand{\FSDst}{\textcolor{UPSDCOLOUR}{\textsc{fsd}}}
\newcommand{\FSDev}{\textcolor{MONCOLOUR}{\textsc{fsd}}}
\newcommand{\LB}{\textcolor{UPSDCOLOUR}{\textsc{lb}}}
\newcommand{\LBi}{\textcolor{MONCOLOUR}{\textsc{lb1}}}
\newcommand{\LBii}{\textcolor{MONCOLOUR}{\textsc{lb2}}}
\newcommand{\LBiii}{\textcolor{MONCOLOUR}{\textsc{lb3}}}
\newcommand{\OB}{\textcolor{UPSDCOLOUR}{\textsc{ob}}}
\newcommand{\OFF}{\textcolor{UPSDCOLOUR}{\textsc{off}}}
\newcommand{\OL}{\textcolor{UPSDCOLOUR}{\textsc{ol}}}
\newcommand{\OVER}{\textcolor{UPSDCOLOUR}{\textsc{over}}}
\newcommand{\RB}{\textcolor{UPSDCOLOUR}{\textsc{rb}}}
\newcommand{\TEST}{\textcolor{UPSDCOLOUR}{\textsc{test}}}
\newcommand{\TRIM}{\textcolor{UPSDCOLOUR}{\textsc{trim}}}
% NOTIFY events
\newcommand{\ONLINE}{\textcolor{MONCOLOUR}{\textsc{online}}}
\newcommand{\ONBATT}{\textcolor{MONCOLOUR}{\textsc{onbatt}}}
\newcommand{\LOWBATT}{\textcolor{MONCOLOUR}{\textsc{lowbatt}}}
\newcommand{\COMMOK}{\textcolor{MONCOLOUR}{\textsc{commok}}}
\newcommand{\COMMBAD}{\textcolor{MONCOLOUR}{\textsc{commbad}}}
\newcommand{\SHUTDOWN}{\textcolor{MONCOLOUR}{\textsc{shutdown}}}
\newcommand{\REPLBATT}{\textcolor{MONCOLOUR}{\textsc{replbatt}}}
\newcommand{\NOCOMM}{\textcolor{MONCOLOUR}{\textsc{nocomm}}}
\newcommand{\NOPARENT}{\textcolor{NUTCOLOUR}{\textsc{noparent}}}
% Other UPSmon.py specific EVENTs
\newcommand{\COMM}{\textcolor{UPSMONCOLOUR}{\textsc{comm}}}
\newcommand{\FSD}{\textcolor{UPSMONCOLOUR}{\textsc{fsd}}}
\newcommand{\LS}{\textcolor{UPSMONCOLOUR}{\textsc{ls}}}
\newcommand{\None}{\textcolor{UPSMONCOLOUR}{\textsf{None}}}
\newcommand{\TICK}{\textcolor{UPSMONCOLOUR}{\textsc{tick}}}
\newcommand{\TIMEOUT}{\textcolor{UPSMONCOLOUR}{\textsc{timeout}}}
\newcommand{\TO}{\textcolor{UPSMONCOLOUR}{\textsc{to}}}
\newcommand{\TOCK}{\textcolor{UPSMONCOLOUR}{\textsc{tock}}}

% Colouring for statuses, status changes, NOTIFY events and EVENTs
\newcommand{\status}[1]{\textcolor{UPSDCOLOUR}{[{#1}]}}
\newcommand{\statuschange}[2]{\status{#1}{\allowbreak}\textcolor{UPSDCOLOUR}{$\rightarrow$}{\allowbreak}\status{#2}}
\newcommand{\NOTev}[1]{\textcolor{MONCOLOUR}{[{#1}]}}
\newcommand{\EVENT}[2]{\textcolor{MONCOLOUR}{#1}{\allowbreak}\texttt{\textcolor{MONCOLOUR}{->}}{\allowbreak}\textcolor{MONCOLOUR}{#2}}
\newcommand{\ttit}[1]{\texttt{\textit{#1}}}

% UPS names
\newcommand{\UPSi}{\texttt{UPS-1}}
\newcommand{\UPSii}{\texttt{UPS-2}}
\newcommand{\UPSiii}{\texttt{UPS-3}}
\newcommand{\UPSiv}{\texttt{UPS-4}}

% Configuration files
\newcommand{\nutconf}{\textcolor{NUTCOLOUR}{\texttt{nut.conf}}}
\newcommand{\upsconf}{\textcolor{UPSDCOLOUR}{\texttt{ups.conf}}}
\newcommand{\heartbeatconf}{\textcolor{UPSDCOLOUR}{\texttt{heartbeat.conf}}}
\newcommand{\upsdconf}{\textcolor{UPSDCOLOUR}{\texttt{upsd.conf}}}
\newcommand{\upsdusers}{\textcolor{UPSDCOLOUR}{\texttt{upsd.users}}}
\newcommand{\upsmonconf}{\textcolor{MONCOLOUR}{\texttt{upsmon.conf}}}
\newcommand{\upsschedconf}{\textcolor{SCHEDCOLOUR}{\texttt{upssched.conf}}}
\newcommand{\nutshutdown}{\textcolor{NUTCOLOUR}{\texttt{nutshutdown}}}
\newcommand{\nutshutdownservice}{\textcolor{NUTCOLOUR}{\texttt{nut{\allowbreak}-delayed{\allowbreak}-ups{\allowbreak}-shutdown.service}}}
\newcommand{\UPSmonconf}{\textcolor{UPSMONCOLOUR}{\texttt{UPSmon.conf}}}

% UPS status elements
\newcommand{\batterycharge}{\textcolor{UPSDCOLOUR}{\texttt{battery{\allowbreak}.charge}}}
\newcommand{\batterychargelow}{\textcolor{UPSDCOLOUR}{\texttt{battery{\allowbreak}.charge{\allowbreak}.low}}}
\newcommand{\batteryruntime}{\textcolor{UPSDCOLOUR}{\texttt{battery{\allowbreak}.runtime}}}
\newcommand{\batteryruntimelow}{\textcolor{UPSDCOLOUR}{\texttt{battery{\allowbreak}.runtime{\allowbreak}.low}}}
\newcommand{\upsstatus}{\textcolor{UPSDCOLOUR}{\texttt{ups{\allowbreak}.status}}}
\newcommand{\upsdelayshutdown}{\textcolor{UPSDCOLOUR}{\texttt{ups{\allowbreak}.delay{\allowbreak}.shutdown}}}
\newcommand{\upsdelaystart}{\textcolor{UPSDCOLOUR}{\texttt{ups{\allowbreak}.delay{\allowbreak}.start}}}

% Timer names
\newcommand{\UPSiiiwarntime}{\texttt{\UPSiii{\allowbreak}-two{\allowbreak}-minute{\allowbreak}-warning{\allowbreak}-timer}}
\newcommand{\UPSiiishutdown}{\texttt{\UPSiii{\allowbreak}-shutdown{\allowbreak}-timer}}
\newcommand{\UPSiiionline}{\texttt{\UPSiii{\allowbreak}-back{\allowbreak}-on{\allowbreak}-line}}
\newcommand{\UPSiiwarntime}{\texttt{\UPSii{\allowbreak}-two{\allowbreak}-minute{\allowbreak}-warning{\allowbreak}-timer}}
\newcommand{\UPSiishutdown}{\texttt{\UPSii{\allowbreak}-shutdown{\allowbreak}-timer}}
\newcommand{\UPSiionline}{\texttt{\UPSii{\allowbreak}-back{\allowbreak}-on{\allowbreak}-line}}
\newcommand{\UPSiwarntime}{\texttt{\UPSi{\allowbreak}-two{\allowbreak}-minute{\allowbreak}-warning{\allowbreak}-timer}}
\newcommand{\UPSishutdown}{\texttt{\UPSi{\allowbreak}-shutdown{\allowbreak}-timer}}
\newcommand{\UPSionline}{\texttt{\UPSi{\allowbreak}-back{\allowbreak}-on{\allowbreak}-line}}
% More timer names
\newcommand{\twominwarntim}{\texttt{two-minute{\allowbreak}-warning{\allowbreak}-timer}}
\newcommand{\oneminwarntim}{\texttt{one-minute{\allowbreak}-warning{\allowbreak}-timer}}
\newcommand{\shutdowntimer}{\texttt{shutdown{\allowbreak}-timer}}
\newcommand{\heartfailtimer}{\texttt{heartbeat{\allowbreak}-failure{\allowbreak}-timer}}
\newcommand{\upsbackonline}{\texttt{ups{\allowbreak}-back{\allowbreak}-on{\allowbreak}-line}}

% NUT RFC
\newcommand{\RFCnumber}{9271}
\newcommand{\RFC}{\href{https://www.rfc-editor.org/info/rfc\RFCnumber}% 
                       {RFC \RFCnumber} Uninterruptible Power Supply (UPS) Management Protocol\ %
                                        -- Commands and Responses} 
\newcommand{\RFCshort}{\href{https://www.rfc-editor.org/info/rfc\RFCnumber}%
                            {RFC \RFCnumber}}
% Other RFCs
\newcommand{\RFCcnn}{\href{https://www.rfc-editor.org/info/rfc7228}% 
                          {RFC 7228} Terminology for Constrained-Node Networks}
\newcommand{\RFCkey}{\href{https://www.rfc-editor.org/info/rfc5280}% 
                          {RFC 5280}}

% ISO standards
\newcommand{\ISOpays}{\href{https://www.iso.org/obp/ui\#search}%
                           {ISO 3166} Country Codes}

% Network UPS Tools Project
\newcommand{\NUTproj}{\href{https://networkupstools.org}{Network UPS Tools Project}}
% NUT software version
\newcommand{\Vsoft}{2.8.0}
% NUT protocol version
\newcommand{\Vprot}{1.3}

% Nut uses Iana port 3493/tcp (nut)
\newcommand{\IANAnut}{\href{https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=3493}%
                           {3493}}
% I squat port 410 (ups)
\newcommand{\IANAups}{\href{https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=401}%
                           {401}}
  
% NUT man pages
\newcommand{\NUTman}[1]{\href{https://networkupstools.org/docs/man/#1.html}{\texttt{man #1}}}
% Linux man pages  e.g.\LINman{systemd.unit}{5}
\newcommand{\LINman}[2]{\href{https://man7.org/linux/man-pages/man#2/#1.#2.html}{\texttt{man #1(#2)}}}
% Debian man pages
\newcommand{\DEBman}[1]{\href{https://manpages.debian.org/testing/#1}{\texttt{man #1}}}

% Some useful URLs
\newcommand{\devicedump}{\footnote{See the Device Dump Library at 
                         \href{https://www.networkupstools.org/ddl/}%
                              {https://{\allowbreak}www.networkupstools.org/{\allowbreak}ddl/}}}
\newcommand{\FAQ}{\footnote{See the FAQ at
                         \href{https://networkupstools.org/docs/FAQ.html}%
                              {https://{\allowbreak}networkupstools.org/{\allowbreak}docs/{\allowbreak}FAQ.html}}}
\newcommand{\hardwarelist}{\footnote{See the Hardware Compatibility list and required drivers at 
                         \href{https://www.networkupstools.org/stable-hcl.html}%
                              {https://{\allowbreak}www.networkupstools.org/{\allowbreak}stable-hcl.html}}}
\newcommand{\mailinglist}{\href{https://lists.alioth.debian.org/mailman/listinfo/nut-upsuser}%
                               {\texttt{nut-upsuser} mailing list}}
\newcommand{\usermanual}{\footnote{See the User Manual at
                         \href{https://networkupstools.org/docs/user-manual.chunked/index.html}%
                              {https://{\allowbreak}networkupstools.org/{\allowbreak}docs/{\allowbreak}user-manual.chunked/{\allowbreak}index.html}}}
\newcommand{\HCL}{https://www.networkupstools.org/stable-hcl.html}
\newcommand{\nutreport}{\texttt{nut-report} script available at
                         \href{http://rogerprice.org/NUT/nut-report}%
                              {http://{\allowbreak}rogerprice.org/{\allowbreak}NUT/{\allowbreak}nut-report}}
\newcommand{\PLY}{David Beazley's PLY\footnote{See David Beazley's PLC (Python Lex-Yacc) page at
                  \href{https://www.dabeaz.com/ply/}% 
                       {https://{\allowbreak}www.dabeaz.com/{\allowbreak}ply/}}} 

% Lists, almost HTML
%
% Abbreviations which make style more consistent, and typing easier.
% Allow approximately the same mnemonics as used in SGML's GDOC for lists 
% Compact lists.  See LaTeX Companion p.62
\newcommand{\ol}{\begin{enumerate}%     Ordered (Numbered) lists 
   \setlength{\itemsep}{0em}}
\newcommand{\eol}{\end{enumerate}} 
\newcommand{\ul}{\begin{itemize}%       Unnumbered lists (bullets) 
   \setlength{\itemsep}{0em}}
\newcommand{\eul}{\end{itemize}} 
\newcommand{\li}{\item}                 % List items e.g. \li or \li[Dog]  

% Page number in references
% The declaration \newcommand{\Ref} produces LaTeX Error: Command \Ref already defined
% since \Ref has been moved into the LaTeX kernel to provide a \ref at the beginning of
% a sentence.
% The ``intelligent'' referencing command \Refpage{xxx} adds the page number.
% See the LaTeX2e Guide c.11.2 p.209.
%\newcommand{\Refpage}[1]{\ref{#1} on page \pageref{#1}}
% No page number when hyperref in use
\newcommand{\Refpage}[1]{\Ref{#1}}
\newcommand{\refpage}[1]{\ref{#1}}

% Maximum generosity for floating material. See LaTeX2e book P.199
\setcounter{topnumber}{6} 
\renewcommand{\topfraction}{1} 
\setcounter{totalnumber}{12} 
\renewcommand{\textfraction}{0} 
\renewcommand{\floatpagefraction}{0.1} 
\setcounter{dbltopnumber}{6} 
\renewcommand{\dbltopfraction}{1} 
\renewcommand{\dblfloatpagefraction}{0.1} 

% Options for hyperref, see https://en.wikibooks.org/wiki/LaTeX/Hyperlinks
% See xcolor: in xcolor.sty, the following color names are defined: red, green,
% blue, cyan, magenta, yellow, black, gray, white, darkgray, lightgray, brown,
% lime, olive, orange, pink, purple, teal, violet.
\hypersetup{
%    bookmarks=true,         % show bookmarks bar?
%    unicode=false,          % non-Latin characters in Acrobat’s bookmarks
%    pdftoolbar=true,        % show Acrobat’s toolbar?
%    pdfmenubar=true,        % show Acrobat’s menu?
%    pdffitwindow=false,     % window fit to page when opened
%    pdfstartview={FitH},    % fits the width of the page to the window
%    pdftitle={My title},    % title
%    pdfauthor={Author},     % author
%    pdfsubject={Subject},   % subject of the document
%    pdfcreator={Creator},   % creator of the document
%    pdfproducer={Producer}, % producer of the document
%    pdfkeywords={keyword1, key2, key3}, % list of keywords
%    pdfnewwindow=true,      % links in new PDF window
    colorlinks=false,        % false: boxed links; true: colored links
    linkcolor=red,           % color of internal links (change box color with linkbordercolor)
    linkbordercolor=pink,    % color of internal links (change box color with linkbordercolor)
    citecolor=green,         % color of links to bibliography
    filecolor=magenta,       % color of file links
    urlcolor=red,            % color of external links
    urlbordercolor=pink      % Color of frame around URL links
}

\urlstyle{same}            % No mono-spaced font for URL  

\begin{document}           % End of preamble and beginning of text. 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% RP Define the style for the front matter of a book.
\setlength{\headheight}{8mm}           % Add 1mm if error messages
\pagestyle{fancy}                      % LaTeX2e p.89 
\renewcommand{\headrulewidth}{0pt}     % Header rule 
\renewcommand{\footrulewidth}{0pt}     % Footer rule

% Layout for the front matter.  See the LaTeX Companion, p.96.
% ``Even'' means left, ``Odd'' means right.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[]{}                           % \lhead[left-header-even]{left-header-odd}
\chead[]{}                           % \chead[centre-header-even]{centre-header-odd}
\rhead[]{}                           % \rhead[right-header-even]{right-header-odd}
\lfoot[]{}                           % \lfoot[left-footer-even]{left-footer-odd}
\cfoot[\thepage]{\thepage}           % \cfoot[centre-footer-even]{centre-footer-odd}
\rfoot[]{}                           % \rfoot[right-footer-even]{right-footer-odd}

\onecolumn                                     % End of SetFrontMatterStyle
\vspace*{\fill}

\begin{center}
\scalebox{1.0}[1.2]{\textsf{\Huge{NUT}}} \\[6mm]
\scalebox{1.0}[1.2]{\textsf{\Large{An Introduction to Network UPS Tools}}} \\

\vspace*{\fill}

\scalebox{1.2}[1.4]{\textsf{\Huge{Configuration Examples}}} \\

\vspace*{\fill}

\textsl{Based on}
\vspace{2mm}

\textsf{\large{\NUTproj\ 2.8.0}} \\
\textsf{\normalsize Russell Kroll},
\textsf{\normalsize Arnaud Quette},
\textsf{\normalsize Jim Klimov}, \\
\textsf{\normalsize Arjen de Korte},
\textsf{\normalsize Charles Lepple and many others}

\vspace{4mm}
\textsl{Conforms to}
\vspace{2mm}

\begin{minipage}[t]{0.6\textwidth}
\begin{center}\textsf{\large{\RFC}}\end{center}
\end{minipage}

\vspace*{\fill}

\textsf{\normalsize Roger Price} \hspace{3mm} \textsf{(Editor)}

\vspace*{\fill}

\textsf{Version \Version, with corrections up to \isodate} \\
\end{center}

\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Allow page numbers to appear.      % See LaTeX2e p. 180
\renewcommand{\thepage}{\roman{page}}
\ifthenelse{\equal{\ncols}{two}}{\twocolumn}{\onecolumn}   % Starts new page

This introduction is based on the Network UPS Tools (NUT) User Manual, the man
pages and the file \texttt{config-notes.txt} which do not carry explicit
copyright notices, but which are part of the NUT package which is GPL
licensed.

\vspace{5mm}

\textsf{Copyright \copyright\ Russell Kroll, Arnaud Quette, Arjen de Korte,
  Charles Lepple and others}

\vspace{5mm}

\textsf{This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by the
  Free Software Foundation; either version 2 of the License, or (at your
  option) any later version.}

\textsf{This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  more details.}

\textsf{You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software Foundation,
  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.}
  
\href{http://www.fsf.org/licenses/old-licenses/gpl-2.0.html}
     {http://{\allowbreak}www.fsf.org/{\allowbreak}licenses/%
       {\allowbreak}old-licenses/{\allowbreak}gpl-2.0.html}

\vspace*{\fill}

The User Manual provides the following notice: 

\fbox{\parbox[c]{0.9\linewidth}{
\textsf{B. Acknowledgments / Contributions}

\textsf{This project is the result of years of work by many individuals and
  companies.}

\textsf{Many people have written or tweaked the software; the drivers,
  clients, server and documentation have all received valuable attention from
  numerous sources.}

\textsf{Many of them are listed within the source code, AUTHORS file, release
  notes, and mailing list archives, but some prefer to be anonymous. This
  software would not be possible without their help.}
}}

\vspace*{\fill}

Additional material:

\textsf{Copyright \copyright\ Roger Price 2017, 2018, 2020, 2021, 2022, 2023}

\textsf{Distributed under the GPLv3.}
\href{http://www.fsf.org/licenses/gpl.html}
     {http://{\allowbreak}www.fsf.org/{\allowbreak}licenses/%
       {\allowbreak}gpl.html}

\vspace*{\fill}
\noindent\hrulefill
\vspace*{\fill}

\textsl{The source file for this document has been marked up by the editor in
  \LaTeXe\ and rendered as PDF file
  \href{http://rogerprice.org/NUT/ConfigExamples.A5.pdf}{ConfigExamples{\allowbreak}.A5.pdf}
  in a portrait A5 format, \pageref{LastPage} pages with one page per sheet.
  Your PDF viewer may be able to place two pages side by side on your big
  monitor.}

\textsl{The document is not only linear reading, but also hypertext. All
  chapters in the table of contents, all chapter references, all line number
  references throughout the document, all man page names and URL's are
  clickable.  Such links are outlined in colour, for example}
\textrm{\NUTman{ups.conf}}\textsl{. If your mouse hovers over a clickable
  surface, your browser/PDF reader may tell you where the link leads.}

\vspace*{\fill}
\newcolumn

\begin{tabular}{|l|l|l|l|}
\hline
\multicolumn{4}{|c|}{\textbf{Page dimensions}} \\ \hline
\textbf{Dimension}    & \textbf{Design (A5)} & \textbf{Actual pt} & \textbf{Actual mm} \\ \hline\hline
\bsl hoffset          & -29.4mm   & \printlength{\hoffset}       & \uselengthunit{mm}\printlength{\hoffset} \\ 
\bsl voffset          & -29.4mm   & \printlength{\voffset}       & \uselengthunit{mm}\printlength{\voffset} \\ 
\hline
\bsl pdfpageheight    & 240mm     & \printlength{\pdfpageheight} & \uselengthunit{mm}\printlength{\pdfpageheight} \\
\bsl pdfpagewidth     & 197.5mm   & \printlength{\pdfpagewidth}  & \uselengthunit{mm}\printlength{\pdfpagewidth} \\
\bsl textheight       & 210mm     & \printlength{\textheight}    & \uselengthunit{mm}\printlength{\textheight} \\ 
\bsl textwidth        & 177.5mm   & \printlength{\textwidth}     & \uselengthunit{mm}\printlength{\textwidth} \\
\bsl linewidth        &           & \printlength{\linewidth}     & \uselengthunit{mm}\printlength{\linewidth} \\
\bsl columnsep        & 15mm      & \printlength{\columnsep}     & \uselengthunit{mm}\printlength{\columnsep} \\ 
\hline
\bsl LinePrinterwidth & 145.5mm   & \printlength{\LinePrinterwidth}  & \uselengthunit{mm}\printlength{\LinePrinterwidth} \\ 
\hline
\end{tabular}

\vspace*{\fill}
Changes:  

\ul

\li 2017-06-27 First edition 

\li 2017-07-02 Added subsection ``Configuration file formats''.  Added
\texttt{lowbatt} to \upsconf.  Added subsection ``Driver daemon'' to
introduction.  Added Ubuntu specific addresses.

\li 2017-07-24 Added discussion of selective UPS shutdown to chapter 9.

\li 2017-08-10 Added appendix \ref{section:notifysend}, ``Using \notifysend''.

\li 2018-01-10 Rewrote appendix \ref{section:notifysend}, ``Using \notifysend''.
Rewrote appendix \ref{section:Start} ``Starting NUT''.
Added chapter \ref{section:upsschedcmd.paranoid} ``For parano\"id sysadmins''.

\li 2018-08-22 In chapter \ref{section:upsconf.dual} added reference
to issue \#597 for multiple UPS units.

\li 2019-07-21 Added chapter \ref{section:SSL} ``Encrypted connections''.

\li 2020-08-20 File \texttt{heartbeat.dev} becomes \texttt{heartbeat.conf}

\li 2020-09-30 Added Part 2 covering the Python3 scripts. Deprecated
\ref{section:SSL} ``Encrypted connections''.

\li 2021-05-16 Split Part 2 into two parts: new Part 2 for the shim daemons,
and a new part 3 for the Python3 replacement for \upsmon\ and \upssched. The
Appendix becomes Part 4.

\li 2021-06-06 Migrated figures from xfig to inkscape.

\li 2021-08-03 Clarified that command \texttt{upsmon -c fsd} calls the
command specified by declaration \texttt{SHUTDOWNCMD}.

\li 2022-08-02 Updated to NUT software version 2.8.0, protocol version
1.3 and \RFCshort.  Removed Part 3 UPSmon.py.  Appendices become Part 3.

\li 2022-11-27 Minor corrections.

\li 2023-01-02 Passwords should not contain spaces or quotation marks
\texttt{"}.

\li \isodate Rendering of the current document in its binary form.

\eul

\vspace*{\fill}
\newcolumn
\tableofcontents
\listoffigures
%\listoftables

% Page 1 should be on the right hand side
%\clearpage 
%\vspace*{\fill}

%\begin{center}
%   \epsfig{file=UPS-1.jpg, height=36mm}
%\end{center}

%\vspace*{\fill}

\newcolumn                           % Move to right hand page
\pagenumbering{arabic}               % Number pages 1, 2, 3, ...
%\renewcommand{\thepage}{\arabic{page}}
%\setcounter{page}{1}

% RP Define the style for the body of a book.
\renewcommand{\headrulewidth}{0.4pt}   % Header rule 
\renewcommand{\footrulewidth}{0pt}     % Footer rule
% Layout for the body.  See the LaTeX Companion, p.96.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[NUT \Vsoft]{NUT \Vsoft}                                % \lhead[left-header-even]{left-header-odd}
\chead[ConfigExamples \Version]%
      {ConfigExamples \Version}                               % \chead[centre-header-even]{centre-header-odd}
\rhead[\LaTeX\ run \isodate]{\LaTeX\ run \isodate}            % \rhead[right-header-even]{right-header-odd}
\lfoot[]{}                                                    % \lfoot[left-footer-even]{left-footer-odd}
\cfoot[\fancyplain{}{Page \thepage\ of \pageref{LastPage}}]%
      {\fancyplain{}{Page \thepage\ of \pageref{LastPage}}}   % \cfoot[centre-footer-even]{centre-footer-odd}
\rfoot[]{}                                                    % \rfoot[right-footer-even]{right-footer-odd}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                            P A R T  1                                  %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{center}
\addtocontents{toc}{\protect\vspace{3mm}}
\part[\hspace{\fill}\textsf{UPS monitoring using NUT}\hspace{\fill}]{}\label{part:NUT}
\addtocontents{toc}{\protect\vspace{3mm}}
\vspace{7mm}
\scalebox{1.0}[1.2]{\textsf{\Huge{UPS monitoring using NUT}}}
\vspace{7mm}
\end{center}

The first part of this documentation discusses UPS activity monitoring
using the facilities provided by NUT \Vsoft.  Part \ref{part:shim}
discusses TLS support for \upsd\ and the clients.
Part \ref{part:appendices} provides technical appendices.
% Part \ref{part:UPSmon} will discuss the use of the \UPSmon\ software
% to manage the UPS activity.

\vspace{7mm}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\Hsep\ Introduction, and Welcome to NUT}\label{section:intro}

%\textsl{You are of course free to read as much or as little as you wish of
%  this document, but the suggested reading order is:}

%\begin{center}
%   \epsfig{file=intro.pdf,width=0.85\LinePrinterwidth}
%\end{center}

%\vspace*{\fill}

\subsection{\Hsep\ What is NUT?}\label{whatisNUT}

% Source figure: overview-OL.svg
% Edit with: inkscape
% Export using inskscape File: 1) Save a copy 2) Select PDF
% To crop the surrounding white space:
% File -> Document properties > Page -> Custom size -> esize page to drawing.
\begin{figure}[ht]
\begin{center}
   \epsfig{file=overview-OL.pdf,width=0.9\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Overview of NUT.\label{fig:overview-OL}}
\end{figure}

The acronym NUT stands for ``Network UPS Tools''.  It is a collection of GPL
licensed software written in K\&R style C for managing power devices, mainly
UPS units.  It supports a wide range of UPS units and can handle one or
multiple UPS's of different models and manufacturers simultaneously in home,
small business and larger professional installations.  NUT replaces the
software which came with your UPS.

The NUT software is included as a package in most major distributions of
Linux, and the source code is available in a tarball for the others.

The NUT software includes complete technical documentation in the form of PDF
manuals, configuration notes such as file
\href{https://github.com/networkupstools/nut/blob/master/docs/config-notes.txt}
     {\texttt{config{\allowbreak}-notes.txt}}, man pages, a web site
\href{http://networkupstools.org}{http://{\allowbreak}networkupstools{\allowbreak}.org}
and detailed comments in the sample configuration files supplied with the
project.  There is also a
\href{http://networkupstools.org/docs/FAQ.html}{FAQ} on the project web
site, and a \mailinglist\ in which users may ask questions.


\subsubsection{\Hsep\ NUT is a mature project}\label{matureproject}

NUT was already operating in its current form when it registered port
\IANAnut/TCP (nut) with IANA in May 2002.  Since then, the project has
kept its principal characteristics which are the basis of its success:

\ul

\li \textit{Simplicity} -- The design of NUT is simple and
straightforward.  No additional tools or software systems are needed
to encode the messages sent between the \ad\ and the \md.

\li \textit{Resilience} -- The ability to operate in a
\textit{challenged environment}.  Such environments are now receiving
attention, for example the evolving vocabulary provided by \RFCcnn.

\li \textit{Aggregation} -- The simultaneous handling of a wide variety of
UPS-things with widely differing capabilites.  This is now known as
the ``Internet of Things'', and again is the subject of much attention.

\eul

\subsection{\Hsep\ You need to configure the NUT software}\label{needtoconfigure}

To make full use of your UPS you will need to configure the NUT software used
to manage UPS units.  The technically complete documentation does not provide
many examples; this introduction is intended to fill the gap by providing
fully worked examples for some frequently met configurations.  It is aimed at
experienced Unix/Linux system administrators who are new to NUT.  Pick the
configuration which corresponds most closely to your installation, get it
working, and then adapt it to your needs.  If you have questions for the
mailing list it is much easier to explain what you are trying to do by
referring to a well known example.


\subsection{\Hsep\ \AD\ \upsd}\label{section:upsd}

Figure \ref{fig:overview-OL} shows the basic components of the NUT software.
\upsd\ is a daemon which runs permanently in the box to which one or more
UPS's are attached.  It scans the UPS's through the UPS-specific
driver\hardwarelist\ and maintains an abstracted image of the UPS in
memory\footnote{This image may be viewed at any time with the command
\texttt{upsc \textsl{name-of-UPS}}}.

The various parts of the abstracted image have standardized names, and
a key part is the variable \upsstatus\ which gives the current status
of the UPS unit.  The current status is a string of symbols.  The
principal symbols are shown in figure \ref{fig:statussymbols}, but if
you write software which processes \upsd\ symbols, expect to find
other values in exceptional UPS specific cases.

Some important status values are \status{\OL} which means that the UPS unit is
taking power from the wall, and \status{\OB\ \LB} which means that wall power
has failed, the UPS is supplying power from it's battery, and that battery is
almost exhausted.

Daemon \upsd\ listens on port \IANAnut/tcp (nut) for requests from its
clients, which may be local or remote.  It is amusing to test this
using a tool such as \texttt{nc} or \texttt{netcat} and a UPS called
\UPSi.
%
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`rprice@maria:~> REQUEST="GET VAR UPS-1 battery.charge"` \\
\Clunk         & \verb`rprice@maria:~> echo $REQUEST | nc localhost 3493` \\
\Clunk         & \verb`VAR UPS-1 battery.charge "100"` \\
\end{LinePrinter}
%
Chapter \ref{section:upsc} will show that this is best done with NUT utility program \upsc.

Later chapters will discuss the configuration files \upsconf, \upsdconf\ and
\upsdusers\ with the specific examples. For gory details, read \NUTman{upsd},
\NUTman{upsd.conf}, \NUTman{upsd.users} and \NUTman{ups.conf}.

\begin{figure}[htb]
\begin{center}
\begin{tabular}{|l|p{0.7\LinePrinterwidth}|}
\hline
\status{\OL}      & UPS unit is receiving power from the wall.  \\ \hline
\status{\OB}      & UPS unit is not receiving power from the wall and is using its
                    own battery to power the protected device. \\ \hline
\status{\LB}      & The battery charge is below a critical level specified by the 
                    variable \batterychargelow. \\ \hline
\status{\RB}      & UPS battery needs replacing.  \\ \hline
\status{\CHRG}    & The UPS battery is currently being charged. \\ \hline
\status{\DISCHRG} & The UPS battery is not being charged and is discharging.  \\ \hline
\status{\ALARM}   & An alarm situation has been detected in the UPS unit. \\ \hline
\status{\OVER}    & The UPS unit is overloaded. \\ \hline
\status{\TRIM}    & The UPS voltage trimming is in operation. \\ \hline
\status{\BOOST}   & The UPS voltage boosting is in operation. \\ \hline
\status{\BYPASS}  & The UPS unit is in bypass mode. \\ \hline
\status{\OFF}     & The UPS unit is off. \\ \hline
\status{\CAL}     & The UPS unit is being calibrated. \\ \hline
\status{\TEST}    & UPS test in progress. \\ \hline
\status{\FSDst}   & Tell secondary \upsmon\ instances that final shutdown is underway. \\ \hline
\end{tabular}
\caption{Symbols used in \upsstatus\ maintained by \upsd.\label{fig:statussymbols}}
\end{center}
\end{figure}

\newcolumn
\subsubsection{\Hsep\ Driver daemon}\label{section:driver}

The driver is a daemon which is part of the \ad\footnote{Communication
between \upsd\ and each driver is through a socket which Debian 11
declares in directory \texttt{/var/{\allowbreak}run/{\allowbreak}nut}
. The following example shows the sockets to two drivers
\texttt{usbhid-ups} and \texttt{dummy-ups} :\\
\hspace*{2cm}\texttt{root@titan ~ ls -alF /run/nut} \\
\hspace*{2cm}\texttt{drwxrwx---  2 root nut  140 Aug  7 15:57 ./} \\
\hspace*{2cm}\texttt{drwxr-xr-x 30 root root 880 Aug  7 16:01 ../} \\
\hspace*{2cm}\texttt{srw-rw----  1 nut  nut    0 Aug  7 15:57 dummy-ups-heartbeat=} \\
\hspace*{2cm}\texttt{-rw-r--r--  1 nut  nut    5 Aug  7 15:57 dummy-ups-heartbeat.pid} \\
\hspace*{2cm}\texttt{-rw-r--r--  1 nut  nut    5 Aug  7 15:57 upsd.pid} \\
\hspace*{2cm}\texttt{srw-rw----  1 nut  nut    0 Aug  7 15:57 usbhid-ups-Eaton=} \\
\hspace*{2cm}\texttt{-rw-r--r--  1 nut  nut    4 Aug  7 15:57 usbhid-ups-Eaton.pid}}.
It talks to the UPS hardware and is aware of the state of the UPS.
One of the strengths of the NUT project is that it provides drivers
for a wide range of UPS units from a range of manufacturers.  NUT
groups the UPS's into families with similar interfaces, and supports
the families with drivers which match the manufacturer's interface.
See \href{\HCL}{the hardware compatibility list} for a looong list of
the available drivers.

The drivers share a command interface, \upsdrvctl, which makes it possible to
send a command to the UPS without having to know the details of the UPS
protocol.  We will see this command in action in chapter
\ref{section:delayedUPSshutdown} when we need to shut down the UPS after a
system shutdown.

%\begin{framed}%
%\begin{minipage}{1.1\LinePrinterwidth}%
%\end{minipage}
%\end{framed}

\subsection{\Hsep\ \MD\ \upsmon}\label{section:upsmon}

% Source figure: overview-OB.svg
% Edit with: inkscape
% Export using inskscape File: 1) Save a copy 2) Select PDF
% To crop the surrounding white space:
% File -> Document properties > Page -> Custom size -> esize page to drawing.
% Add arrow heads to bezier curve: Right click line object -> Fill and stroke menu -> Markers

\begin{figure}[ht]
\vspace{-6mm}
\begin{center}
   \epsfig{file=overview-OB.pdf,width=1.1\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Wall power has failed.\label{fig:overview-OB}}
\end{figure}

The \md\ \upsmon\ is an example of a client of \upsd.  It runs
permanently as a daemon in a local or remote box, polling the status
changes of the UPS unit.  It is able to react to changes in the UPS
state for example by emitting warning messages, or shutting down the
box.  The actions are specified in the configuration file
\upsmonconf\ which will be discussed in specific examples.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|p{0.75\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{NOTIFY events based on status changes} \\ \hline
\NOTev{\ONLINE}   & Status change \statuschange{\OB}{\OL}.  The UPS is back on line. \\ \hline
\NOTev{\ONBATT}   & Status change \statuschange{\OL}{\OB}.  The UPS is now on battery. \\ \hline
\NOTev{\LOWBATT}  & Status \status{\LB} has appeared. The driver says the UPS battery is low. \\ \hline
\NOTev{\REPLBATT} & The UPS needs to have its battery replaced.  Not all UPS's can indicate this. \\ \hline\hline
\multicolumn{2}{|c|}{NOTIFY events based on \upsmon\ activity} \\ \hline
\NOTev{\FSDev}    & No status change.  The primary has commanded the UPS into the ``forced shutdown'' mode. \\ \hline
\NOTev{\SHUTDOWN} & The local system is being shut down. \\ \hline
\NOTev{\COMMOK}   & Communication with the UPS has been established. \\ \hline
\NOTev{\COMMBAD}  & Communication with the UPS was just lost. \\ \hline
\NOTev{\NOCOMM}   & The UPS can't be contacted for monitoring. \\ \hline\hline
\multicolumn{2}{|c|}{NOTIFY event based on NUT process error} \\ \hline
\NOTev{\NOPARENT} & upsmon parent died - shutdown impossible. \\ \hline
\end{tabular}
\caption{Symbols used to represent NOTIFY events maintained by \upsmon.\label{fig:NOTIFYevents}}
\end{center}
\end{figure}

As the state of a UPS evolves, the key status changes, called ``NOTIFY
events'', are identified with the symbols shown in figure
\ref{fig:NOTIFYevents}.  The NOTIFY event symbol is also known as a
``notifytype'' in NUT.

Figure \ref{fig:overview-OB} shows what happens when wall power fails.  Daemon
\upsd\ has polled the UPS, and has discovered that the UPS is supplying power
from it's battery.  The \upsstatus\ changes to \status{\OB}.  Daemon
\upsmon\ has polled \upsd, has discovered the status change and has generated
the NOTIFY event \NOTev{\ONBATT}.

For the gory details, read \NUTman{upsmon} and \NUTman{upsmon.conf}.

\subsubsection{\Hsep\ Utility program \upsc}\label{section:upsc}

The NUT project provides this simple utility program to talk to \upsd\ and
retrieve details of the UPS's.  For example, ``What UPS's are attached to the
local host?''
%
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`rprice@maria:~> upsc -L` \\
\Clunk         & \verb`UPS-1: Example Mfg ASR 1500 USBS` \\
\Clunk         & \verb`heartbeat: Heart beat validation of NUT` \\
\end{LinePrinter}
%
Let's ask for the \upsd\ abstracted image of a UPS:
%
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`rprice@maria:~> upsc UPS-1` \\
\Clunk         & \verb`battery.charge: 100` \\
\Clunk[L:low]  & \verb`battery.charge.low: 50` \\
\Clunk         & \verb` ...` \\
\Clunk         & \verb`driver.name: usbhid-ups` \\
\Clunk         & \verb`driver.parameter.offdelay: 30`\\
\Clunk         & \verb`driver.parameter.ondelay: 40` \\
\Clunk         & \verb` ...` \\
\Clunk         & \verb`ups.status: OL CHRG` \\
\end{LinePrinter}
%
Let's ask, using Bash syntax, for a list of the drivers used by \upsd:
%
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`rprice@maria:~> for u in $(upsc -l)`\\
\Clunk         & \verb`> do upsc $u driver.name`\\
\Clunk         & \verb`> done`\\
\Clunk         & \verb`usbhid-ups`\\
\Clunk         & \verb`dummy-ups`\\
\end{LinePrinter}

\noindent Man page \NUTman{upsc} provides further examples.


\subsection{\Hsep\ Configuration file formats}\label{section:conffileformat}

The components of NUT get their configuration from the following configuration files.
The simpler configurations do not use all these files.

\ul
\li \textbf{\nutconf}       \quad Nut daemons to be started.
\li \textbf{\upsconf}       \quad Declare the UPS's to be managed by \upsd.
\li \textbf{\heartbeatconf} \quad Used only for \hyperref[heartbeat]{heartbeat} configurations.
\li \textbf{\upsdconf}      \quad Access control to the \upsd\ daemon.
\li \textbf{\upsdusers}     \quad Who has access to the \upsd\ daemon.
\li \textbf{\upsmonconf}    \quad \upsmon\ daemon configuration.
\li \textbf{\upsschedconf}  \quad Only used for customised and timer-based setups.
\li \textbf{\upsschedcmd}   \quad A script used only for customised and timer-based setups.
\li \textbf{delayed UPS shutdown} \quad Choice of scripts for delayed UPS shutdown.
\eul

NUT parses all the configuration files with a common state machine, which
means they all have the following characteristics.

First, most of the programs use an uppercase word to declare a configuration
directive.  This may be something like \texttt{MONITOR}, \texttt{NOTIFYCMD},
or \texttt{ACCESS}.  Case matters here.  ``\texttt{monitor}'' won't be
recognized.

Next, the parser does not care about whitespace between words.  If you
like to indent things with tabs or spaces, feel free to do so.

The keywords are often followed by values. If you need to set a value to
something containing spaces, it has to be contained within ``quotes'' to keep
the parser from splitting the line, e.g.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\end{LinePrinter}

Without the quotes, the parser would only see the first word on the line.
Let's say you really need to embed a quote within your directive for some
reason.  You can do that too.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`NOTIFYCMD "/bin/notifyme -foo -bar \"hi there\" -baz"` \\
\end{LinePrinter}

In other words, \texttt{\bsl} can be used to escape the \texttt{"}.

When you need to put the \texttt{\bsl} character into your string, you just
escape it.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`NOTIFYCMD "/bin/notifyme c:\\dos\\style\\path"` \\
\end{LinePrinter}

The \texttt{\bsl} can be used to escape any character, but you only
really need it for \texttt{\bsl}, \texttt{"}, and \texttt{\#} as they have
special meanings to the parser.

When using file names with space characters, you may end up having tricky
things since you need to write them inside \texttt{""} which must be escaped:

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`NOTIFYCMD "\"c:\\path with space\\notifyme\""` \\
\end{LinePrinter}

\texttt{\#} is the comment character.  Anything after an unescaped \texttt{\#}
is ignored, e.g.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`identity = my#1ups` \\
\end{LinePrinter}

will turn into \texttt{identity = my}, since the \texttt{\#} stops the
parsing. If you really need to have a \texttt{\#} in your configuration, then
escape it.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`identity = my\#1ups` \\
\end{LinePrinter}

Much better.

The \texttt{=} character should be used with care too. There should be
only one ``simple'' \texttt{=} character in a line: between the
parameter name and its value.  All other \texttt{=} characters should
be either escaped or within ``quotes''.  Remember that the \texttt{\#}
character in a password must be escaped:

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk & \verb`password = 12=34#56`   \hspace{30mm}\textsl{Incorrect} \\
\Clunk & \verb`password = 12\=34\#56`  \hspace{30mm}\textsl{Good} \\
\Clunk & \verb`password = NUT=Awesome` \hspace{28mm}\textsl{Incorrect} \\
\Clunk & \verb`password = "NUT=Awesome"` \hspace{28mm}\textsl{Good} \\
\end{LinePrinter}

\subsubsection{\Hsep\ Line spanning}\label{linespan}

You can put a backslash at the end of the line to join it to the next
one.  This creates one virtual line that is composed of more than one
physical line.

Also, if you leave the \texttt{""} quote container open before a newline, it
will keep scanning until it reaches another one.  If you see bizarre behavior
in your configuration files, check for an unintentional instance of quotes
spanning multiple lines.


\subsection{\Hsep\ Mailing list: nut-users}\label{nut-users}

The NUT project offers a mailing list to assist the users.  The web page for
list administration is
\href{https://lists.alioth.debian.org/mailman/listinfo/nut-upsuser}%
{https://{\allowbreak}lists.alioth{\allowbreak}.debian.org/{\allowbreak}mailman/{\allowbreak}listinfo/{\allowbreak}nut-upsuser}.

As always in mailing lists, you get better results if you remember Eric
Raymond's good advice which you will find in ``How To Ask Questions The Smart
Way'' at \href{http://www.catb.org/esr/faqs/smart-questions.html}%
{http://{\allowbreak}www.catb.org/{\allowbreak}esr/{\allowbreak}faqs/{\allowbreak}smart-questions.html}.

The NUT mailing lists accept HTML formatted e-mails, but it's better to get
into the habit of sending only plain text, since you will meet mailing lists
that send HTML to \texttt{/dev/null}.

If you want to quote configuration files, please remove comments and blank
lines.  A command such as \verb`grep ^[^#] upsmon.conf` will do the job.  To
save you some work, there is ready-made script to prepare a report on a NUT
configuration. See \nutreport.

\subsection{\Hsep\ NUT has an RFC}\label{nut-RFC}

On August 8th, 2022, the IETF published \RFC\ which describes in
detail the commands and responses of the NUT protocol.  The RFC
follows changes in the technical terms used by the NUT Project and
listed in figure \ref{fig:terms}.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|}
\hline
                                   & \textbf{Term used in NUT 2.8.0,} \\
\textbf{Term used up to NUT 2.7.4} & \textbf{RFC 9271 and this document} \\ \hline\hline
{\tt ALREADY-LOGGED-IN}   & {\tt ALREADY-ATTACHED} \\ \hline
{\tt ALREADY-SSL-MODE}    & {\tt TLS-ALREADY-ENABLED} \\ \hline
{\tt LOGIN}               & {\tt ATTACH} \\ \hline
{\tt LOGOUT}              & {\tt DETACH} \\ \hline
Master                    & Primary \\ \hline
{\tt NETVER}              & {\tt PROTVER} \\ \hline
{\tt NUMLOGINS}           & {\tt NUMATTACH} \\ \hline
Slave                     & Secondary \\ \hline\hline
\end{tabular}
\caption{NUT terms changed by NUT 2.8.0 and the RFC.\label{fig:terms}}
\end{center}
\end{figure}

The RFC uses the term ``public power supply'' where this text refers to ``wall power''.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\textsl{Now that we have the basic ideas of NUT, we are ready to look at the
  first simple configuration.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage  % 
\newcolumn
\section{\Hsep\ Simple server with no local users}\label{section:server}

\textsl{This chapter extends the general ideas of chapter
  \ref{section:intro} to provide a fully worked example of a simple
  configuration.  This will in turn form the basis of future chapters.
  In this simple configuration, the \ad\ and the \md\ run in the same
  machine.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=server.pdf,width=0.75\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Server with no local users.\label{fig:server}}
\end{figure}

Six configuration files specify the operation of NUT in the simple server.

\ol

\li The NUT startup configuration: \nutconf.  Since this file is not strictly
a part of NUT, and is common to all configurations, it is discussed separately
in appendix \refpage{section:Start}.

\li The \upsd\ UPS declarations: \upsconf, see chapter \ref{section:upsconf}.

\li The \upsd\ daemon access control; \upsdconf, see chapter
\ref{section:upsdconf}.

\li The \upsd\ daemon user declarations: \upsdusers, see chapter
\ref{section:upsdusers}.

\li The \upsmon\ daemon configuration: \upsmonconf, see chapter
\ref{section:upsmonconf}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol


\subsection{\Hsep\ Configuration file \upsconf, first attempt}\label{section:upsconf}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-9mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# ups.conf, first attempt` \\
\Clunk[LP100]  & \verb`[UPS-1]` \\
\Clunk[LP101]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP102]  & \verb`   port = auto` \\
\Clunk[LP103]  & \verb`   desc = "Example Mfg 1600"` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsconf, first attempt.\label{fig:upsconf}}
\end{wrapfigure}

This configuration file declares your UPS units.  The file described here will
do the job, but we will see after we have discussed the shutdown process, that
useful improvements are possible. 

Line \ref{LP100} begins a UPS-specific section, and names the UPS unit
\texttt{UPS-1}.  There will as many sections as there are UPS units.  Make sure
this UPS name matches the name in \upsmonconf\ and in \upsschedcmd,
which we will meet in later chapters.

Line \ref{LP101} specifies the driver that \upsd\ will use.  For the full list
of drivers, see the Hardware Compatibility list and the required drivers at
\href{http://www.networkupstools.org/stable-hcl.html}%
{http://{\allowbreak}www.networkupstools.org/{\allowbreak}stable-hcl.html}.

Line \ref{LP102} depends on the driver. For the \usbhidups\ driver the
value is always \texttt{auto}.  For other drivers, see the man page for that
driver.

Line \ref{LP103} provides a descriptive text for the UPS.



\subsection{\Hsep\ Configuration file \upsdconf}\label{section:upsdconf}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-9mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.conf` \\
\Clunk[LP110]  & \verb`LISTEN 127.0.0.1 3493` \\
\Clunk[LP111]  & \verb`LISTEN ::1 3493` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsdconf.\label{fig:upsdconf}}
\end{wrapfigure}
%
This configuration file declares on which ports the \upsd\ daemon will listen,
and provides a basic access control mechanism.

Line \ref{LP110} declares that \upsd\ is to listen on it's prefered port for
traffic from the localhost.  The IP address specifies the interface on which
the \upsd\ daemon will listen.  The default 127.0.0.1 specifies the loopback
interface.  It is possible to replace 127.0.0.1 by 0.0.0.0 which says ``listen
for traffic from all sources'' and use your firewall to filter traffic to port
\IANAnut.  For good security, this file should be accessible to the \upsd\ process
only.

If you do not have IPv6, remove or comment out line \ref{LP111}.


\subsection{\Hsep\ Configuration file \upsdusers}\label{section:upsdusers}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-9mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.users` \\
\Clunk[LP120]  & \verb`[nut-admin]` \\
\Clunk[LP121]  & \verb`   password = sekret`\\
\Clunk[LP122]  & \verb`   upsmon primary`\\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsdusers\ for a simple server.\label{fig:upsdusers}}
\end{wrapfigure}
%
This configuration file declares who has write access to the UPS.  For
good security, ensure that only users nut\footnote{This is for Debian
11.  See table \ref{fig:UD} in appendix \ref{section:UD} for other user
names.} and root can read and write this file.

Line \ref{LP120} declares the ``user name'' of the system administrator who
has write access to the UPS's managed by \upsd.  It is independent of
\texttt{/etc/passwd}.  The \upsmon\ client daemon will use this name to poll
and command the UPS's.  There may be several names with different levels of
access.  For this example we only need one.

Line \ref{LP121} provides the password.  You may prefer something
better than ``sekret''.  \textbf{Warning:} Avoid placing spaces
\texttt{U+0020} and quotation marks \texttt{"} \texttt{U+0022} in
passwords.

Line \ref{LP122} declares that this user is the \upsmon\ daemon, and
the required set of actions will be set automatically.  In this simple
configuration daemon \upsmon\ is a \texttt{primary}\footnote{Up to NUT
2.7.4 the primary was known as the ``master''.  The secondary was
known as the ``slave''.} and has authority to shutdown the server.
The alternative, ``\texttt{upsmon secondary}", allows monitoring only,
with no shutdown authority.

The configuration file for \upsmon\ must match these declarations for
\upsmon\ to operate correctly.

For lots of details, see \NUTman{upsd.users}.

\subsection{\Hsep\ Configuration file \upsmonconf\ for a simple server}\label{section:upsmonconf}

This configuration file declares how \upsmon\ is to handle NOTIFY
events.  For good security, ensure that only users nut\footnote{This
is for Debian 11.  See table \ref{fig:UD} in appendix \ref{section:UD}
for other user names.} and root can read and write this file.

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP200]  & \verb`# upsmon.conf` \\
\Clunk[LP201]  & \verb`MONITOR UPS-1@localhost 1 nut-admin sekret primary` \\
%\Clunk[LP202]  & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a simple server, part 1 of 5.\label{fig:upsmonconf1}}
\end{figure}

On line \ref{LP201}

\ul

\li The UPS name \UPSi\ must correspond to that declared in \upsconf\ line
\ref{LP100}.

\li The ``power value'' \texttt{1} is the number of power supplies that this
UPS feeds on this system.

\li \texttt{nut-admin} is the ``user'' declared in \upsdusers\ line \ref{LP120}.

\li \texttt{sekret} is the password declared in \upsdusers\ line \ref{LP121}.

\li \texttt{primary} means this system will shutdown last, allowing any secondaries
time to shutdown first.  Secondary systems will be discussed in chapter
\ref{section:secondary}. There are no secondaries in this simple configuration.

\eul

\begin{figure}[ht]
\vspace{-6mm}
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP203]  & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\Clunk[LP209]  & \verb`POWERDOWNFLAG /etc/killpower` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a simple server, part 2 of 5.\label{fig:upsmonconf2}}
\end{figure}

Line \ref{LP203} declares the command that is to be used to shut down the
server.  A second instance of the \upsmon\ daemon running as root will execute
this command.  Multiple commands are possible, for example \texttt{SHUTDOWNCMD
  "logger -t upsmon.conf \bsl"SHUTDOWNCMD calling /sbin/shutdown to shut down
  system\bsl" ; /sbin/shutdown -h +0"} will also log the action of
\texttt{SHUTDOWNCMD}.  Note that internal " have to be escaped.

Line \ref{LP209} declares a file created by \upsmon\ when running in primary
mode when the UPS needs to be powered off.  It will be used in more complex
configurations.  See \NUTman{upsmon.conf} for details.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP217]  & \verb`NOTIFYMSG ONLINE   "UPS %s: On line power."` \\
\Clunk[LP216]  & \verb`NOTIFYMSG ONBATT   "UPS %s: On battery."` \\
\Clunk[LP213]  & \verb`NOTIFYMSG LOWBATT  "UPS %s: Battery is low."` \\
\Clunk[LP218]  & \verb`NOTIFYMSG REPLBATT "UPS %s: Battery needs to be replaced."` \\
\Clunk[LP212]  & \verb`NOTIFYMSG FSD      "UPS %s: Forced shutdown in progress."` \\
\Clunk[LP219]  & \verb`NOTIFYMSG SHUTDOWN "Auto logout and shutdown proceeding."` \\
\Clunk[LP211]  & \verb`NOTIFYMSG COMMOK   "UPS %s: Communications (re-)established."` \\
\Clunk[LP210]  & \verb`NOTIFYMSG COMMBAD  "UPS %s: Communications lost."` \\
\Clunk[LP214]  & \verb`NOTIFYMSG NOCOMM	  "UPS %s: Not available."` \\
\Clunk[LP215]  & \verb`NOTIFYMSG NOPARENT "upsmon parent dead, shutdown impossible."` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a simple server, part 3 of 5.\label{fig:upsmonconf3}}
\end{figure}

Lines \ref{LP217}-\ref{LP215} assign a text message to each NOTIFY event.
Within each message, the marker \texttt{\%s} is replaced by the name of the
UPS which has produced this event.  \upsmon\ passes this message to program
\texttt{wall} to notify the system administrator of the event.  You can change
the default messages to something else if you like.  The format is
\texttt{NOTIFYMSG event "\textsl{message}"} where \texttt{\%s} is replaced
with the identifier of the UPS in question.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP227]  & \verb`NOTIFYFLAG ONLINE   SYSLOG+WALL` \\
\Clunk[LP226]  & \verb`NOTIFYFLAG ONBATT   SYSLOG+WALL` \\
\Clunk[LP223]  & \verb`NOTIFYFLAG LOWBATT  SYSLOG+WALL` \\
\Clunk[LP228]  & \verb`NOTIFYFLAG REPLBATT SYSLOG+WALL` \\
\Clunk[LP222]  & \verb`NOTIFYFLAG FSD      SYSLOG+WALL` \\
\Clunk[LP229]  & \verb`NOTIFYFLAG SHUTDOWN SYSLOG+WALL` \\
\Clunk[LP221]  & \verb`NOTIFYFLAG COMMOK   SYSLOG+WALL` \\
\Clunk[LP220]  & \verb`NOTIFYFLAG COMMBAD  SYSLOG+WALL` \\
\Clunk[LP224]  & \verb`NOTIFYFLAG NOCOMM   SYSLOG+WALL` \\
\Clunk[LP225]  & \verb`NOTIFYFLAG NOPARENT SYSLOG+WALL` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a simple server, part 4 of 5.\label{fig:upsmonconf4}}
\end{figure}

Lines \ref{LP227}-\ref{LP225} declare what is to be done at each NOTIFY event.
The declarations, known as ``flags'' are shown in table \ref{fig:flags}. You
may specify one, two or three flags for each event, in the form
\texttt{FLAG[+FLAG]*}, however \texttt{IGNORE} must always be alone.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|p{0.75\LinePrinterwidth}|}
\hline
\texttt{IGNORE}    & Don't do anything.  Must be the only flag on the line. \\ \hline
\texttt{SYSLOG}    & Write the message in the system log. \\ \hline
\texttt{WALL}      & Use program \texttt{wall} to send message to terminal users.
                     Note that \texttt{wall} does not support accented letters or non-latin
                     characters. \\ \hline
\texttt{EXEC}      & \textsl{(Not used for this simple server example)}. \\ \hline
\end{tabular}
\caption{Flags declaring what \upsmon\ is to do for NOTIFY events.\label{fig:flags}}
\end{center}
\end{figure}

Note that if you have multiple UPS's, the same actions are to be performed for
a given NOTIFY event for all the UPS's.  \textsl{We will see later that this
  is not good news.}

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP230]  & \verb`RBWARNTIME 43200` \\
\Clunk[LP231]  & \verb`NOCOMMWARNTIME 300` \\
\Clunk[LP232]  & \verb`FINALDELAY 5` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a simple server, part 5 of 5.\label{fig:upsmonconf5}}
\end{figure}

When a UPS says that it needs to have its battery replaced, upsmon will
generate a \NOTev{\REPLBATT}\ NOTIFY event.  Line \ref{LP230} say that this happens
every \texttt{RBWARNTIME} = 43200 seconds (12 hours).

Line \ref{LP231}: Daemon \upsmon\ will trigger a \NOTev{\NOCOMM}\ NOTIFY event after
\texttt{NOCOMMWARNTIME} seconds if it can't reach any of the UPS entries in
configuration file \upsmonconf.  It keeps warning you until the situation is
fixed.

Line \ref{LP232}: When running in primary mode, \upsmon\ waits this long after
sending the \NOTev{\SHUTDOWN}\ NOTIFY event to warn the users. After the timer
elapses, it then runs your \texttt{SHUTDOWNCMD} as specified on line
\ref{LP203}.  If you need to let your users do something in between those
events, increase this number. Remember, at this point your UPS battery is
almost depleted, so don't make this too big.  Alternatively, you can set this
very low so you don't wait around when it's time to shut down. Some UPS's
don't give much warning for low battery and will require a value of 0 here for
a safe shutdown.

For lots and lots of details, see \NUTman{upsmon.conf}.  See also the file
\href{https://github.com/networkupstools/nut/blob/master/docs/config-notes.txt}
     {\texttt{config{\allowbreak}-notes.txt}} in the distribution.

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ The delayed UPS shutdown}\label{section:delayedUPSshutdown}

\begin{wrapfigure}{l}{0.6\LinePrinterwidth}
\vspace{-6mm}
\begin{center}
   \epsfig{file=delayedUPSshutdown,width=0.6\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Delayed UPS shutdown.\label{fig:delayedUPSshutdown}}
\end{wrapfigure}
%
Somewhere in your distribution, as part of the system shutdown process, there
needs to be an action to send a message to the UPS to tell it that some time
later, it too will shut down.  Note that the UPS does not shutdown at the same
time as the system it protects.  The UPS shutdown is \textbf{delayed}.  By
default the delay is 20 seconds.  We will see in a later chapter how to change
this. (Line \refpage{LP104} if you're curious.)

The delayed UPS shutdown command may be from a shell script or a
systemd service unit but in all cases the key element is the command
\texttt{upsdrvctl shutdown}.

Figure \ref{fig:delayedUPSshutdown-Debian} shows the shell script
supplied by NUT to be placed in a systemd ``drop-in'' directory for
scripts which should be executed as late as possible during a system
shutdown.  This script is used by openSUSE and Debian 11 and is placed
in file
\texttt{/usr{\allowbreak}/lib{\allowbreak}/systemd{\allowbreak}/system-shutdown{\allowbreak}/nutshutdown}\ .
systemd detects automatically that a script in one of these
``drop-in'' directories needs to be executed. There is no need to
enable the script.

\begin{figure}[ht]
\begin{LinePrinter}[0.97\LinePrinterwidth]
\Clunk         & \verb` #!/bin/sh` \\
\Clunk         & \verb` /usr/sbin/upsmon -K >/dev/null 2>&1 && /usr/sbin/upsdrvctl shutdown` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{openSUSE script for delayed UPS shutdown.\label{fig:delayedUPSshutdown-Debian}}
\end{figure}

Gentoo users: see Denny Page's post at
\href{https://alioth-lists.debian.net/pipermail/nut-upsuser/2018-July/011172.html}%
     {https://alioth-lists{\allowbreak}.debian.net/{\allowbreak}pipermail/nut-upsuser{\allowbreak}/2018-July/{\allowbreak}011172.html}\ .

In all these cases, the file name ``\texttt{nutshutdown}'' seems to me to
be a misnomer, since it is not NUT which is being shut down, but such
naming sloppiness is common.

\colorbox{yellow}{Warning}: This script is executed late in the system
shutdown process, and there is no trace in the system log of it's
action.  If, like the editor, you believe that shutting off power to a
system is a major event, and should be logged, then you are invited to
replace the script provided by NUT with a systemd service unit as
shown in appendix \ref{section:Stop} which will log the delayed
shutdown command.


\newcolumn
\subsection{\Hsep\ The shutdown story for a simple server}\label{section:story:server}

\textsl{We are now ready to tell the detailed story of how the server gets
  shut down when wall power fails, and how it restarts when wall power
  returns.}

\ol 

\li\label{serverOL} \textbf{Wall power on} \quad The system runs
normally. In the \ad\ the \upsd\ status is \status{\OL}. No NOTIFY event.

\textsl{Days, weeks, months go by...}

\li \textbf{Wall power fails} \quad The server remains operational running on
the UPS battery.  \upsd\ polls the UPS, and detects status change
\statuschange{\OL}{\OB}.

\li In the \md, \upsmon\ polls \upsd, receives \status{\OB} and issues
NOTIFY event \NOTev{\ONBATT}.  As instructed by line \ref{LP226}, an
\NOTev{\ONBATT}\ message goes to syslog and to program \texttt{wall}.
The server is still operational running on the UPS battery.

\textsl{Minutes go by...}

\li \textbf{Battery discharges below \texttt{battery.charge.low}} \quad The
server remains operational, but the UPS battery will not last much longer.
\upsd\ polls the UPS, and detects status change
\statuschange{\OB}{\OB\ \LB}.

\li \upsmon\ polls \upsd, receives \status{\OB\ \LB} and issues new
NOTIFY event \NOTev{\LOWBATT}.  As instructed by line \ref{LP223}
\upsmon\ sends a \NOTev{\LOWBATT}\ message to syslog and to program
\texttt{wall}.

\li\label{serverLB} \upsmon\ decides to command a system shutdown and
generates NOTIFY event \NOTev{\SHUTDOWN}.  It also sends command
\texttt{FSD} to \upsd\ to tell any secondaries that they must shut down.
There are no secondaries in this simple configuration.

\li \upsmon\ uses command
\texttt{NUMATTACH}\footnote{\texttt{NUMATTACH} was known as
\texttt{NUMLOGINS} up to NUT 2.7.4.} to query the number of
secondaries currently operational.  In this simple configuration, the
reply is 1, there are no secondaries and the primary may proceed to
shut down.

\li \upsmon\ waits \texttt{FINALDELAY} seconds as specified on line \ref{LP232}.

\li \upsmon\ creates \texttt{POWERDOWN} flag specified on line \ref{LP209}.

\li \upsmon\ calls the \texttt{SHUTDOWNCMD} specified on line \ref{LP203}.

\li We now enter the scenario described in figure
\ref{fig:delayedUPSshutdown}.  The operating system's shutdown process takes
over.  During the system shutdown, the Bash script shown in figure
\ref{fig:delayedUPSshutdown-Debian} or equivalent systemd service unit or some
other equivalent runs the command \texttt{upsdrvctl shutdown} .  This tells
the UPS that it is to shut down 20 seconds later.

\li The system powers down, hopefully before the 20 seconds have passed.

\li \textbf{UPS shuts down} \quad 20 seconds have passed.  With some UPS
units, there is an audible ``clunk''.  The UPS outlets are no longer powered.
The absence of AC power to the protected system for a sufficient time has the
effect of resetting the BIOS options, and in particular the option ``Restore
power on AC return''.  This BIOS option will be needed to restart the box.
How long is a sufficient time for the BIOS to reset?  This depends very much
on the box.  Some need more than 10 seconds.  What if wall power returns
before the ``sufficient time'' has elapsed?  The UPS unit will wait until the
time specified by the \texttt{ondelay} option in file \upsconf.  This timer,
like the \texttt{offdelay} timer, starts from the moment the UPS receives the
\texttt{upsdrvctl shutdown} command.  See line \ref{LP105} in figure
\ref{fig:upsconf,improved}.

\textsl{Minutes, hours, days go by...}

\li \textbf{Wall power returns} \quad Some time later, maybe much later, wall
power returns.  The UPS reconnects it's outlets to send power to the protected
system.  

\li The system BIOS option ``Restore power on AC return'' has hopefully been
selected and the system powers up.  The bootstrap process of the operating
system begins.

\li\label{serverUP} The operating system starts the NUT daemons
\upsd\ and \upsmon.  Daemon \upsd\ starts the driver(s) and scans the
UPS.  The UPS status becomes \status{\OL\ \LB}.  Daemon \upsmon\ sends
command \texttt{ATTACH}\footnote{\texttt{ATTACH} was known as
\texttt{LOGIN} up to NUT 2.7.4.} to \upsd\ to advise \upsd\ that the
primary is operational, i.e. the number of attached systems is $\geq$
1.

\li After some time, the battery charges above the \texttt{battery.charge.low}
threshold and \upsd\ declares the status change \statuschange{\OL\ \LB}{\OL}.
We are now back in the same situation as state \ref{serverOL} above.

\eol

\vspace*{\fill}
\begin{wrapfigure}[4]{l}{0.20\LinePrinterwidth}
\vspace{-6mm}
   \epsfig{file=Danger.png,width=0.15\LinePrinterwidth}
\vspace{-6mm}
\end{wrapfigure}
%
As we saw in figure \ref{fig:delayedUPSshutdown}, there is a danger that the
system will take longer than 20 seconds to shut down.  If that were to happen,
the UPS shutdown would provoke a brutal system crash.  To alleviate this
problem, the next chapter proposes an improved configuration file \upsconf.
\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ Configuration file \upsconf\ for a simple server, improved}\label{section:upsconf.improved}

Let's revisit this configuration file which declares your UPS units.

\begin{wrapfigure}{l}{0.55\LinePrinterwidth}
\vspace{-6mm}
\begin{center}
\begin{LinePrinter}[0.45\LinePrinterwidth]
\Clunk         & \verb`# ups.conf, improved` \\
\Clunk         & \verb`[UPS-1]` \\
\Clunk         & \verb`   driver = usbhid-ups` \\
\Clunk         & \verb`   port = auto` \\
\Clunk         & \verb`   desc = "Example Mfg 1600"` \\
\Clunk[LP104]  & \verb`   offdelay = 60` \\
\Clunk[LP105]  & \verb`   ondelay = 70` \\
\Clunk[LP10A]  & \verb`   lowbatt = 33` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsconf, improved.\label{fig:upsconf,improved}}
\end{wrapfigure}

New line \ref{LP104} increases from the default 20 secs to 60 secs the time
that passes between the \texttt{upsdrvctl shutdown} command and the moment the
UPS shuts itself down.

Line \ref{LP105} increases the time that must pass between the
\texttt{upsdrvctl shutdown} command and the moment when the UPS will react to
the return of wall power and turn on the power to the system.  Even if wall
power returns earlier, the UPS will wait \texttt{ondelay = 70} seconds before
powering itself on.  The default is 30 seconds.

The \texttt{ondelay} \textbf{must} be greater than the \texttt{offdelay}.  See
\NUTman{ups.conf} for more news about this configuration file.

Additional line \ref{LP10A} sets the default value for \batterychargelow.
Even if you use command \upsrw\ to set a value for \batterychargelow,
\usbhidups\ and some other drivers\footnote{List needed} will restore the
default, so if you want a permanent change you must change the default.  See
also chapter \ref{section:upsrw}.

%\newcolumn
\subsection{\Hsep\ The shutdown story with quick power return}\label{section:story:quick}

\textsl{What happens if power returns after the system shuts down but before
  the UPS delayed shutdown?  We pick up the story from state \refpage{serverLB}.}

\ol 

\setcounter{enumi}{5}

\li \upsmon\ decides to command a system shutdown and generates NOTIFY
event \NOTev{\SHUTDOWN}.  It also sends command \texttt{FSD} to
\upsd\ to tell any secondaries that they must shut down.  There are no
secondaries in this simple configuration.

\li \upsmon\ uses command \texttt{NUMATTACH} to query the number of
secondaries currently oerational.  In this simple configuration, the
reply is 1, since there are no secondaries.  The primary may proceed
to shut down.

\li \upsmon\ waits \texttt{FINALDELAY} seconds as specified on line \ref{LP232}.

\li \upsmon\ creates \texttt{POWERDOWN} flag specified on line \ref{LP209}.

\li \upsmon\ calls the \texttt{SHUTDOWNCMD} specified on line \ref{LP203}.

\li We now enter the scenario described in figure
\ref{fig:delayedUPSshutdown}.  The operating system's shutdown process takes
over.  During the system shutdown, the Bash script shown in figure
\ref{fig:delayedUPSshutdown-Debian} or equivalent systemd service unit or some
other equivalent runs the command \texttt{upsdrvctl shutdown} .  This tells
the UPS that it is to shut down \texttt{offdelay} seconds later .

\li The system powers down before \texttt{offdelay} seconds have passed.

\li \textbf{Wall power returns before the UPS shuts down} \quad Less than
\texttt{offdelay} seconds have passed.  The UPS continues it's shutdown
process.

\li After \texttt{offdelay} seconds the UPS shuts down, disconnecting it's
outlets.  The beeping stops.  With some UPS units, there is an audible
``clunk''.

\textsl{An interval of} \texttt{ondelay}-\texttt{offdelay} \textsl{seconds later}

\li After \texttt{ondelay} seconds the UPS turns itself on, and repowers it's
outlets

\li The system BIOS option ``restore power on AC return'' has hopefully been
selected and the system powers up.  The bootstrap process of the operating
system begins.

\eol

\textsl{The story continues at state \refpage{serverUP} in chapter
  \ref{section:story:server}.}

\subsection{\Hsep\ Utility program \upscmd}\label{section:upscmd}

Utility program \upscmd\ is a command line program for sending commands
directly to the UPS.  To see what commands your UPS will accept, type
\texttt{upscmd -l \textsl{ups-name}} where \texttt{\textsl{ups-name}} is the
name of the UPS as declared in file \upsconf, line \refpage{LP100}.

\noindent For example, to turn on the beeper, use command

\verb`upscmd -u nut-admin -p sekret UPS-1@localhost beeper.enable`

\noindent where \texttt{nut-admin} is the user declared on line \ref{LP120} and sekret
is the l33t password declared on line \ref{LP121} in file \upsdusers.

Command \upscmd\ can be dangerous.  Make sure that file \upsdusers\ can be
read and written by root only.  See \NUTman{upscmd} for more detail.

%\newcolumn
\subsection{\Hsep\ Utility program \upsrw}\label{section:upsrw}

Utility program \upsrw\ is a command line program for changing the values of
UPS variables.  To see which variables may be changed, type \texttt{upsrw
  \textsl{ups-name}} where \texttt{\textsl{ups-name}} is the name of the UPS
as declared in file \upsconf, line \refpage{LP100}.

\noindent For example, at line \refpage{L:low} we saw that the
\batterychargelow\ has been set to 50.  We will change this to something less
conservative with command

\verb`upsrw -s battery.charge.low=33 -u nut-admin -p sekret UPS-1@localhost`

\noindent where \texttt{nut-admin} is the user declared on line \ref{LP120}
and \texttt{sekret} is the password declared on line \ref{LP121} in file
\upsdusers.  Now check that the value has been set with command

\verb`upsc UPS-1 battery.charge.low`

\noindent which returns the value 33.

Once again, command \upsrw\ can be dangerous.  Make sure that file
\upsdusers\ can be read and written by root only.  See \NUTman{upsrw} for more
detail.

Some drivers, for example \usbhidups, reset \batterychargelow\ to the default
value when they start.  To overcome this resistance, add the line
\texttt{lowbatt = 33} to the UPS definition in file \upsconf\ as shown on line
\ref{LP10A}.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\textsl{This chapter has described a basic configuration which is deficient in
  several ways:}

\ul

\li \textsl{NUT messages are only available to those users who are constantly
  in front of text consoles which display the output of the program
  \texttt{wall}.  Systems with users of graphical interfaces which do not
  display wall output will need stronger techniques.}

\li \textsl{Program \texttt{wall} has not been internationalised.  It cannot
  display letters with accents or any non-latin character.}

\eul
 
\textsl{Chapter \ref{section:workstation} will show how to overcome these
  difficulties.}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage  
\newcolumn
\section{\Hsep\ Server with multiple power supplies}\label{section:dual}

\textsl{This chapter extends the ideas of chapter \ref{section:server} to
  cover a larger server which has multiple, hopefully independent power
  supplies.  The server is capable of running on two or more power supplies,
  but must be shut down if there are less than two operational.  The
  flexibility of NUT makes this configuration easy: we will describe only the
  modifications to the configuration in chapter \ref{section:server}.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=dual.pdf,width=0.95\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Server with multiple power supplies.\label{fig:dual}}
\end{figure}

Six configuration files specify the operation of NUT in the server with multiple
power supplies.

\ol

\li The NUT startup configuration: \nutconf.  Since this file is not strictly
a part of NUT, and is common to all configurations, it is discussed separately
in appendix \refpage{section:Start}.

\li The \upsd\ UPS declarations: \upsconf, see chapter \ref{section:upsconf.dual}.

\li The \upsd\ daemon access control; \upsdconf\ does not change, see chapter
\ref{section:upsdconf}.

\li The \upsd\ daemon user declarations: \upsdusers\ do not change, see chapter
\ref{section:upsdusers}.

\li The \upsmon\ daemon configuration: \upsmonconf, see chapter
\ref{section:upsmonconf.dual}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol


\subsection{\Hsep\ Configuration file \upsconf\ for multiple power supplies}\label{section:upsconf.dual}

\begin{figure}[ht]
\begin{tabular}{cp{5mm}c}
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# ups.conf, 4 power supplies`  \\
\Clunk[LP140]  & \verb`[UPS-1]` \\
\Clunk[LP141]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP142]  & \verb`   port = auto` \\
\Clunk[LP143]  & \verb`   desc = "Power supply 1"` \\
%\Clunk[LP144]  & \verb`   offdelay = 60` \\
%\Clunk[LP145]  & \verb`   ondelay = 70` \\
\Clunk[LP14X]  & \verb`   lowbatt = 33` \\
\Clunk[LP14C]  & \verb`   serial = 47014` \\
\Clunk[LP146]  & \verb`[UPS-2]` \\
\Clunk[LP147]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP148]  & \verb`   port = auto` \\
\Clunk[LP149]  & \verb`   desc = "Power supply 2"` \\
%\Clunk[LP14A]  & \verb`   offdelay = 60` \\
%\Clunk[LP14B]  & \verb`   ondelay = 70` \\
\Clunk[LP14Y]  & \verb`   lowbatt = 33` \\
\Clunk[LP14D]  & \verb`   serial = 47015` \\
\end{LinePrinter}
\end{minipage}
& &
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk[LP14E]  & \verb`[UPS-3]` \\
\Clunk[LP14F]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP14G]  & \verb`   port = auto` \\
\Clunk[LP14H]  & \verb`   desc = "Power supply 3"` \\
%\Clunk[LP14I]  & \verb`   offdelay = 60` \\
%\Clunk[LP14J]  & \verb`   ondelay = 70` \\
\Clunk[LP14Z]  & \verb`   lowbatt = 33` \\
\Clunk[LP14K]  & \verb`   serial = 47024` \\
\Clunk[LP14L]  & \verb`[UPS-4]` \\
\Clunk[LP14M]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP14N]  & \verb`   port = auto` \\
\Clunk[LP14P]  & \verb`   desc = "Power supply 4"` \\
%\Clunk[LP14Q]  & \verb`   offdelay = 60` \\
%\Clunk[LP14R]  & \verb`   ondelay = 70` \\
\Clunk[LP14W]  & \verb`   lowbatt = 33` \\
\Clunk[LP14S]  & \verb`   serial = 47025` \\
\end{LinePrinter}
\end{minipage} \\
\end{tabular}
\caption{File \upsconf\ for multiple power supplies.\label{fig:upsconf.dual}}
\end{figure}

We add additional sections to \upsconf\ to declare the additional UPS units
but we need some way of distinguishing them.  Assuming the \usbhidups\
driver, \NUTman{usbhid-ups} describes how this can be done.

Driver \usbhidups\ distinguishes multiple UPS units with some
combination of the \texttt{vendor}, \texttt{product}, \texttt{serial}
and \texttt{vendorid} options that it provides.  For other drivers,
which do not provide the ability to distinguish UPS units, or for UPS
units which have no serial number, see
\href{https://github.com/networkupstools/nut/issues/597}%
     {the comment by Charles Lepple in NUT issue \#597} at
  \href{https://github.com/{\allowbreak}networkupstools/{\allowbreak}nut/issues/{\allowbreak}597}%
       {https://github.com/networkupstools/nut/issues/597}.

Let's assume that the UPS units used in this configuration are sophisticated
products and are capable of reporting their serial numbers.  You can check
this with command \texttt{upsc \UPSi{\allowbreak}@localhost ups.serial} .  In
lines \ref{LP14C}, \ref{LP14D}, \ref{LP14K} and \ref{LP14S} we use this
information to distinguish \UPSi\ with \texttt{serial = 47014}, \UPSii\ with
\texttt{serial = 47015}, etc.

See \NUTman{ups.conf} and \NUTman{usbhid-ups}.


\subsection{\Hsep\ Configuration file \upsmonconf\ for multiple power supplies}\label{section:upsmonconf.dual}

This configuration file declares how \upsmon\ is to handle NOTIFY
events from the UPS units.  For good security, ensure that only users
nut\footnote{This is for Debian 11.  See table \ref{fig:UD} in
appendix \ref{section:UD} for other user names.} and root can read and
write this file.

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP150]  & \verb`# upsmon.conf, multiple power supplies` \\
\Clunk[LP151]  & \verb`MONITOR UPS-1@localhost 1 nut-admin sekret primary` \\
\Clunk[LP152]  & \verb`MONITOR UPS-2@localhost 1 nut-admin sekret primary` \\
\Clunk[LP153]  & \verb`MONITOR UPS-3@localhost 1 nut-admin sekret primary` \\
\Clunk[LP154]  & \verb`MONITOR UPS-4@localhost 1 nut-admin sekret primary` \\
\Clunk[LP155]  & \verb`MINSUPPLIES 2` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for multiple power supplies, part 1 of 5.\label{fig:upsmonconf.dual}}
\end{figure}

On lines \ref{LP151}-\ref{LP154}

\ul

\li The UPS names \UPSi, \UPSii, etc. must correspond to those declared in
\upsconf\ lines \ref{LP140}, \ref{LP146}. \ref{LP14E} and \ref{LP14L}.

\li The ``power value'' \texttt{1} is the number of power supplies that each
UPS feeds on this system.

\li \texttt{nut-admin} is the ``user'' declared in \upsdusers\ line \ref{LP120}.

\li \texttt{sekret} is the password declared in \upsdusers\ line \ref{LP121}.

\li \texttt{primary} means this system will shutdown last, allowing any secondaries
time to shutdown first.  Secondary systems will be discussed in chapter
\ref{section:secondary}. There are no secondaries in this configuration.

\eul

Line \ref{LP155}, \texttt{MINSUPPLIES}, declares that at least two power
supplies must be operational, and that if fewer are available, NUT must shut
down the server. Figure \ref{fig:dual} shows that currently two of the four
power supplies are operational.  The \status{\OB\ \LB} of \UPSii, which would
have caused a system shutdown in the case of the simple server in chapter
\ref{section:server} is not sufficient to provoke a system shutdown in this
case.  \UPSiii\ has been disconnected and will be removed in order to paint
the wall behind it.  (Have you ever worked for Big Business IT, or for Big
Government IT?).

The remainder of \upsmonconf\ is the same as that for the simple server of
chapter \ref{section:server}, figures \ref{fig:upsmonconf2}-\ref{fig:upsmonconf5}.


\subsection{\Hsep\ Shutdown conditions for multiple power supplies}\label{section:shutdown.dual}

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP160]  & \verb`rprice@maria:~> for i in {1..100}` \\
\Clunk[LP161]  & \verb`> do upsc UPS-1 ups.status 2>&1` \\
\Clunk[LP162]  & \verb`> sleep 5s` \\
\Clunk[LP163]  & \verb`> done` \\
\Clunk[LP164]  & \verb`OL CHRG` \\
\Clunk[LP165]  & \verb`OL CHRG` \\
               & \hspace{20mm}\fbox{\textsl{Action: disconnect UPS-1 USB cable}} \\
\Clunk[LP166]  & \verb`Broadcast Message from upsd@maria` \\
\Clunk[LP168]  & \verb`UPS UPS-1@localhost: Communications lost` \\
\Clunk[LP169]  & \verb`Error: Data stale` \\
\Clunk[LP16A]  & \verb`Error: Data stale` \\
               & \hspace{20mm}\fbox{\textsl{Action: reconnect UPS-1 USB cable}} \\
\Clunk[LP16B]  & \verb`Broadcast Message from upsd@maria` \\
\Clunk[LP16D]  & \verb`UPS UPS-1@localhost: Communications (re-)established` \\
\Clunk[LP16E]  & \verb`OL CHRG` \\
\Clunk[LP16F]  & \verb`OL CHRG` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Experiment to show effect of lost UPS. Part 1,\label{fig:lostUPS.1}}
\end{figure}

The value of \texttt{MINSUPPLIES} is the key element in determining if a
server with multiple power supplies should shut down.  When all the UPS units
can be contacted, and when their \texttt{ups.status} values are known, then it
is the count $A$ of those that are active, that is without \status{\LB}, which
is determinant.

\begin{center}
If $A$ $\geq$ \texttt{MINSUPPLIES} then OK else shutdown.
\end{center}

\textbf{\UPSiii: What is the value of $A$?} \quad The situation for those UPS
units such as \UPSiii\ is more delicate.  If a UPS unit had been reporting the
status \status{\OL}, then if communication is lost, NUT assumes that the UPS
is still operational.  Command \texttt{upsc \UPSiii@localhost ups.status} will
return the error message ``Error: Data stale'', \upsmon\ will raise the NOTIFY
event \NOTev{\COMMBAD} and the sysadmin will receive the ``Communications
lost'' message shown on line \ref{LP210}.  However this does not count as an
\status{\LB}.

You can verify this yourself on a simple working configuration such as that of
chapter \ref{section:server} using the Bash command shown on lines
\ref{LP160}-\ref{LP163} in figure \ref{fig:lostUPS.1}.  Disconnecting the USB
cable on a \underline{healthy} UPS does not cause a system shutdown.

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP170]  & \verb`rprice@maria:~> for i in {1..100}` \\
\Clunk[LP171]  & \verb`> do upsc UPS-1 ups.status 2>&1` \\
\Clunk[LP172]  & \verb`> sleep 5s` \\
\Clunk[LP173]  & \verb`> done` \\
\Clunk[LP174]  & \verb`OL CHRG` \\
\Clunk[LP175]  & \verb`OL CHRG` \\
               & \hspace{20mm}\fbox{\textsl{Action: disconnect wall power}} \\
\Clunk[LP176]  & \verb`OB` \\
\Clunk[LP177]  & \verb`OB` \\
               & \hspace{20mm}\fbox{\textsl{Action: disconnect UPS-1 USB cable}} \\
\Clunk[LP178]  & \verb`Broadcast Message from upsd@maria` \\
\Clunk[LP179]  & \verb`UPS UPS-1@localhost: Communications lost` \\
\Clunk[LP17A]  & \verb`Error: Data stale` \\
\Clunk[LP17B]  & \verb`Error: Data stale` \\
               & \hspace{20mm}\fbox{\textsl{Result: system shutdown}} \\
\end{LinePrinter}
\caption{Experiment to show effect of lost UPS. Part 2,\label{fig:lostUPS.2}}
\end{figure}

However, as shown in figure \ref{fig:lostUPS.2}, disconnecting the USB lead on
a \underline{sick} UPS causes a rapid system shutdown.  If a UPS unit had been
reporting the status \status{\OB}, then if communication is lost, NUT assumes
that the UPS is about to reach status \status {\OB\ \LB} and calls for a immediate
system shutdown.

So the value of $A$ depends not only on the current situation, but also on how
the system got into that state.

The moral of our story is that NUT will play safe, but you must be very
careful who has access to your server room.  We will see in later chapters
that there are ways of reinforcing the feedback to the sysadmin.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\textsl{This chapter has described a complex UPS configuration in isolation,
  but in practice such a configuration would be just a part of a complete
  server room, and the use of NUT would have to be integrated with the rest of
  the server room power management.  The layered design of NUT makes this
  integration possible.}



\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-3.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\textsl{A recent book\footnote{``The Backup Book: Disaster Recovery
  from Desktop to Data Center'' by Dorian J. Cougias, E. L. Heiberger,
  Karsten Koop, Schaser-Vartan Books, 2003, ISBN 0-9729039-0-9, 755
  pages.}  for managers on disaster recovery discusses UPS units.  On
  page 559 it says ``We chose to have just one UPS do the paging
  ... We do it on low battery for one of the UPSes that has a
  15-minute run-time.''  Clearly they wanted a timed action, but the
  only way they could get it was by running down a UPS until it
  reached} \status{\LB}.  \textsl{NUT is capable of doing a lot
  better, as we will show in later chapters.}

\vspace*{\fill}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage  
\newcolumn
\section{\Hsep\ Workstation with local users}\label{section:workstation}

\textsl{This chapter extends the ideas of chapter \ref{section:server} to
  provide a fully worked example of a configuration which includes a simple
  user provided script.  This will in turn form the basis for future chapters.}

\textsl{There are two approaches possible for supporting user scripts:}

\ol 

\li \textsl{Directly from \upsmon\ using \texttt{NOTIFYCMD}.}

\li \textsl{Indirectly via \upssched\ and \texttt{CMDSCRIPT}.}

\eol

\textsl{We choose the latter since this introduces \upssched, which will be
  needed later.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=workstation.pdf,width=0.95\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Workstation with local users.\label{fig:workstation}}
\end{figure}

Eight configuration files specify the operation of NUT in the workstation.

\ol

\li The NUT startup configuration: \nutconf.  Since this file is not strictly
a part of NUT, and is common to all configurations, it is discussed separately
in appendix \refpage{section:Start}.

\li The \upsd\ UPS declarations: The improved file \upsconf\ as given in chapter
\refpage{section:upsconf.improved} does not change.

\li The \upsd\ daemon access control: File \upsdconf\ as given in chapter
\refpage{section:upsdconf} does not change.

\li The \upsd\ user declarations: File \upsdusers\ as given in chapter
\refpage{section:upsdusers} does not change.

\li The \upsmon\ daemon configuration: \upsmonconf.  See chapter
\ref{section:upsmonconf2}.

\li The \upssched\ configuration: \upsschedconf.   See chapter
\ref{section:upsschedconf2}.

\li The \upsschedcmd\ script: see chapter \ref{section:upsschedcmd}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol

\newcolumn
\subsection{\Hsep\ Configuration file \upsmonconf\ for a workstation}\label{section:upsmonconf2}

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP300]  & \verb`# upsmon.conf` \\
\Clunk[LP301]  & \verb`MONITOR UPS-1@localhost 1 nut-admin sekret primary` \\
\Clunk[LP302]  & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation, part 1 of 5.\label{fig:upsmonconf11}}
\end{figure}

This configuration file declares how \upsmon\ is to handle NOTIFY
events.  For good security, ensure that only users nut\footnote{This
is for Debian 11.  See table \ref{fig:UD} in appendix \ref{section:UD}
for other user names.} and root can read and write this file.

Line \ref{LP301} is the same as line \ref{LP201} in the previous chapter.

On line \ref{LP302}, \texttt{MINSUPPLIES} sets the number of power
supplies that must be receiving power to keep this system
running. Computers commonly have just one power supply, so the default
value of 1 is acceptable. See \NUTman{upsmon.conf} for more details.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP303]  & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\Clunk[LP304]  & \verb`NOTIFYCMD /usr/sbin/upssched` \\
\Clunk[LP305]  & \verb`POLLFREQ 5` \\
\Clunk[LP306]  & \verb`POLLFREQALERT 5` \\
\Clunk[LP307]  & \verb`HOSTSYNC 15` \\
\Clunk[LP308]  & \verb`DEADTIME 15` \\
\Clunk[LP309]  & \verb`POWERDOWNFLAG /etc/killpower` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation, part 2 of 5.\label{fig:upsmonconf12}}
\end{figure}

Line \ref{LP303}, identical to line \ref{LP203} declares the command to be
used to shut down the server.

Line \ref{LP304} says which program is to be invoked when
\upsmon\ detects a NOTIFY event flagged as \texttt{EXEC}.  The
directory/file \texttt{/usr{\allowbreak}/sbin/{\allowbreak}upssched}
is for Debian 11.  Sysadmins for other distributions should check the
directory used.

Line \ref{LP305}, \texttt{POLLFREQ}, declares that the \upsmon\ daemon will
poll \upsd\ every 5 seconds.

Line \ref{LP306}, \texttt{POLLFREQALERT}, declares that the \upsmon\ daemon
will poll \upsd\ every 5 seconds while the UPS in on battery.

Line \ref{LP307}, \texttt{HOSTSYNC} will be used in primary-secondary\footnote{A
  secondary is a second, third, ... PC or workstation sharing the same UPS,}
cooperation, to be discussed in chapter \ref{section:magic}.  The default
value is 15 seconds.

Line \ref{LP308} specifies how long \upsmon\ will allow a UPS to go missing
before declaring it ``dead''. The default is 15 seconds.

Daemon \upsmon\ requires a UPS to provide status information every few seconds
as defined by \texttt{POLLFREQ} and \texttt{POLLFREQALERT}. If the status
fetch fails, the UPS is marked stale. If it stays stale for more than
\texttt{DEADTIME} seconds, the UPS is marked dead.

A dead UPS that was last known to be on battery \status{\OB} is assumed to
have changed to a low battery condition \statuschange{\OB}{\OB\ \LB}. This may
force a shutdown. Disruptive, but the alternative is barreling ahead into
oblivion and crashing when you run out of power.
See chapter \ref{section:shutdown.dual} for more discussion.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP317]  & \verb`NOTIFYMSG ONLINE   "UPS %s: On line power."` \\
\Clunk[LP316]  & \verb`NOTIFYMSG ONBATT   "UPS %s: On battery."` \\
\Clunk[LP313]  & \verb`NOTIFYMSG LOWBATT  "UPS %s: Battery is low."` \\
\Clunk[LP318]  & \verb`NOTIFYMSG REPLBATT "UPS %s: Battery needs to be replaced."` \\
\Clunk[LP312]  & \verb`NOTIFYMSG FSD      "UPS %s: Forced shutdown in progress."` \\
\Clunk[LP319]  & \verb`NOTIFYMSG SHUTDOWN "Auto logout and shutdown proceeding."` \\
\Clunk[LP311]  & \verb`NOTIFYMSG COMMOK   "UPS %s: Communications (re-)established."` \\
\Clunk[LP310]  & \verb`NOTIFYMSG COMMBAD  "UPS %s: Communications lost."` \\
\Clunk[LP314]  & \verb`NOTIFYMSG NOCOMM	  "UPS %s: Not available."` \\
\Clunk[LP315]  & \verb`NOTIFYMSG NOPARENT "upsmon parent dead, shutdown impossible."` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation, part 3 of 5.\label{fig:upsmonconf13}}
\end{figure}

The message texts on lines \ref{LP317}-\ref{LP315} in figure
\ref{fig:upsmonconf13} do not change.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP327]  & \verb`NOTIFYFLAG ONLINE   SYSLOG+WALL+EXEC` \\
\Clunk[LP326]  & \verb`NOTIFYFLAG ONBATT   SYSLOG+WALL+EXEC` \\
\Clunk[LP323]  & \verb`NOTIFYFLAG LOWBATT  SYSLOG+WALL+EXEC` \\
\Clunk[LP328]  & \verb`NOTIFYFLAG REPLBATT SYSLOG+WALL` \\
\Clunk[LP322]  & \verb`NOTIFYFLAG FSD      SYSLOG+WALL` \\
\Clunk[LP329]  & \verb`NOTIFYFLAG SHUTDOWN SYSLOG+WALL` \\
\Clunk[LP321]  & \verb`NOTIFYFLAG COMMOK   SYSLOG+WALL` \\
\Clunk[LP320]  & \verb`NOTIFYFLAG COMMBAD  SYSLOG+WALL` \\
\Clunk[LP324]  & \verb`NOTIFYFLAG NOCOMM   SYSLOG+WALL` \\
\Clunk[LP325]  & \verb`NOTIFYFLAG NOPARENT SYSLOG+WALL` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation, part 4 of 5.\label{fig:upsmonconf14}}
\end{figure}

Lines \ref{LP327}-\ref{LP323} now carry the \texttt{EXEC} flag: this flag
means that when the NOTIFY event occurs, \upsmon\ calls the program identified
by the \texttt{NOTIFYCMD} on line \ref{LP304}.

Lines \ref{LP328}-\ref{LP325} do not change.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP330]  & \verb`RBWARNTIME 43200` \\
\Clunk[LP331]  & \verb`NOCOMMWARNTIME 300` \\
\Clunk[LP332]  & \verb`FINALDELAY 5` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation, part 5 of 5.\label{fig:upsmonconf15}}
\end{figure}

Lines \ref{LP330}-\ref{LP332} are the same as lines \ref{LP230}-\refpage{LP232}.


\newcolumn
\subsection{\Hsep\ Configuration file \upsschedconf\ for a workstation}\label{section:upsschedconf2}

The NOTIFY events detected by \upsmon\ and flagged as \texttt{EXEC} in
\upsmonconf\ become events for \upssched\ when \texttt{NOTIFYCMD} points to
\upssched.  The program \upssched\ provides a richer set of actions than \upsmon.

The configuration file \upsschedconf\ described here shows only a simple
subset of what can be done.  We will see more later.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP340]  & \verb`# upssched.conf` \\
\Clunk[LP342]  & \verb`CMDSCRIPT /usr/bin/upssched-cmd` \\
\Clunk         & \verb`# PIPEFN LOCKFN suitable for Debian 11` \\
\Clunk[LP343]  & \verb`PIPEFN /run/nut/upssched.pipe` \\
\Clunk[LP344]  & \verb`LOCKFN /run/nut/upssched.lock` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ for a Debian 11 workstation, Part 1.\label{fig:upsschedconf}}
\end{figure}

On line \ref{LP342} \texttt{CMDSCRIPT} points to a user script to be
called for designated NOTIFY events.  This script will receive as
argument a user chosen value.  The specification
\texttt{/usr/{\allowbreak}bin/{\allowbreak}upssched-{\allowbreak}cmd}
is for Debian 11.  Sysadmins of other distributions should check the
directory used.

Line \ref{LP343} defines \texttt{PIPEFN} which is the file name of a
socket used for communication between \upsmon\ and \upssched.  It is
important that the directory be accessible to NUT software and nothing
else.  I recommend that you use the same directory as is used for
communication between \upsd\ and the drivers.  Search for the
directory which contains the file \texttt{upsd.pid}.  You should see
at least one socket.  See for example the footnote to section
\ref{section:driver}.

The value shown on line \ref{LP343} is for the Debian 11 distribution
which places \texttt{upsd.pid} in directory
\texttt{/run/{\allowbreak}nut/} .  As always, sysadmins for other
distributions should check the directory used.  You should see an
additional entry in the directory:

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk  & \verb`srw-rw----  1 nut  nut    0 Aug  7 15:57 upssched.pipe=` \\
\end{LinePrinter}

On line \ref{LP344} the \texttt{LOCKFN} declaration is needed by
daemon \upsmon\ to avoid race conditions.  The directory should be the
same as \texttt{PIPEFN}.

%\newcolumn
\subsubsection{\Hsep\ The \texttt{AT} declaration.\label{section:AT}}

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP345]  & \verb`AT ONLINE  UPS-1@localhost EXECUTE online` \\
\Clunk[LP346]  & \verb`AT ONBATT  UPS-1@localhost EXECUTE onbatt` \\
\Clunk[LP347]  & \verb`AT LOWBATT UPS-1@localhost EXECUTE lowbatt` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ for a Debian 11 workstation, Part 2.\label{fig:AT}}
\end{figure}

Line \ref{LP345} introduces the very useful \texttt{AT} declaration provided
by \upsschedconf.  This has the form
\begin{center}
\texttt{AT} \textsl{notifytype} \textsl{UPS-name} \textsl{command}
\end{center}
\begin{flushleft}where\end{flushleft} 
\ul 

\li \textsl{notifytype} is a symbol representing a NOTIFY event.

\li \textsl{UPS-name} can be the special value ``\texttt{*}'' to apply this
handler to every possible value of \textsl{UPS-name}.  I strongly recommend
that you do not use this wildcard, since in later chapters we need distinct
actions for distinct UPS's.
 
\li The \textsl{command} in this case is \texttt{EXECUTE}.  In later chapters
we will see other very useful commands.

\eul

Line \ref{LP345} says what is to be done by \upssched\ for event
\NOTev{\ONLINE}.  The field ``\UPSi\texttt{@localhost}'' says that it applies
to the UPS we are using, and the \texttt{EXECUTE} says that the user script
specified by \texttt{CMDSCRIPT} is to be called with argument
``\texttt{online}''.

Lines \ref{LP346} and \ref{LP347} make similar declarations for NOTIFY
events \NOTev{\ONBATT}\ and \NOTev{\LOWBATT}.

\subsection{\Hsep\ Configuration script \upsschedcmd\ for a workstation}\label{section:upsschedcmd}

When \upssched\ was added to the NUT project, the user defined script was
called ``\upsschedcmd''.  This is not the most elegant of names but if you use
it, people in the NUT community will know immediately what you mean.  Ubuntu
sysadmins sometimes use \texttt{upssched{\allowbreak}-script} which is better.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP352]  & \verb`#!/bin/bash -u` \\
\Clunk[LP350]  & \verb`# upssched-cmd` \\
\Clunk[LP354]  & \verb`logger -i -t upssched-cmd Calling upssched-cmd $1` \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP355]  & \verb`UPS="UPS-1"` \\
\Clunk[LP356]  & \verb`STATUS=$( upsc $UPS ups.status )` \\
\Clunk[LP357]  & \verb`CHARGE=$( upsc $UPS battery.charge )` \\
\Clunk[LP358]  & \verb`CHMSG="[$STATUS]:$CHARGE%"` \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP359]  & \verb`case $1 in` \\
\Clunk[LP35A]  & \verb`   online) MSG="$UPS, $CHMSG - power supply has been restored." ;;` \\
\Clunk[LP35B]  & \verb`   onbatt) MSG="$UPS, $CHMSG - power failure - save your work!" ;;` \\
\Clunk[LP35C]  & \verb`   lowbatt) MSG="$UPS, $CHMSG - shutdown now!" ;;` \\
\Clunk[LP35D]  & \verb`   *) logger -i -t upssched-cmd "Bad arg: \"$1\", $CHMSG"` \\
\Clunk[LP35E]  & \verb`      exit 1 ;;` \\
\Clunk[LP35F]  & \verb`esac` \\
\Clunk[LP35G]  & \verb`logger -i -t upssched-cmd $MSG` \\
\Clunk[LP35H]  & \verb`notify-send-all "$MSG"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration script \upsschedcmd\ for a workstation.\label{fig:upsschedcmd2}}
\end{figure}

Figure \ref{fig:upsschedcmd2} shows a simple example of the script.
Since NUT runs on a wide range of operating systems and distributions, with
different default scripting languages, it is wise to declare as on line
\ref{LP352} which scripting language is used.

Logging all calls to this script helps sysadmins to discover what went wrong
after the catastrophic failures which in theory should never occur, but which
in practice do.  Line \ref{LP354} logs all calls to this script.

Lines \ref{LP356}-\ref{LP358} prepare a Bash variable \texttt{CHMSG} which
gives the current UPS status and battery charge.  This is to be included in
messages, so we get a clearer idea of what is happening.

On line \ref{LP359} the value of the Bash variable \texttt{\$1} is one of the
\texttt{EXECUTE} tags defined on lines \ref{LP345}-\ref{LP347}.

Lines \ref{LP35A}-\ref{LP35C} define, for each possible NOTIFY event that
\upsmon\ passes on to \upssched, a message to be logged and put in front of
users.  Accented letters and non latin characters are allowed.

Line \ref{LP35G} logs the \upssched\ action, and line \ref{LP35H} calls
program \notifysendall\ to put the message in front of the users.  For details
of \notifysendall, see appendix \ref{section:notifysend}, ``Using \notifysend''.
See also \texttt{notify-send -\/-help}.  There is no man page.

It is important that script \upsschedcmd\ be accessible to NUT
software and nothing else.  For example the following restrictive
ownership and permissions seen on a Debian 11 site:

\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk  & \verb`root@titan ~ ls -alF /usr/bin/upssched-cmd` \\
\Clunk  & \verb`-rwxr--r-- 1 nut daemon 8444 Aug  6 18:07 /usr/bin/upssched-cmd*` \\
\end{LinePrinter}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-4.jpg, height=36mm}
\end{center}

\vspace*{\fill}

% espeak -m "<speak>Attention <break> Attention <break> <prosody
% pitch=low rate=slow> this machine will shut down in <break>2<break>
% minutes"

\subsection{\Hsep\ The shutdown story for a workstation}\label{section:story:workstation}

\textsl{We are now ready to tell the detailed story of how the workstation gets
  shut down when wall power fails, and how it restarts when wall power
  returns.}

\ol 

\li \textbf{Wall power on} \quad The system runs normally. \upsd\ status is
\status{\OL}. No NOTIFY event.

\textsl{Days, weeks, months go by...}

\li \textbf{Wall power fails} \quad The server remains operational running on
the UPS battery.  \upsd\ polls the UPS, and detects status change
\statuschange{\OL}{\OB}.

\li \upsmon\ polls \upsd, receives status \status{\OB} and issues
NOTIFY event \NOTev{\ONBATT}.  As instructed by line \ref{LP326} an
\NOTev{\ONBATT}\ message goes to syslog, to program \texttt{wall} and
to \upssched.  The server is still operational, running on the UPS
battery.

\li \upssched\ ignores the message it receives and follows the instruction on
line \ref{LP346} to call the user script \upsschedcmd\ with parameter
\texttt{onbatt}.

\li User script \upsschedcmd\ sees that \texttt{\$1 = onbatt} and on line
\ref{LP35B} sets Bash variable \texttt{\$MSG} to
\verb`UPS-1, [OB DISCHRG]:99% - power failure - save your work!`

\li On line \ref{LP35G}, the message is logged, and on line \ref{LP35H} program 
\notifysendall\ notifies the users.

\textsl{Minutes go by...}

\li \textbf{Battery discharges below \texttt{battery.charge.low}} \quad The
server remains operational, but the UPS battery will not last much longer.
\upsd\ polls the UPS, and detects status change
\statuschange{\OB}{\OB\ \LB}.

\li \upsmon\ polls \upsd, receives status \status{\OB\ \LB} and issues
new NOTIFY event \NOTev{\LOWBATT}.  As instructed by line \ref{LP323}
\upsmon\ sends a \NOTev{\LOWBATT}\ message to syslog, to program
\texttt{wall} and to \upssched.

\textsl{The following \upssched\ actions may not occur if the system shutdown
  is rapid.}

\li \upssched\ ignores the message it receives and follows the instruction on
line \ref{LP347} to call the user script \upsschedcmd\ with parameter
\texttt{lowbatt}.

\li User script \upsschedcmd\ sees that \texttt{\$1 = lowbatt} and on line
\ref{LP35C} sets Bash variable \texttt{\$MSG} to
\verb`UPS-1, [OB DISCHRG LB]:12% - shutdown now!`

\li On line \ref{LP35G}, the message is logged, and on line \ref{LP35H} program 
\notifysend\ notifies the users.

\textsl{The shutdown story now continues as for the simple server in state
  \refpage{serverLB}.}

\eol

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Workstations share a UPS}\label{section:secondary}

\textsl{This chapter discusses a variant of the workstation configuration of
  chapter \ref{section:workstation}: multiple workstations on the same UPS
  unit.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=slave.pdf,width=0.95\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{``Secondary'' workstations take power from same UPS as ``primary''.\label{fig:slave}}
\end{figure}

In this configuration two or more workstations are powered by the same UPS
unit.  Only one, the ``primary'', has a control lead to the UPS.  The other(s)
do not have control leads to the UPS and are known as ``secondaries''.

Figure \ref{fig:slave} shows the arrangement.  The NUT configuration
for the primary workstation is identical to that of chapter
\ref{section:workstation}.

Five configuration files specify the operation of NUT in the secondary workstation.

\ol

\li The NUT startup configuration: \nutconf.  Since there is no control lead
to the UPS, there is no need for \upsd\ or a \driver\ in the secondary.  In
\nutconf\ declare \texttt{MODE=netclient} since only \upsmon\ needs to be
started.  You will probably need to review your distribution's start-up
scripts to achieve this.  If \upsd\ is started but without any UPS specified,
it usually does no harm.  See also appendix \refpage{section:Start}.

\li The \upsmon\ daemon configuration: \upsmonconf.  See chapter
\ref{section:upsmonconf.slave}.

\li The \upssched\ configuration: \upsschedconf.  See chapter
\ref{section:upsschedconf.slave}.

\li The \upsschedcmd\ script: see chapter \ref{section:upsschedcmd.slave}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol


\subsection{\Hsep\ Configuration file \upsmonconf\ for a secondary}\label{section:upsmonconf.slave}

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP360]  & \verb`# upsmon.conf  -- secondary --` \\
\Clunk[LP361]  & \verb`MONITOR UPS-1@primary 1 nut-admin sekret secondary` \\
\Clunk[LP362]  & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a secondary, part 1 of 5.\label{fig:upsmonconf1.slave}}
\end{figure}

This configuration file declares how \upsmon\ in the secondary is to
handle NOTIFY events coming from the primary.  For good security,
ensure that only users nut\footnote{I've seen user upsd rather than
nut in distributions.  See table \ref{fig:UD} in appendix
\ref{section:UD}} and root can read and write this file.

On line \ref{LP361}

\ul

\li The UPS name \UPSi\ must correspond to that declared in the primary
\upsconf, line \refpage{LP100}.  The fully qualified name
\textsl{\texttt{UPS@host}} includes the network name of the primary
workstation, in this case \texttt{primary}.

\li The ``power value'' \texttt{1} is the number of power supplies that this
UPS feeds on this system.

\li \texttt{nut-admin} is the ``user'' declared in primary \upsdusers\ line
\refpage{LP120}.

\li \texttt{sekret} is the password declared in primary \upsdusers\ line
\refpage{LP121}.

\li \texttt{secondary} means this system will shutdown first, before the primary.

\eul

On line \ref{LP362}, \texttt{MINSUPPLIES} sets the number of power
supplies that must be receiving power to keep this system
running. Normal computers have just one power supply, so the default
value of 1 is acceptable. See chapter \ref{section:dual}, and
\NUTman{upsmon.conf} in the NUT documentation for more details.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP363]  & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\Clunk[LP364]  & \verb`NOTIFYCMD /usr/sbin/upssched` \\
\Clunk[LP365]  & \verb`POLLFREQ 5` \\
\Clunk[LP366]  & \verb`POLLFREQALERT 5` \\
\Clunk[LP367]  & \verb`HOSTSYNC 15` \\
\Clunk[LP368]  & \verb`DEADTIME 15` \\
\Clunk[LP369]  & \verb`POWERDOWNFLAG /etc/killpower` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a secondary, part 2 of 5.\label{fig:upsmonconf2.slave}}
\end{figure}

Line \ref{LP363}, identical to line \refpage{LP203}, declares the command to be
used to shut down the secondary.

Line \ref{LP364} says which program is to be invoked when \upsmon\ detects a
NOTIFY event flagged as \texttt{EXEC}.  Debian administrators would probably
specify \texttt{/sbin/upssched}\ .

Line \ref{LP365}, \texttt{POLLFREQ}, declares that the \upsmon\ daemon will
poll \upsd\ in the primary every 5 seconds.

Line \ref{LP366}, \texttt{POLLFREQALERT}, declares that the \upsmon\ daemon
will poll \upsd\ in the primary every 5 seconds while the UPS in on battery.

Line \ref{LP367}, \texttt{HOSTSYNC}\footnote{The name
``\texttt{HOSTSYNC}'' is misleading.  It would be clearer if the name
were say ``\texttt{MAXWAITSCNDRY}''.}  will be used as a safeguard for
the primary-secondary shutdown sequence, preventing the overall
shutdown being blocked by an unresponsive secondary, as discussed in
chapter \ref{section:numattach}.  The default value is 15 seconds.

Line \ref{LP368} specifies how long the secondary \upsmon\ will allow a UPS to go
missing before declaring it ``dead''. The default is 15 seconds.

Daemon \upsmon\ requires a UPS to provide status information every few seconds
as defined by \texttt{POLLFREQ} and \texttt{POLLFREQALERT}. If the status
fetch fails, the UPS is marked stale. If it stays stale for more than
\texttt{DEADTIME} seconds, the UPS is marked dead.

A dead UPS that was last known to be on battery \status{\OB} is assumed to have
changed to a low battery condition \statuschange{\OB}{\OB\ \LB}. This may force a
shutdown. Disruptive, but the alternative is barreling ahead into oblivion and
crashing when you run out of power.
See chapter \ref{section:shutdown.dual} for more discussion.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP370]  & \verb`NOTIFYMSG ONLINE   "UPS %s: On line power."` \\
\Clunk[LP371]  & \verb`NOTIFYMSG ONBATT   "UPS %s: On battery."` \\
\Clunk[LP372]  & \verb`NOTIFYMSG LOWBATT  "UPS %s: Battery is low."` \\
\Clunk[LP373]  & \verb`NOTIFYMSG REPLBATT "UPS %s: Battery needs to be replaced."` \\
\Clunk[LP374]  & \verb`NOTIFYMSG FSD      "UPS %s: Forced shutdown in progress."` \\
\Clunk[LP375]  & \verb`NOTIFYMSG SHUTDOWN "Auto logout and shutdown proceeding."` \\
\Clunk[LP376]  & \verb`NOTIFYMSG COMMOK   "UPS %s: Communications (re-)established."` \\
\Clunk[LP377]  & \verb`NOTIFYMSG COMMBAD  "UPS %s: Communications lost."` \\
\Clunk[LP378]  & \verb`NOTIFYMSG NOCOMM	  "UPS %s: Not available."` \\
\Clunk[LP379]  & \verb`NOTIFYMSG NOPARENT "upsmon parent dead, shutdown impossible."` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a secondary, part 3 of 5.\label{fig:upsmonconf3.slave}}
\end{figure}

The message texts on lines \ref{LP370}-\ref{LP379} in figure
\ref{fig:upsmonconf3.slave} do not change from those in the primary.

\begin{figure}[ht]\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP380]  & \verb`NOTIFYFLAG ONLINE   SYSLOG+WALL+EXEC` \\
\Clunk[LP381]  & \verb`NOTIFYFLAG ONBATT   SYSLOG+WALL+EXEC` \\
\Clunk[LP382]  & \verb`NOTIFYFLAG LOWBATT  SYSLOG+WALL+EXEC` \\
\Clunk[LP383]  & \verb`NOTIFYFLAG REPLBATT SYSLOG+WALL` \\
\Clunk[LP384]  & \verb`NOTIFYFLAG FSD      SYSLOG+WALL` \\
\Clunk[LP385]  & \verb`NOTIFYFLAG SHUTDOWN SYSLOG+WALL` \\
\Clunk[LP386]  & \verb`NOTIFYFLAG COMMOK   SYSLOG+WALL` \\
\Clunk[LP387]  & \verb`NOTIFYFLAG COMMBAD  SYSLOG+WALL` \\
\Clunk[LP388]  & \verb`NOTIFYFLAG NOCOMM   SYSLOG+WALL` \\
\Clunk[LP389]  & \verb`NOTIFYFLAG NOPARENT SYSLOG+WALL` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a secondary, part 4 of 5.\label{fig:upsmonconf4.slave}}
\end{figure}

Lines \ref{LP380}-\ref{LP382}, which do not change from those in the primary,
carry the \texttt{EXEC} flag: when the NOTIFY event occurs, secondary
\upsmon\ calls the program identified by the \texttt{NOTIFYCMD} on line
\ref{LP364}.

Lines \ref{LP383}-\ref{LP389} do not change from those in the primary.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP390]  & \verb`RBWARNTIME 43200` \\
\Clunk[LP391]  & \verb`NOCOMMWARNTIME 300` \\
\Clunk[LP392]  & \verb`FINALDELAY 5` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a secondary, part 5 of 5.\label{fig:upsmonconf5.slave}}
\end{figure}

Lines \ref{LP390}-\ref{LP392} are the same as lines \ref{LP230}-\refpage{LP232} in
the primary.


\subsection{\Hsep\ Configuration file \upsschedconf\ for a secondary}\label{section:upsschedconf.slave}

The NOTIFY events detected by secondary \upsmon\ and flagged as \texttt{EXEC} in
\upsmonconf\ become events for \upssched\ when \texttt{NOTIFYCMD} points to
\upssched.  The program \upssched\ provides a richer set of actions than
\upsmon.

As with the primary in chapter \ref{section:workstation}, the configuration
file \upsschedconf\ described here shows only a simple subset of what can be
done.  We will see more later.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP3A0]  & \verb`# upssched.conf  -- secondary  --` \\
\Clunk[LP3A1]  & \verb`CMDSCRIPT /usr/sbin/upssched-cmd` \\
\Clunk[LP3A2]  & \verb`PIPEFN /run/nut/upssched.pipe` \\
\Clunk[LP3A3]  & \verb`LOCKFN /run/nut/upssched.lock` \\
\Clunk         & \\
\Clunk[LP3A4]  & \verb`AT ONLINE  UPS-1@primary EXECUTE online` \\
\Clunk[LP3A5]  & \verb`AT ONBATT  UPS-1@primary EXECUTE onbatt` \\
\Clunk[LP3A6]  & \verb`AT LOWBATT UPS-1@primary EXECUTE lowbatt` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ for a secondary.\label{fig:upsschedconf.slave}}
\end{figure}

On line \ref{LP3A1}, \texttt{CMDSCRIPT} points to a user script to be called
for designated NOTIFY events.  This script will receive as argument a user
chosen value.

Line \ref{LP3A2} defines \texttt{PIPEFN} which is the file name of a
socket used for communication between \upsmon\ and \upssched.  The
value shown is for the Debian 11 distribution.  For a detailed
discussion of \texttt{PIPEFN}, see chapter
\ref{section:upsschedconf2}, line \ref{LP343}.

Daemon \upsmon\ requires the \texttt{LOCKFN} declaration on line \ref{LP3A3}
to avoid race conditions.  The directory should be the same as
\texttt{PIPEFN}.

Line \ref{LP3A4} says what \upssched\ should do for NOTIFY event
\NOTev{\ONLINE}.  The ``\UPSi\texttt{@primary}'' says that it applies
to the UPS controlled by the primary, and the \texttt{EXECUTE} says
that the user script specified by \texttt{CMDSCRIPT} is to be called
with argument ``\texttt{online}''.

Lines \ref{LP3A5} and \ref{LP3A6} make similar declarations for NOTIFY
events \NOTev{\ONBATT}\ and \NOTev{\LOWBATT}.



\subsection{\Hsep\ Configuration script \upsschedcmd\ for a secondary}\label{section:upsschedcmd.slave}

When \upssched\ was added to the NUT project, the user defined script was
called ``\upsschedcmd''.  This is not the most elegant of names but if you use
it, people in the NUT community will know immediately what you mean.

It is important that script \upsschedcmd\ be accessible to NUT software and
nothing else.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP3B0]  & \verb`#!/bin/bash -u` \\
\Clunk[LP3B1]  & \verb`# upssched-cmd  --secondary --` \\
\Clunk[LP3B2]  & \verb`logger -i -t upssched-cmd Calling upssched-cmd $1` \\
\end{LinePrinter}
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP3B7]  & \verb`case $1 in` \\
\Clunk[LP3B8]  & \verb`   online) MSG="UPS-1 - power supply had been restored." ;;` \\
\Clunk[LP3B9]  & \verb`   onbatt) MSG="UPS-1 - power failure - save your work!" ;;` \\
\Clunk[LP3C0]  & \verb`   lowbatt) MSG="UPS-1 - shutdown now!" ;;` \\
\Clunk[LP3C1]  & \verb`   *) logger -i -t upssched-cmd "Bad arg: \"$1\""` \\
\Clunk[LP3C2]  & \verb`      exit 1 ;;` \\
\Clunk[LP3C3]  & \verb`esac` \\
\Clunk[LP3C4]  & \verb`logger -i -t upssched-cmd $MSG` \\
\Clunk[LP3C5]  & \verb`notify-send-all "$MSG"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration script \upsschedcmd\ for a secondary.\label{fig:upsschedcmd.slave}}
\end{figure}

Since NUT runs on a wide rage of operating systems and distributions, with
different default scripting languages, it is wise to declare as on line
\ref{LP3B0} which scripting language is used.

Logging all calls to this script helps sysadmins to discover what went wrong
after the catastrophic failures which in theory should never occur, but which
in practice sometimes do.  Line \ref{LP3B2} logs all calls to this script.

On line \ref{LP3B7} the value of the Bash variable \texttt{\$1} is one of the
\texttt{EXECUTE} tags defined on lines \ref{LP3A4}-\ref{LP3A6}.

Lines \ref{LP3B8}-\ref{LP3C0} define, for each possible NOTIFY event that
\upsmon\ passes on to \upssched, a message to be logged and put in front of
users of the secondary.  Accented letters and non latin characters are allowed.

Line \ref{LP3C4} logs the \upssched\ action, and line \ref{LP3C5} calls
program \notifysendall\ to put the message in front of the secondary users.  For
details of \notifysendall, see appendix \ref{section:notifysend}, ``Using
\notifysend''.  See also \texttt{notify-send -\/-help}.  There is no man page.

\newcolumn
\subsection{\Hsep\ \texttt{NUMATTACH}: Counting the protected systems}\label{section:numattach}

The daemon \upsd\ maintains a count of the number of systems protected
by a UPS unit.  When a primary or secondary is brought up, it sends
command \texttt{ATTACH} to \upsd\ which increases the count by 1.
When a system is shut down, it sends command \texttt{DETACH} to
\upsd\ and the count decreases by 1.  In the configuration shown in
figure \ref{fig:slave} on page \pageref{fig:slave}, during normal
operation the count is 4.  The primary \upsmon\ instance polls the
number of protected systems using command \texttt{NUMATTACH}.  During
a complete shutdown, the primary waits until the \texttt{NUMATTACH}
value drops to 1 before shutting down itself.

However there is a safeguard against excessive waiting for a
non-responsive secondary provided by the \texttt{HOSTSYNC} value
declared on line \ref{LP367}.

%\newcolumn
\subsection{\Hsep\ Magic: How does the primary shut down the secondaries?}\label{section:magic}

The primary commands the system shutdowns which may be due to an \status{\LB},
a timeout (chapter \ref{section:bad}), or a sysadmin command.  When there are
secondaries to be shutdown as well, then the primary expects them to shut down
first.  But how do the secondaries know that they are to shut down?

When the primary makes the shutdown decision, it places a status
symbol \status{\FSDst} in variable \texttt{ups.status} in the abstract
image of the UPS maintained by it's \upsd.  The secondary
\upsmon\ daemons poll \upsd\ every \texttt{POLLFREQ} seconds as
delared on line \ref{LP305}, and when they see the \status{\FSDst}
symbol, knowing that they are a secondary, they shut down immediately,
sending command \texttt{DETACH} to \upsd.  The primary waits for the
secondaries to react and shutdown by polling the \texttt{NUMATTACH}
value.  The maximum waiting period is specified by
\texttt{HOSTSYNC}\footnote{The name ``\texttt{HOSTSYNC}'' is
misleading.  It would be clearer if the name were say
``\texttt{MAXWAITSCNDRY}''.} on line \ref{LP307}.  When
\texttt{NUMATTACH} $=1$, or after the \texttt{HOSTSYNC} time has
elapsed, the primary will shut down, even if there is a secondary
which has not yet completed it's shutdown.  If you meet this problem,
you may have to increase the value of \texttt{HOSTSYNC}.

This \texttt{HOSTSYNC} value is also used to keep secondary systems
from getting stuck if the primary fails to respond in time. After a
UPS becomes critical, e.g. status \status{\OB\ \LB}, the secondary
will wait up to \texttt{HOSTSYNC} seconds for the primary to set the
\status{\FSDst} flag. If that timer expires, the secondary will assume
that the primary is broken and will shut down anyway.  See also
\NUTman{upsmon.conf}.

%\vspace*{\fill}
%\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Workstation with heartbeat}\label{heartbeat}

\textsl{The NUT software runs in the background for weeks, months without
  difficulty and with no messages going the system administrator.  ``All is
  well!'', but is it?  NUT is a collection of pieces and interconnecting
  protocols.  What if one of these pieces has stopped or the protocol blocked?
  We need something that will check regularly that all is indeed well.  The
  proposed heartbeat does this job.}

\textsl{This chapter supposes that you already have a working configuration
  for a workstation.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=heartbeat.pdf,width=1.0\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Workstation with heartbeat.\label{fig:heartbeat}}
\end{figure}

\textbf{How does it work?} \quad NUT program \upssched\ runs
permanently as a daemon managing an 11 minute timer.  If this timer
expires, NUT is broken, and \upssched\ calls user script
\upsschedcmd\ which issues wall messages, e-mails, notifications, etc.
Meanwhile a dummy (software) UPS is programmed to generate a status
change every 10 minutes.  This works it's way through the NUT daemons
and protocols to reach user script \upsschedcmd\ which then restarts
the 11 minute timer.  As long as the 10 minute status changes are
fully and correctly handled by NUT, the warning message does not go
out, but if something breaks, the 11 minute timer elapses.

Nine configuration files specify the operation of NUT in the workstation.

\ol

\li The NUT startup configuration: \nutconf.  See appendix
\refpage{section:Start}.

\li The \upsd\ UPS declarations: \upsconf\ will be extended to include
the heartbeat.  See chapter \ref{section:upsconf.heartbeat}.

\li New configuration file \heartbeatconf\ defines the dummy UPS which
provides the heartbeat.  See chapter \ref{section:heartbeat.conf}. 

\li The \upsd\ daemon access control: File \upsdconf\ as given
in chapter \ref{section:upsdconf} stays the same.

\li The \upsd\ user declarations: File \upsdusers\ as given in chapter
\ref{section:upsdusers} does not change.

\li The \upsmon\ daemon configuration: \upsmonconf.  See chapter
\ref{section:upsmonconf.heartbeat}.

\li The \upssched\ configuration: \upsschedconf.  See chapter
\ref{section:upsschedconf.heartbeat}.

\li The \upsschedcmd\ script: see chapter \ref{section:upsschedcmd.heartbeat}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \ref{section:Stop}.

\eol


%\newcolumn
\subsection{\Hsep\ Configuration file \upsconf\ for workstation with heartbeat}\label{section:upsconf.heartbeat}

We extend this configuration file with an additional section to declare a new
UPS unit.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.6\LinePrinterwidth]
\Clunk         & \verb`# ups.conf, heartbeat` \\
\Clunk[LP400]  & \verb`[UPS-1]` \\
\Clunk         & \verb`   driver = usbhid-ups` \\
\Clunk         & \verb`   port = auto` \\
\Clunk         & \verb`   desc = "Example Mfg Sparkly 1600"` \\
\Clunk         & \verb`   offdelay = 60` \\
\Clunk[LP401]  & \verb`   ondelay = 70` \\
\Clunk[LP40X]  & \verb`   lowbatt = 33` \\
\end{LinePrinter}
\begin{LinePrinter}[0.6\LinePrinterwidth]
\Clunk[LP402]  & \verb`[heartbeat]` \\
\Clunk[LP403]  & \verb`   driver = dummy-ups` \\
\Clunk[LP404]  & \verb`   port = heartbeat.conf` \\
\Clunk[LP404a] & \verb`   mode = dummy-loop` \\
\Clunk[LP405]  & \verb`   desc = "Watch over NUT"` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsconf\ for workstation with heartbeat.\label{fig:upsconf,heartbeat}}
\end{figure}

Lines \ref{LP400}-\ref{LP40X} are unchanged.

New line \ref{LP402} declares the new dummy UPS \texttt{heartbeat}.  This will
be a software creation which looks to NUT like a UPS, but which can be
programmed with a script, and given arbitrary states.

Line \ref{LP403} says that this UPS is of type \dummyups, i.e. a
software UPS, for which the scripted behaviour will be in a file
specified by the \texttt{port} declaration.

Line \ref{LP404} says that the scripted behaviour is in file
\heartbeatconf\ in the same directory as \upsconf.  Up to 2.7.4 it was
traditional in NUT development that such files had file type
\textcolor{UPSDCOLOUR}{\texttt{.dev}}.  NUT 2.8.0 has introduced
\textcolor{UPSDCOLOUR}{\texttt{.seq}}, but we are in a production
context, not development so we choose a more conventional name.

Starting with 2.8.0, \textcolor{UPSDCOLOUR}{\texttt{.dev}} no longer
implies the looping needed by a heartbeat, this is now called for by
\textcolor{UPSDCOLOUR}{\texttt{.seq}}.  The implicit looping behaviour
of other file names is no longer defined and must be configured
explicitly with a \texttt{mode} declaration as shown on line
\ref{LP404a}.

See \NUTman{dummy-ups} for lots of details.

\newcolumn
\subsection{\Hsep\ Configuration file \heartbeatconf\ for workstation}\label{section:heartbeat.conf}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.6\LinePrinterwidth]
\Clunk         & \verb`# heartbeat.conf -- 10 minute heartbeat`  \\
\Clunk[LP410]  & \verb`ups.status: OL`  \\
\Clunk[LP411]  & \verb`TIMER 300`  \\
\Clunk[LP412]  & \verb`ups.status: OB`  \\
\Clunk[LP413]  & \verb`TIMER 300`  \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \heartbeatconf\ for workstation.\label{fig:heartbeatconf}}
\end{figure}

Heartbeat definitions are not provided by NUT, you have to create them
yourself.  Create the new file \heartbeatconf\ in the same directory
as \upsconf.  For security, only users nut\footnote{Some distributions
have been known to use upsd. See table \ref{fig:UD} in appendix
\ref{section:UD} for other user names.} and root should have write
access to this file.

The dummy UPS will cycle continuously through this script. 

Lines \ref{LP410} and \ref{LP412} flip the \texttt{ups.status} value between
\status{\OL} and \status {\OB}.

Lines \ref{LP411} and \ref{LP413} place a 5 minute time interval between each
status change. Remember that $2\times 300 sec = 10 min$, the heartbeat period.

%\newcolumn
\subsection{\Hsep\ Configuration file \upsmonconf\ for workstation with heartbeat}\label{section:upsmonconf.heartbeat}

The configuration file \upsmonconf\ is the same as for the workstation in
chapter \ref{section:workstation}, except for an additional \texttt{MONITOR}
declaration and a simpler \texttt{NOTIFYFLAG} to avoid flooding the logs.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`# upsmon.conf` \\
\Clunk[LP421]  & \verb`MONITOR UPS-1@localhost     1 nut-admin sekret primary` \\
\Clunk[LP422]  & \verb`MONITOR heartbeat@localhost 0 nut-admin sekret primary` \\
\Clunk         & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for a workstation with heartbeat.\label{fig:upsmonconf21}}
\end{figure}

The change is the addition of line \ref{LP422} which declares that \upsmon\ is
to monitor the heartbeat.  Note that the power value is ``0'' because the
heartbeat does not supply power to the workstation.

To avoid flooding your logs, remove the flags \texttt{SYSLOG} and
\texttt{WALL} for the \NOTev{\ONLINE} and \NOTev{\ONBATT} NOTIFY events:
 
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk         & \verb`NOTIFYFLAG ONLINE   EXEC` \\
\Clunk         & \verb`NOTIFYFLAG ONBATT   EXEC` \\
\end{LinePrinter}

All the other declarations remain unchanged.  This inability of \upsmon\ to
provide different behaviours for different UPS's is a weakness, and is why we
prefer to make use of \upssched\ which supports precise selection of the UPS
in it's \texttt{AT} specification.

\newcolumn
\subsection{\Hsep\ Configuration file \upsschedconf\ for workstation with heartbeat}\label{section:upsschedconf.heartbeat}

We use \upssched\ as a daemon to maintain an 11 minute timer which we
call \heartfailtimer.  The timer is kept in memory, and manipulated
with the commands \texttt{START-TIMER} and \texttt{CANCEL-TIMER} which
are included in the \texttt{AT} facility which NUT provides as a part of
\upsschedconf.  See \NUTman{upssched.conf}.  If this timer completes,
\upssched\ calls the user script \upsschedcmd\ with the parameter
\heartfailtimer, and \upsschedcmd\ will complain that NUT is broken.

The configuration file \upsschedconf\ is the same as for the workstation in
chapter \ref{section:workstation}, except for two additional declarations.

\begin{figure}[ht]
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk         & \verb`# Restart timer which completes only if the dummy-ups heart beat` \\
\Clunk         & \verb`# has stopped.  See timer values in heartbeat.conf` \\
\Clunk[LP432]  & \verb`AT ONBATT heartbeat@localhost CANCEL-TIMER heartbeat-failure-timer` \\
\Clunk[LP431]  & \verb`AT ONBATT heartbeat@localhost START-TIMER  heartbeat-failure-timer 660` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ for a workstation with heartbeat.\label{fig:upsschedconf21}}
\end{figure}

Remember that the very useful \texttt{AT} declaration provided by
\upsschedconf\ has the form

\begin{center}
\texttt{AT} \textsl{notifytype} \textsl{UPS-name} \textsl{command}
\end{center}

On line \ref{LP432}, when \upssched\ receives an \NOTev{\ONBATT} it executes
the \textsl{command} which is \texttt{CANCEL{\allowbreak}-TIMER
  \heartfailtimer}.  This kills the timer.  \upssched\ does not call the user
script.

Immediately afterwards, on line \ref{LP431}, and for the same \NOTev{\ONBATT}
event, \upssched\ executes the \textsl{command}
\texttt{START{\allowbreak}-TIMER \heartfailtimer\ 660} which restarts the
\heartfailtimer\ which will run for 660 sec, i.e. 11 minutes.  If the timer
completes, \upssched\ will call the user script \upsschedcmd\ with parameter
\heartfailtimer.

Make sure that there are no entries such as

\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk          & \verb`AT ONLINE * ...` \\
\Clunk          & \verb`AT ONBATT * ...` \\
\end{LinePrinter}

\noindent which would be activated by an \NOTev{\ONLINE} or \NOTev{\ONBATT}
from the heartbeat UPS.  Replace the "\texttt{*}" with the full address of the
UPS unit, e.g. \verb`UPS-1@localhost`.

\subsection{\Hsep\ Script \upsschedcmd\ for workstation with heartbeat}\label{section:upsschedcmd.heartbeat}

In \upsschedcmd, we add additional code to test for completion of the
\heartfailtimer, and when it completes send a warning to the sysadmin by
e-mail, SMS, pigeon, ...

Here is an example of what can be done.  Note the e-mail address declarations
in the head of the script, and the additional case after ``\verb`case $1 in`''
beginning on line \ref{LP440}.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk         & \verb`#!/bin/bash -u` \\
\Clunk         & \verb`# upssched-cmd for workstation with heartbeat` \\
\Clunk         & \verb`logger -i -t upssched-cmd Calling upssched-cmd $1` \\
\Clunk         & \\
\Clunk         & \verb`# Send emails to/from these addresses` \\
\Clunk[LP438]  & \verb`EMAIL_TO="sysadmin@example.com"` \\
\Clunk[LP439]  & \verb`EMAIL_FROM="upssched-cmd@${HOSTNAME:-nut}.example.com"` \\
\Clunk         & \\
\Clunk[LP436]  & \verb`UPS="UPS-1"` \\
\Clunk         & \verb`STATUS=$( upsc $UPS ups.status )` \\
\Clunk         & \verb`CHARGE=$( upsc $UPS battery.charge )` \\
\Clunk[LP437]  & \verb`CHMSG="[$STATUS]:$CHARGE%"` \\
\Clunk         & \\
\Clunk         & \verb`case $1 in` \\
\Clunk         & \verb`(online)  MSG="$UPS, $CHMSG - power supply had been restored." ;;` \\
\Clunk         & \verb`(onbatt)  MSG="$UPS, $CHMSG - power failure - save your work!" ;;` \\
\Clunk         & \verb`(lowbatt) MSG="$UPS, $CHMSG - shutdown now!" ;;` \\
\Clunk[LP440]  & \verb`(heartbeat-failure-timer)` \\
\Clunk[LP441]  & \verb`   MSG="NUT heart beat fails. $CHMSG" ;;` \\
\Clunk[LP442]  & \verb`   # Email to sysadmin` \\
\Clunk[LP443]  & \verb`   MSG1="Hello, upssched-cmd reports NUT heartbeat has failed."` \\
\Clunk[LP444]  & \verb`   MSG2="Current status: $CHMSG \n\n$0 $1"` \\
\Clunk[LP445]  & \verb`   MSG3="\n\n$( ps -elf | grep -E 'ups[dms]|nut' )"` \\
\Clunk[LP446]  & \verb`   echo -e "$MSG1 $MSG2 $MSG3" | /bin/mail -r "$EMAIL_FROM" \` \\
\Clunk[LP447]  & \verb`        -s "NUT heart beat fails. Currently $CHMSG" "$EMAIL_TO"` \\
\Clunk         & \verb`(*) logger -i -t upssched-cmd "Bad arg: \"$1\", $CHMSG"` \\
\Clunk         & \verb`      exit 1 ;;` \\
\Clunk         & \verb`esac` \\
\Clunk         & \verb`logger -i -t upssched-cmd $MSG` \\
\Clunk         & \verb`notify-send-all "$MSG"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration script \upsschedcmd\ including heartbeat.\label{fig:upsschedcmd.heartbeat}}
\end{figure}

On lines \ref{LP438} and \ref{LP439}, change the e-mail addresses to something
that works for you.

Lines \ref{LP440}-\ref{LP447} introduce the \heartfailtimer\ case into the
case statement.  Line \ref{LP441} specifies a message to be logged with the
current UPS status as defined on lines \ref{LP436}-\ref{LP437}.

Lines \ref{LP443}-\ref{LP445} compose a message to the sysadmin which is sent
on line \ref{LP446}.  The message includes the current state of those NUT
kernel processes which are operational.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\textsl{A true sysadmin should not be satisfied with just the heartbeat.  ``What if
the heartbeat dies silently?''  We need a further independent check that the
normally silent heartbeat is doing it's job.}

\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ For parano\"id sysadmins}\label{section:upsschedcmd.paranoid}

We want to check that the heartbeat is in progress.  To do so we make use of
the permanent presence of a \upssched\ process.  Consider the following Bash
script:

\begin{figure}[ht]
\begin{LinePrinter}[0.90\LinePrinterwidth]
\Clunk         & \verb`#!/bin/bash -u` \\
\Clunk[A201]   & \verb`NUT=nut       # openSUSE: "upsd", Debian: "nut"` \\
\Clunk         & \verb`MSGERR="${HOSTNAME:-mybox}: NUT heartbeat fails"` \\
\Clunk         & \verb`MSGOK="${HOSTNAME:-mybox}: NUT heartbeat OK"` \\
\Clunk         & \verb`# Are the heartbeat timers keeping upssched busy?` \\
\Clunk[A202]   & \verb`ps -elf | grep "upssched UPS heartbeat" | grep $NUT > /dev/null` \\
\Clunk         & \verb`if [[ $? -ne 0 ]]` \\
\Clunk[A203]   & \verb`then wall $MSGERR         # Tell sysadmin the bad news` \\
\Clunk[A204]   & \verb`     echo -e "$MSGERR" | /bin/mail\` \\
\Clunk         & \verb`                         -r heartbeat-watcher@example.com\` \\
\Clunk         & \verb`                         -s "$MSGERR" sysadmin@example.com` \\
\Clunk[A205]   & \verb`     notify-send-all "$MSGERR"` \\
\Clunk         & \verb`     sleep 1s` \\
\Clunk         & \verb`else # Tell sysadmin that all is well` \\
\Clunk         & \verb`     echo -e "$MSGOK" | /bin/mail\` \\
\Clunk         & \verb`                        -r heartbeat-watcher@example.com\` \\
\Clunk         & \verb`                        -s "$MSGOK" sysadmin@example.com` \\
\Clunk[A206]   & \verb`     notify-send-all "$MSGOK"` \\
\Clunk         & \verb`fi` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Heartbeat watcher.\label{fig:heartbeat.watcher}}
\end{figure}

Line \ref{A201} specifies who is the owner of the \upssched\ process.  See
table \ref{fig:UD} for a list of possible owners.

Line \ref{A202} will succeed if there is a process managing the heartbeat.

Lines \ref{A203}, \ref{A204} and \ref{A205} show three different ways
of telling the sysadmin that all is not well with the heartbeat
process.  Pick which one(s) suit you.  See appendix
\ref{section:notifysend} for a discussion of \notifysendall.

The Bash script requires something like line \ref{A200} in \texttt{/etc/crontab}:

\begin{LinePrinter}[0.99\LinePrinterwidth]
\Clunk[A200]  & \verb`1 8 * * *  nut  /usr/local/bin/heartbeat-watcher.sh > /dev/null 2>&1` \\
\end{LinePrinter}

In this example, line \ref{A200} declares that the Bash script is to
be run at 08:01 hrs every day as user ``nut''.  OpenSUSE might use
``upsd''.  See table \ref{fig:UD} for a list of possible users.  See
also \LINman{crontab}{5}.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\textsl{This chapter has introduced the timers provided by \upssched.
We will see in the next chapter that much more can be done with them.}

\vspace*{\fill}

%\begin{center}
%   \epsfig{file=UPS-1.jpg, height=36mm}
%\end{center}

%\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \clearpage   
\newcolumn
\section{\Hsep\ Workstation with timed shutdown}\label{section:bad}

\textsl{All the configurations we have looked at so far have one thing
  in common.  The system shutdown is provoked by UPS status}
\status{\LB}.  \textsl{This means that when the system finally shuts
  down, the battery is depleted.  It will still be depleted when wall
  power returns and the system restarts.  This is not a problem if the
  power supply is inherently reliable, and the power supply will
  continue long enough to recharge the batteries, but this is not
  always the case.  The maintenance people do not always fix the
  problem completely on their first visit. In neighbourhoods where
  lightning strikes frequently, where local industrial activity plays
  havoc with the voltage, and in neighbourhoods with training schools
  for backhoe operators, we expect the wall power to fail again, and
  again.}

\textsl{In this chapter the criteria for a system shutdown will not be
  based on the status} \status{\LB}, \textsl{but on the status}
\status{\OB} \textsl{and an elapsed time.}

\textsl{It is sometimes said in NUT circles ``get the most out of your UPS by
  hanging on as long as possible''.  In this chapter we say ``get the most out
  of your UPS by being able to shut down cleanly as often as possible''.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=bad.pdf,width=1.0\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Workstation with timed shutdown.\label{fig:bad}}
\end{figure}

Nine configuration files specify the operation of NUT in a workstation with
timed shutdown.  In this chapter we will give these configuration files in
full to avoid excessive page turning.

\ol

\li The NUT startup configuration: \nutconf.  Since this file is not strictly
a part of NUT, and is common to all configurations, it is discussed separately
in appendix \refpage{section:Start}.

\li The \upsd\ UPS declarations \upsconf: See chapter \ref{section:upsconf.bad}.

\li Configuration file \heartbeatconf\ which defines the dummy UPS providing
the heartbeat.  See chapter \ref{section:heartbeatconf.bad}.

\li The \upsd\ daemon access control \upsdconf: See chapter
\ref{section:upsdconf.bad}.

\li The \upsd\ user declarations \upsdusers: See chapter
\ref{section:upsdusers.bad}.

\li The \upsmon\ daemon configuration: \upsmonconf.  See chapter
\ref{section:upsmonconf.bad}.

\li The \upssched\ configuration: \upsschedconf.  See chapter
\ref{section:upsschedconf.bad}.

\li The \upsschedcmd\ script: see chapter \ref{section:upsschedcmd.bad}.

\li The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol

%\newcolumn
\subsection{\Hsep\ Configuration file \upsconf\ for workstation with timed shutdown}\label{section:upsconf.bad}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.6\LinePrinterwidth]
\Clunk         & \verb`# ups.conf, timed shutdown` \\
\Clunk[LP502]  & \verb`[UPS-1]` \\
\Clunk[LP503]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP504]  & \verb`   port = auto` \\
\Clunk[LP505]  & \verb`   desc = "Bigspark ECO 1600"` \\
\Clunk[LP506]  & \verb`   offdelay = 60` \\
\Clunk[LP507]  & \verb`   ondelay = 70` \\
\Clunk[LP50X]  & \verb`   lowbatt = 33` \\
\Clunk[LP508]  & \verb`[heartbeat]` \\
\Clunk[LP509]  & \verb`   driver = dummy-ups` \\
\Clunk[LP50A]  & \verb`   port = heartbeat.conf` \\
\Clunk[LP50C]  & \verb`   mode = dummy-loop` \\
\Clunk[LP50B]  & \verb`   desc = "Watch over NUT"` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsconf\ for workstation with timed shutdown.\label{fig:upsconf.bad}}
\end{figure}

This configuration file includes support for the heartbeat, and is unchanged
from that discussed in the previous chapter.  See \refpage{section:upsconf.heartbeat}

Lines \ref{LP502} and \ref{LP508} begin a UPS-specific section, and name the
UPS unit that \upsd\ will manage.  The following lines provides details for
each UPS.  There will as many sections as there are UPS units.  Make sure this
name matches the name in \upsmonconf\ and in \upsschedcmd, which we will meet
later.

Lines \ref{LP503} and \ref{LP509} specify the driver that \upsd\ will use.  For the full list
of drivers, see the Hardware Compatibility list and the required drivers at
\href{http://www.networkupstools.org/stable-hcl.html}%
{http://{\allowbreak}www.networkupstools.org/{\allowbreak}stable-hcl.html}.

Lines \ref{LP504} and \ref{LP50A} depend on the driver. For the
\usbhidups\ driver the value is always \texttt{auto}.  For the
\dummyups\ driver, the value is the address of the file which specifies the
dummy UPS behaviour.  This file should be in the same directory as \upsconf.
For other drivers, see the man page for that driver.

Line \ref{LP50C} is needed by NUT 2.8.0 to specify that the program of
work described by the file \heartbeatconf\ is to be repeated
endlessly. See \NUTman{dummy-ups}.

Lines \ref{LP505} and \ref{LP50B} provide descriptive texts for the UPS.

For a detailed discussion of \texttt{offdelay} and \texttt{ondelay} on lines
\ref{LP506}-\ref{LP507}, see chapter \refpage{section:upsconf.improved}.

Additional line \ref{LP50X} sets the default value for \batterychargelow.
Even if you use command \upsrw\ to set a value for \batterychargelow,
\usbhidups\ and some other drivers\footnote{List needed} will restore the
default, so if you want a permanent change you must change the default.  See
also chapter \ref{section:upsrw}.



\newcolumn
\subsection{\Hsep\ Configuration file \heartbeatconf\ for workstation with timed shutdown}\label{section:heartbeatconf.bad}

Create the new file \heartbeatconf\ in the same directory as \upsconf.

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-6mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# heartbeat.conf` \\
\Clunk         & \verb`# 10 minute heartbeat` \\
\Clunk[LP50J]  & \verb`ups.status: OL`  \\
\Clunk[LP50K]  & \verb`TIMER 300`  \\
\Clunk[LP50L]  & \verb`ups.status: OB`  \\
\Clunk[LP50M]  & \verb`TIMER 300`  \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{This is the configuration file \heartbeatconf\ for a work{\allowbreak}station with timed shutdown.\label{fig:heartbeatconf.bad}}
\end{wrapfigure}

This configuration file provides the definition of the heartbeat, and is
unchanged from that discussed in chapter \refpage{section:heartbeat.conf}.

The heartbeat definitions are not provided by NUT, you have to create them
yourself.  Create the new file \heartbeatconf\ in the same directory
as \upsconf.  For security, only users nut\footnote{This is for Debian
11.  See table \ref{fig:UD} in appendix \ref{section:UD} for other
user names.} and root should have write access to this file.

Because it is in mode \texttt{dummy-loop}, the dummy UPS will cycle
continuously through this script.
%Remember that there
%are no comments in NUT \textcolor{UPSDCOLOUR}{\texttt{.dev}} files.

Lines \ref{LP50J} and \ref{LP50L} flip the \texttt{ups.status} value
between \status{\OL} and \status {\OB}. Lines \ref{LP50K} and
\ref{LP50M} place a 5 minute time interval between each status
change. Remember that $2\times 300 sec = 10 min$, the heartbeat
period.


\subsection{\Hsep\ Configuration file \upsdconf\ with timed shutdown}\label{section:upsdconf.bad}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-6mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.conf` \\
\Clunk[LP510]  & \verb`LISTEN 127.0.0.1 3493` \\
\Clunk[LP511]  & \verb`LISTEN ::1 3493` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \upsdconf\ for workstation with timed shutdown.\label{fig:upsdconf.bad}}
\end{wrapfigure}

This configuration file declares on which ports the \upsd\ daemon will listen,
and provides a basic access control mechanism.  It does not change from the
version shown on lines \ref{LP110}-\refpage{LP111}.

Line \ref{LP510} declares that \upsd\ is to listen on it's prefered port for
traffic from the localhost.  It is possible to replace 127.0.0.1 by
0.0.0.0 which says ``listen for traffic from all sources'' and use your
firewall to filter traffic to port \IANAnut.

If you do not have IPv6, remove or comment out line \ref{LP511}.


\newcolumn
\subsection{\Hsep\ Configuration file \upsdusers\ with timed shutdown}\label{section:upsdusers.bad}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-6mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.users` \\
\Clunk[LP520]  & \verb`[nut-admin]` \\
\Clunk[LP521]  & \verb`   password = sekret`\\
\Clunk[LP522]  & \verb`   upsmon primary`\\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{This is the configuration file \upsdusers\ for a simple server.\label{fig:upsdusers.bad}}
\end{wrapfigure}

This configuration file declares who has write access to the UPS.  It
does not change from the version shown in lines
\ref{LP120}-\refpage{LP122}.  For good security, ensure that only
users nut\footnote{This is for Debian 11.  See table \ref{fig:UD} in
appendix \ref{section:UD} for other user names.} and root can read and
write this file.

Line \ref{LP520} declares the ``user name'' of the system administrator who
has write access to the UPS's managed by \upsd.  It is independent of
\texttt{/etc/passwd}.  The \upsmon\ client daemon will use this name to poll
and command the UPS's.  There may be several names with different levels of
access.  For this example we only need one.

Line \ref{LP521} provides the password.  You may prefer something
better than ``sekret''.  \textbf{Warning:} Avoid placing spaces
\texttt{U+0020} and quotation marks \texttt{"} \texttt{U+0022} in
passwords.

Line \ref{LP522} declares that this user is the \upsmon\ daemon, and the
required set of actions will be set automatically.  In this simple
configuration daemon \upsmon\ is a \texttt{primary}.

The configuration file for \upsmon\ must match these declaration for
\upsmon\ to operate correctly.

For lots of details, see \NUTman{upsd.users}.


\subsection{\Hsep\ Configuration file \upsmonconf\ with timed shutdown}\label{section:upsmonconf.bad}

\textsl{The previous chapters have repeatedly modified \upsmonconf\ so we
  provide here a complete description of the file, including all previous
  modifications.}

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP600]  & \verb`# upsmon.conf` \\
\Clunk[LP601]  & \verb`MONITOR UPS-1@localhost     1 nut-admin sekret primary` \\
\Clunk[LP602]  & \verb`MONITOR heartbeat@localhost 0 nut-admin sekret primary` \\
\Clunk[LP603]  & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ with timed shutdown, part 1 of 5.\label{fig:upsmonconf51}}
\end{figure}

This configuration file declares how \upsmon\ is to handle NOTIFY
events.  For good security, ensure that only users nut\footnote{This
is for Debian 11.  See table \ref{fig:UD} in appendix \ref{section:UD}
for other user names.} and root can read and write this file.

On line \ref{LP601}

\ul

\li The UPS name \UPSi\ must correspond to that declared in \upsconf\ line
\ref{LP502}.

\li The ``power value'' \texttt{1} is the number of power supplies that this
UPS feeds on this system.

\li \texttt{nut-admin} is the ``user'' declared in \upsdusers\ line \ref{LP520}.

\li \texttt{sekret} is the password declared in \upsdusers\ line \ref{LP521}.

\li \texttt{primary} means this system will shutdown last, allowing any secondaries
time to shutdown first.  There are no secondaries in this simple configuration.

\eul

Line \ref{LP602} declares that \upsmon\ is also to monitor the heartbeat.

On line \ref{LP603}, \texttt{MINSUPPLIES} sets the number of power supplies
that must be receiving power to keep this system running. Normal computers
have just one power supply, so the default value of 1 is acceptable. See
\NUTman{upsmon.conf} and file
\href{http://www.susaaland.dk/sharedoc/nut-2.0.3/docs/big-servers.txt}{\texttt{big-servers.txt}}
in the NUT documentation for more details.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP610]  & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\Clunk[LP611]  & \verb`NOTIFYCMD /usr/sbin/upssched` \\
\Clunk[LP612]  & \verb`POLLFREQ 5` \\
\Clunk[LP613]  & \verb`POLLFREQALERT 5` \\
%\Clunk[LP614]  & \verb`HOSTSYNC 15` \\
\Clunk[LP615]  & \verb`DEADTIME 15` \\
\Clunk[LP616]  & \verb`POWERDOWNFLAG /etc/killpower` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ with timed shutdown, part 2 of 5.\label{fig:upsmonconf52}}
\end{figure}

Line \ref{LP610} declares the command to be used to shut down the
server.  A second instance of the \upsmon\ daemon running as root will
execute this command.  Multiple commands are possible, for example
\texttt{SHUTDOWNCMD "logger -t upsmon.conf \bsl"SHUTDOWNCMD calling
  /sbin/shutdown to shut down system\bsl" ; /sbin/shutdown -h +0"}
will also log the action of \texttt{SHUTDOWNCMD}.  Note that internal
" have to be escaped. Note also that this command will be used in any
call to \texttt{upsmon -c fsd}.  See line \ref{LP698}.

Line \ref{LP611} says which program is to be invoked when
\upsmon\ detects a NOTIFY event flagged as \texttt{EXEC}.  The example
shown is for Debian 11, sysadmins for other distributions should check
the directory used.

Line \ref{LP612}, \texttt{POLLFREQ}, declares that the \upsmon\ daemon will
poll \upsd\ every 5 seconds.

Line \ref{LP613}, \texttt{POLLFREQALERT}, declares that the \upsmon\ daemon
will poll \upsd\ every 5 seconds while the UPS in on battery.

Line \ref{LP615}, \texttt{DEADTIME} specifies how long \upsmon\ will allow a
UPS to go missing before declaring it ``dead''. The default is 15 seconds.

Daemon \upsmon\ requires a UPS to provide status information every few seconds
as defined by \texttt{POLLFREQ} and \texttt{POLLFREQALERT}. If the status
fetch fails, the UPS is marked stale. If it stays stale for more than
\texttt{DEADTIME} seconds, the UPS is marked dead.

A dead UPS that was last known to be on battery \status{\OB} is assumed to have
changed to a low battery condition \statuschange{\OB}{\OB\ \LB}. This may force a
shutdown. Disruptive, but the alternative is barreling ahead into oblivion and
crashing when you run out of power.
See chapter \ref{section:shutdown.dual} for more discussion.

Line \ref{LP616}, \texttt{POWERDOWNFLAG} declares a file created by
\upsmon\ when running in primary mode when the UPS needs to be powered off.  It
will be used in more complex configurations.  See \NUTman{upsmon.conf} for
details.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP620]  & \verb`NOTIFYMSG ONLINE   "UPS %s: On line power."` \\
\Clunk[LP621]  & \verb`NOTIFYMSG ONBATT   "UPS %s: On battery."` \\
\Clunk[LP622]  & \verb`NOTIFYMSG LOWBATT  "UPS %s: Battery is low."` \\
\Clunk[LP623]  & \verb`NOTIFYMSG REPLBATT "UPS %s: Battery needs to be replaced."` \\
\Clunk[LP624]  & \verb`NOTIFYMSG FSD      "UPS %s: Forced shutdown in progress."` \\
\Clunk[LP625]  & \verb`NOTIFYMSG SHUTDOWN "Auto logout and shutdown proceeding."` \\
\Clunk[LP627]  & \verb`NOTIFYMSG COMMOK   "UPS %s: Communications (re-)established."` \\
\Clunk[LP626]  & \verb`NOTIFYMSG COMMBAD  "UPS %s: Communications lost."` \\
\Clunk[LP628]  & \verb`NOTIFYMSG NOCOMM	  "UPS %s: Not available."` \\
\Clunk[LP629]  & \verb`NOTIFYMSG NOPARENT "upsmon parent dead, shutdown impossible."` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ with timed shutdown, part 3 of 5.\label{fig:upsmonconf53}}
\end{figure}

Lines \ref{LP620}-\ref{LP629} assign a text message to each NOTIFY event.
Within each message, the marker \texttt{\%s} is replaced by the name of the
UPS which has produced this event.  \upsmon\ passes this message to program
\texttt{wall} to notify the system administrator of the event.  You can change
the default messages to something else if you like.  The format is
\texttt{NOTIFYMSG event "\textsl{message}"} where \texttt{\%s} is replaced
with the identifier of the UPS in question.  Note that program \texttt{wall}
has not been internationalized and does not support accented letters or non
latin characters.  When the corresponding \texttt{NOTIFYFLAG} contains the
symbol \texttt{EXEC}, \upsmon\ also passes the message to the program
specified by \texttt{NOTIFYCMD} on line \ref{LP611}.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP630]  & \verb`NOTIFYFLAG ONLINE   EXEC` \\
\Clunk[LP631]  & \verb`NOTIFYFLAG ONBATT   EXEC` \\
\Clunk[LP632]  & \verb`NOTIFYFLAG LOWBATT  SYSLOG+WALL` \\
\Clunk[LP633]  & \verb`NOTIFYFLAG REPLBATT SYSLOG+WALL` \\
\Clunk[LP634]  & \verb`NOTIFYFLAG FSD      SYSLOG+WALL` \\
\Clunk[LP635]  & \verb`NOTIFYFLAG SHUTDOWN SYSLOG+WALL` \\
\Clunk[LP637]  & \verb`NOTIFYFLAG COMMOK   SYSLOG+WALL` \\
\Clunk[LP636]  & \verb`NOTIFYFLAG COMMBAD  SYSLOG+WALL` \\
\Clunk[LP638]  & \verb`NOTIFYFLAG NOCOMM   SYSLOG+WALL` \\
\Clunk[LP639]  & \verb`NOTIFYFLAG NOPARENT SYSLOG+WALL` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ with timed shutdown, part 4 of 5.\label{fig:upsmonconf54}}
\end{figure}

Lines \ref{LP630}-\ref{LP639} declare what is to be done at each NOTIFY event.
The declarations, known as ``flags'' are shown in table \refpage{fig:flags}. You
may specify one, two or three flags for each event, in the form
\texttt{FLAG[+FLAG]*}, however \texttt{IGNORE} must always be alone.

Lines \ref{LP630}-\ref{LP631} carry only the \texttt{EXEC} flag: Since the
heartbeat induces a lot of \NOTev{\ONLINE} and \NOTev{\ONBATT} traffic, the
\texttt{SYSLOG} option would flood the log and \texttt{WALL} would put far
too many useless messages in xterm windows.  When the NOTIFY event occurs,
\texttt{EXEC} declares that \upsmon\ should call the program identified by the
\texttt{NOTIFYCMD} on line \ref{LP611}.

Note that if you have multiple UPS's, the same actions are to be performed for
a given NOTIFY event for all the UPS's.  \textsl{Clearly this is not good
  news.}

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP640]  & \verb`RBWARNTIME 43200` \\
\Clunk[LP641]  & \verb`NOCOMMWARNTIME 300` \\
\Clunk[LP642]  & \verb`FINALDELAY 5` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ with timed shutdown, part 5 of 5.\label{fig:upsmonconf55}}
\end{figure}

When a UPS says that it needs to have its battery replaced, upsmon will
generate a \NOTev{\REPLBATT}\ NOTIFY event.  Line \ref{LP640} say that this happens
every \texttt{RBWARNTIME} = 43200 seconds (12 hours).

Line \ref{LP641}: Daemon \upsmon\ will trigger a \NOTev{\NOCOMM}\ NOTIFY event after
\texttt{NOCOMMWARNTIME} seconds if it can't reach any of the UPS entries in
configuration file \upsmonconf.  It keeps warning you until the situation is
fixed.

Line \ref{LP642}: When running in primary mode, \upsmon\ waits this
long after sending the \NOTev{\SHUTDOWN}\ NOTIFY event to warn the
users. After the timer elapses, it then runs your \texttt{SHUTDOWNCMD}
as specified on line \ref{LP610}.  If you need to let your users do
something in between those events, increase this number. Don't make
this too big, even though the battery still has charge.
Alternatively, you can set this very low so you don't wait around when
it's time to shut down.

For lots and lots of details, see \NUTman{upsmon.conf}.  See also the file
\href{https://github.com/networkupstools/nut/blob/master/docs/config-notes.txt}
     {\texttt{config{\allowbreak}-notes.txt}} in the distribution.


\subsection{\Hsep\ Configuration file \upsschedconf\ with timed shutdown}\label{section:upsschedconf.bad}

The NOTIFY events detected by \upsmon\ and flagged as \texttt{EXEC} in
\upsmonconf\ become events for \upssched\ when \texttt{NOTIFYCMD} points to
\upssched.  The program \upssched\ provides a richer set of actions than
\upsmon, especially the management of timers.

\begin{figure}[ht]
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[LP660]  & \verb`# upssched.conf    PIPEFN, LOCKFN for Debian 11` \\
\Clunk[LP661]  & \verb`CMDSCRIPT /usr/bin/upssched-cmd` \\
\Clunk[LP662]  & \verb`PIPEFN /run/nut/upssched.pipe` \\
\Clunk[LP663]  & \verb`LOCKFN /run/nut/upssched.lock` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ with timed shutdown, part 1.\label{fig:upsschedconf.bad}}
\end{figure}

On line \ref{LP661} \texttt{CMDSCRIPT} points to a user script to be
called for designated NOTIFY events.  The value shown is for Debian
11.  Ubuntu sysadmins might see
\texttt{/usr/{\allowbreak}local/{\allowbreak}bin/{\allowbreak}upssched-{\allowbreak}script}.
This script will receive as argument a user chosen timer name.

Line \ref{LP662} defines \texttt{PIPEFN} which is the file name of a
socket used for communication between \upsmon\ and \upssched.  It is
important that the directory be accessible to NUT software and nothing
else.  I recommend that you use the same directory as is used for
communication between \upsd\ and the drivers.  Search for the
directory which contains the file \texttt{upsd.pid}.  You should see
at least one socket.  See for example the footnote to section
\ref{section:driver}.

The value shown on line \ref{LP662} is for the Debian 11 distribution
which places \texttt{upsd.pid} in directory
\texttt{/run/{\allowbreak}nut/} .  As always, sysadmins for other
distributions should check the directory used.  You should see an
additional entry in the directory:

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk  & \verb`srw-rw----  1 nut  nut    0 Aug  7 15:57 upssched.pipe=` \\
\end{LinePrinter}

Daemon \upsmon\ requires the \texttt{LOCKFN} declaration on line \ref{LP663}
to avoid race conditions.  The directory should be the same as
\texttt{PIPEFN}.

\subsubsection{\Hsep\ The \texttt{AT} declaration\label{section:AT2}}

\begin{figure}[ht]
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[LP664]  & \verb`AT ONBATT UPS-1@localhost START-TIMER two-minute-warning-timer 5` \\
\Clunk[LP665]  & \verb`AT ONBATT UPS-1@localhost START-TIMER one-minute-warning-timer 65` \\
\Clunk[LP666]  & \verb`AT ONBATT UPS-1@localhost START-TIMER shutdown-timer 125` \\
\Clunk         & \\
\Clunk[LP667]  & \verb`AT ONLINE UPS-1@localhost CANCEL-TIMER two-minute-warning-timer` \\
\Clunk[LP668]  & \verb`AT ONLINE UPS-1@localhost CANCEL-TIMER one-minute-warning-timer` \\
\Clunk[LP669]  & \verb`AT ONLINE UPS-1@localhost CANCEL-TIMER shutdown-timer` \\
\Clunk[LP66A]  & \verb`AT ONLINE UPS-1@localhost EXECUTE ups-back-on-line` \\
\Clunk         & \\
\Clunk[LP66B]  & \verb`AT ONBATT heartbeat@localhost CANCEL-TIMER heartbeat-failure-timer` \\
\Clunk[LP66C]  & \verb`AT ONBATT heartbeat@localhost START-TIMER  heartbeat-failure-timer 660` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ with timed shutdown, part 2.\label{fig:AT2}}
\end{figure}

Line \ref{LP664} introduces the very useful \texttt{AT} declaration provided
by \upsschedconf.  This has the form

\begin{center}
\texttt{AT} \textsl{notifytype} \textsl{UPS-name} \textsl{command}
\end{center}
where 

\ul 

\li \textsl{notifytype} is a symbol representing a NOTIFY event.

\li \textsl{UPS-name} can be the special value ``\texttt{*}'' to apply this
handler to every possible value of \textsl{UPS-name}.  We strongly recommend
that you do not use this wildcard, since we need distinct actions for distinct
UPS's.
 
\li The \textsl{command} values are \texttt{START-TIMER},
\texttt{CANCEL-TIMER} and \texttt{EXECUTE}.

\eul

Line \ref{LP664} says what is to be done by \upssched\ for event
\NOTev{\ONBATT}.  The field ``\verb`UPS-1@localhost`'' says that it applies to
the UPS we are using, and the \texttt{START{\allowbreak}-TIMER} says that
\upssched\ is to create and manage a timer called ``\twominwarntim'' which
runs for 5 seconds.  When this timer completes, \upssched\ calls the user
script specified by \texttt{CMDSCRIPT} with argument ``\twominwarntim''.

Lines \ref{LP665} and \ref{LP666} do the same thing for the 65 second timer
\oneminwarntim\ and the 125 second timer \shutdowntimer.

Line \ref{LP667} says what is to be done by \upssched\ for event
\NOTev{\ONLINE}.  The field ``\verb`UPS-1@localhost`'' says that it applies to
the UPS we are using, and the \texttt{CANCEL{\allowbreak}-TIMER} says that
\upssched\ must cancel the timer ``\twominwarntim''.  The user script is not
called.

Lines \ref{LP668} and \ref{LP669} do the same thing for the 65 second timer
``\oneminwarntim'' and the 125 second timer ``\shutdowntimer''.

Line \ref{LP66A} command \texttt{EXECUTE} says that \upssched\ is to call the
user script immediately with the argument ``\upsbackonline''.

On line \ref{LP66B}, when \upssched\ receives an \NOTev{\ONBATT} it executes
the \textsl{command} which is \texttt{CANCEL{\allowbreak}-TIMER
  \heartfailtimer}.  This kills the timer.  \upssched\ does not call the user
script.

Immediately afterwards, on line \ref{LP66C}, and for the same \NOTev{\ONBATT}
event, \upssched\ executes the \textsl{command}
\texttt{START{\allowbreak}-TIMER \heartfailtimer} 660 which restarts the
\heartfailtimer\ which will run for 660 sec, i.e. 11 minutes.  If the timer
completes, \upssched\ will call the user script \upsschedcmd\ with parameter
\heartfailtimer.

%\newcolumn
\subsection{\Hsep\ Script \upsschedcmd\ for workstation with timed shutdown}\label{section:upsschedcmd.bad}

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk         & \verb`#!/bin/bash -u` \\
\Clunk         & \verb`# upssched-cmd  Workstation with heartbeat and timed shutdown` \\
\Clunk         & \verb`logger -i -t upssched-cmd Calling upssched-cmd $1` \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk         & \verb`# Send emails to/from these addresses` \\
\Clunk[LP680]  & \verb`EMAIL_TO="sysadmin@example.com"` \\
\Clunk[LP681]  & \verb`EMAIL_FROM="upssched-cmd@${HOSTNAME:-nut}.example.com"` \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP682]  & \verb`UPS="UPS-1"` \\
\Clunk         & \verb`STATUS=$( upsc $UPS ups.status )` \\
\Clunk         & \verb`CHARGE=$( upsc $UPS battery.charge )` \\
\Clunk[LP683]  & \verb`CHMSG="[$STATUS]:$CHARGE%"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration script \upsschedcmd\ for timed shutdown, 1 of 2.\label{fig:upsschedcmd.bad1}}
\end{figure}

The user script \upsschedcmd, the example is in Bash, manages the completion
of the timers \twominwarntim, \oneminwarntim, \shutdowntimer,
\upsbackonline\ and \heartfailtimer.  Here is an complete example of what can
be done.  You will probably need to modify this for your own use.  Note that
this script could be written in the language of your choice, as long as the
resulting program is able to receive the timer names as a parameter, send
e-mails and log and notify the users of messages.  Bash has the advantage of
being widely available and is understood by many sysadmins.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP684]  & \verb`case $1 in` \\
\Clunk[LP685]  & \verb`(heartbeat-failure-timer)` \\
\Clunk[LP686]  & \verb`   MSG="NUT heart beat fails. $CHMSG" ;;` \\
\Clunk[LP687]  & \verb`   MSG1="Hello, upssched-cmd reports NUT heartbeat has failed."` \\
\Clunk[LP688]  & \verb`   MSG2="Current status: $CHMSG \n\n$0 $1"` \\
\Clunk[LP689]  & \verb`   MSG3="\n\n$( ps -elf | grep -E 'ups[dms]|nut' )"` \\
\Clunk[LP690]  & \verb`   echo -e "$MSG1 $MSG2 $MSG3" | /bin/mail -r "$EMAIL_FROM" \` \\
\Clunk[LP691]  & \verb`        -s "NUT heart beat fails. Currently $CHMSG" "$EMAIL_TO" ;;` \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP692]  & \verb`(two-minute-warning-timer)`  \\
\Clunk[LP693]  & \verb`   MSG="Possible shutdown in 2 minutes. Save your work! $CHMSG" ;;`  \\
\Clunk[LP694]  & \verb`(one-minute-warning-timer)`  \\
\Clunk[LP695]  & \verb`   MSG="Probable shutdown in 1 minute. Save your work! $CHMSG" ;;`  \\
\Clunk[LP696]  & \verb`(shutdown-timer)`  \\
\Clunk[LP697]  & \verb`   MSG="Power  failure shutdown: Calling upsmon -c fsd, $CHMSG"`  \\
\Clunk[LP698]  & \verb`   /usr/sbin/upsmon -c fsd ;;`  \\
\Clunk[LP699]  & \verb`(ups-back-on-line)`  \\
\Clunk[LP69A]  & \verb`   MSG="Power back, shutdown cancelled. $CHMSG"  ;;`  \\
\Clunk[LP69B]  & \verb`(*) logger -i -t upssched-cmd "Bad arg: \"$1\", $CHMSG"` \\
\Clunk[LP69C]  & \verb`      exit 1 ;;` \\
\Clunk[LP69D]  & \verb`esac`  \\
\Clunk[LP69E]  & \verb`logger -i -t upssched-cmd $MSG` \\
\Clunk[LP69F]  & \verb`notify-send-all "$MSG"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration script \upsschedcmd\ for timed shutdown, 2 of 2.\label{fig:upsschedcmd.bad2}}
\end{figure}

On lines \ref{LP680} and \ref{LP681}, change the e-mail addresses to something
that works for you.

Lines \ref{LP682}-\ref{LP683} prepare a Bash variable \texttt{CHMSG} which
gives the current UPS status and battery charge.  This is to be included in
messages, so we get a clearer idea of what is happening.

Lines \ref{LP685}-\ref{LP691} introduce the \heartfailtimer\
case into the case statement.  Line \ref{LP686} specifies a message to be
logged with the current UPS status as defined on lines
\ref{LP682}-\ref{LP683}.  

Lines \ref{LP687}-\ref{LP689} compose a message to the sysadmin which is sent
on line \ref{LP690}.  The message includes the current state of those NUT
kernel processes which are operational.

\subsubsection{\Hsep\ The timed shutdown}\label{section:timedshutdown}

The cases at lines \ref{LP692} and \ref{LP694} specify warnings to be notified
to the users when the \twominwarntim\ and \oneminwarntim\ complete.

Beginning at line \ref{LP696} we prepare a message which the user may not see,
since we call for an immediate shutdown.  The UPS may well be almost fully
charged, but the shutdown is now, leaving enough charge for further shutdowns
in the near future.  

Note on line \ref{LP698} that we use \upsmon\ to shut down the system.
This automatically takes into account any secondary systems which need to
be shut down as well. The command \texttt{upsmon -c fsd} will call the
command specified by the \texttt{SHUTDOWNCMD} declaration on line
\ref{LP610}.

Line \ref{LP699} prepares a message that \notifysendall\ will put in front of
the users to tell them to get back to work since wall power has returned.  See
appendix \ref{section:notifysend} for a discussion of \notifysendall.

\newcolumn
\subsection{\Hsep\ The timed shutdown story}\label{section:story:timed}

\textsl{We now tell the detailed story of how the workstation gets
  shut down when wall power fails, and how it restarts when wall power
  returns.}

\ol 

\li\label{workOL} \textbf{Wall power on} \quad The system runs
normally. \upsd\ status is \status{\OL}. No NOTIFY event.

\textsl{Days, weeks, months go by...}

\li \textbf{Wall power fails} \quad The workstation remains operational
running on the UPS battery.  \upsd\ polls the UPS, and detects status change
\statuschange{\OL}{\OB}.

\li \upsmon\ polls \upsd, receives status \status{\OB} and issues
NOTIFY event \NOTev{\ONBATT}.  As instructed by line \refpage{LP631}
\upsmon\ calls \upssched, specified by \texttt{NOTIFYCMD} on line
\ref{LP611}.  Note that there is no \texttt{wall} message and no
logging by \upsmon.

\li \upssched\ matches the NOTIFY event \NOTev{ONBATT} and the UPS name
\verb`UPS-1@localhost` with the three \texttt{AT} specifications on lines
\ref{LP664}-\ref{LP666}.  Three timers start: \twominwarntim,
\oneminwarntim\ and \shutdowntimer, managed in memory by \upssched.

\textsl{5 seconds go by...}

\li \twominwarntim\ completes, and \upssched\ calls the user script
\upsschedcmd\ specified by \texttt{CMDSCRIPT} on line \ref{LP661} with the
timer name as argument.  In the script, this matches the case on line
\ref{LP692} which defines a suitable warning message in Bash variable
\texttt{MSG}.  Line \ref{LP69E} logs this message and line \ref{LP69F} puts it
in front of the users.  The workstation continues to operate on battery power.

\textsl{60 seconds go by...}

\li \oneminwarntim\ completes, and \upssched\ calls the user script
\upsschedcmd\ with the timer name as argument.  In the script, this matches the
case on line \ref{LP694} which defines a stronger warning message in Bash
variable \texttt{MSG}.  Line \ref{LP69E} logs this message and line
\ref{LP69F} puts it in front of the users.  The workstation continues to
operate on battery power.

\textsl{60 seconds go by...}

\li \shutdowntimer\ completes, and \upssched\ calls the user script
\upsschedcmd\ with the timer name as argument.  In the script, this matches
the case on line \ref{LP696} which defines an ultimate warning message in Bash
variable \texttt{MSG}, and then calls \upsmon\ for a system shutdown.  Line
\ref{LP69E} logs message \texttt{MSG} and line \ref{LP69F} puts it in front of
the users.  The workstation continues to operate on battery power during the
shutdown.  If wall power returns, it is now too late to call off the shutdown
procedure.

\li\label{workshutdown} \upsmon\ commands a system shutdown and generates
NOTIFY event \NOTev{\SHUTDOWN}.

\li \upsmon\ waits \texttt{FINALDELAY} seconds as specified on line \ref{LP642}.

\li \upsmon\ creates \texttt{POWERDOWN} flag specified on line \refpage{LP616}.

\li \upsmon\ calls the \texttt{SHUTDOWNCMD} specified on line \refpage{LP610}.

\li We now enter the scenario described in figure
\refpage{fig:delayedUPSshutdown}.  The operating system's shutdown process takes
over.  During the system shutdown, the Bash script shown in figure
\ref{fig:delayedUPSshutdown-Debian} or equivalent systemd service unit or some
other equivalent runs the command \texttt{upsdrvctl shutdown} .  This tells
the UPS that it is to shut down \texttt{offdelay} seconds later as specified
on line \ref{LP506}.

\li The system powers down, hopefully before the \texttt{offdelay} seconds
have passed.

\li \textbf{UPS shuts down} \quad \texttt{offdelay} seconds have passed.  With
some UPS units, there is an audible ``clunk''.  The UPS outlets are no longer
powered.

\textsl{Minutes, hours, days go by...}

\li \textbf{Wall power returns} \quad Some time later, maybe much later, wall
power returns.  The UPS reconnects it's outlets to send power to the protected
system.

\li The system BIOS option ``restore power on AC return'' has hopefully been
selected and the system powers up.  The bootstrap process of the operating
system begins.

\li\label{workUP} The operating system starts the NUT daemons \upsd\ and
\upsmon.  Daemon \upsd\ scans the UPS and the status becomes \status{\OL}.  We
are now back in the same situation as state \ref{workOL} above.

\li We hope that the battery has retained sufficient charge to
complete further timed shutdown cycles, but if it hasn't, then at the
next power failure, \upsd\ will detect the status \status{\OB\ \LB},
\upsmon\ will receive status \status{\OB\ \LB} and issue a
\NOTev{\LOWBATT} and will begin the system shutdown process used by
the simple server of chapter \ref{section:server}.  This system
shutdown will override any \upssched\ timed process.

\eol

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage 
\newcolumn
\section{\Hsep\ Workstation with additional equipment}\label{section:big}

\textsl{The time has come to look at a more ambitious configuration, with
  multiple UPS's and multiple computer systems.  NUT has been designed as an
  assembly of components each performing a distinct part of the operation.  We
  now see that this design allows NUT to adapt and perform well in complex
  configurations.}

\begin{figure}[ht]
\vspace{-9mm}
\begin{center}
   \epsfig{file=big.pdf,width=1.05\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Workstation with additional equipment.\label{fig:big}}
\end{figure}

The configuration is for an industrial application in which some
undisclosed industrial equipment is protected by a UPS
(\texttt{UPS-3}), and is also driven by a computer system having it's
own UPS (\texttt{UPS-2}).  This equipment with the driving computer is
at a remote site, code name \gold.  Overall management is from a
computer at a different, administrative site.  We will call the
management system \mgmt.

Computer \mgmt\ is represented here as if it were a single machine, but it
could well be duplicated at different sites for reliability.  Two (or more)
\mgmt\ systems may monitor a single \gold\ production machine.

Fourteen configuration files specify the operation of NUT in the production and
management machines.  

\ol

\li \gold: The NUT startup configuration: \nutconf.  This file is not strictly
a part of NUT, and is common to all configurations.  See chapter
\ref{section:nutconf.big} and appendix \refpage{section:Start}.

\li \gold: The \upsd\ UPS declarations \upsconf: See chapter
\ref{section:upsconf.big}.

\li \gold: The \upsd\ daemon access control \upsdconf: See chapter
\ref{section:upsdconf.big}.

\li \gold: The \upsd\ user declarations \upsdusers: See chapter
\ref{section:upsdusers.big}.

\li \gold: The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.
The shutdown script for the undisclosed device is beyond the scope of this
text.

\li \mgmt: The NUT startup configuration: \nutconf.  This file is not strictly
a part of NUT, and is common to all configurations.  See chapter
\ref{section:nutconf.big} also appendix \refpage{section:Start}.

\li \mgmt: The \upsd\ UPS declarations \upsconf: See chapter
\ref{section:upsconf.big}.

\li \mgmt: The \upsd\ heartbeat declaration \heartbeatconf: See chapter
\ref{section:upsconf.big}.

\li \mgmt: The \upsd\ daemon access control \upsdconf: See chapter
\ref{section:upsdconf.big}.

\li \mgmt: The \upsd\ user declarations \upsdusers: See chapter
\ref{section:upsdusers.big}.

\li \mgmt: The \upsmon\ daemon configuration \upsmonconf: See chapter
\ref{section:upsmonconf.big}.

\li \mgmt: The \upssched\ configuration \upsschedconf: See chapter
\ref{section:upsschedconf.big}.

\li \mgmt: The \upsschedcmd\ script: See chapter
\ref{section:upsschedcmd.big}.

\li \mgmt: The delayed UPS shutdown script.  Since this file is common to all
configurations, it is discussed separately in appendix \refpage{section:Stop}.

\eol

\subsection{\Hsep\ Configuration files \nutconf}\label{section:nutconf.big}

The first configuration files say which parts of the NUT are to be started.

\begin{tabular}{cp{5mm}c}
\textbf{\gold} & & \textbf{\mgmt} \\
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk[LP700]  & \verb`# nut.conf  -- gold --` \\
\Clunk[LP701]  & \verb`MODE=netserver` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \nutconf\ for \gold.\label{fig:nutconf.gold}}
\vspace{3mm}
\end{minipage}
& &
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# nut.conf  -- mgmt --` \\
\Clunk[LP702]  & \verb`MODE=standalone` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{Files \nutconf\ for \mgmt.\label{fig:nutconf.mgmt}}
\vspace{3mm}
\end{minipage} \\
\end{tabular}

Strictly speaking, this file is not for NUT, but for the process which starts
NUT.  The initialization process is expected to source this file to know which
parts of nut are to be started.  Some distributions, e.g.\ openSUSE, ignore
this file and start the three NUT layers \driver, \upsd\ and \upsmon.  They
assume that \texttt{MODE=standalone}.

This is probably satisfactory for \mgmt, but for \gold\ you should review line
\ref{LP701} and the init/systemd startup of the NUT software to ensure that
only the \upsd\ and \driver\ daemons get started.  See appendix
\ref{section:Start}.  See also \NUTman{nut.conf}.

%\newcolumn
\subsection{\Hsep\ Configuration files \upsconf\ and \heartbeatconf}\label{section:upsconf.big}

These configuration files declare which UPS's are to be managed by the
instances of NUT.

\begin{tabular}{cp{5mm}c}
\textbf{\gold} & & \textbf{\mgmt} \\
\begin{minipage}{0.55\LinePrinterwidth}
\begin{LinePrinter}[0.45\LinePrinterwidth]
\Clunk         & \verb`# ups.conf  -- gold --` \\
\Clunk[LP716]  & \verb`[UPS-3]` \\
\Clunk[LP717]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP718]  & \verb`   port = auto` \\
\Clunk[LP719]  & \verb`   desc = "Huge 3 phase"` \\
\Clunk[LP71A]  & \verb`   offdelay = 20` \\
\Clunk[LP71B]  & \verb`   ondelay = 30` \\
\Clunk[LP71X]  & \verb`   lowbatt = 33` \\
\Clunk[LP71S]  & \verb`   serial = 00328` \\
\Clunk         & \\
\Clunk[LP710]  & \verb`[UPS-2]` \\
\Clunk[LP711]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP712]  & \verb`   port = auto` \\
\Clunk[LP713]  & \verb`   desc = "Small monophase"` \\
\Clunk[LP714]  & \verb`   offdelay = 20` \\
\Clunk[LP715]  & \verb`   ondelay = 30` \\
\Clunk[LP71Y]  & \verb`   lowbatt = 33` \\
\Clunk[LP71T]  & \verb`   serial = XT766` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsconf\ for \gold.\label{fig:upsconf.gold}}
\vspace{3mm}
\end{minipage}
& &
\begin{minipage}{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# ups.conf  -- mgmt --` \\
\Clunk[LP720]  & \verb`[UPS-1]` \\
\Clunk[LP721]  & \verb`   driver = usbhid-ups` \\
\Clunk[LP722]  & \verb`   port = auto` \\
\Clunk[LP723]  & \verb`   desc = "BigSpark ECO 1600"` \\
\Clunk[LP724]  & \verb`   offdelay = 60` \\
\Clunk[LP725]  & \verb`   ondelay = 70` \\
\Clunk[LP72Z]  & \verb`   lowbatt = 33` \\
\Clunk         & \\
\Clunk[LP726]  & \verb`[heartbeat]` \\
\Clunk[LP727]  & \verb`   driver = dummy-ups` \\
\Clunk[LP728]  & \verb`   port = heartbeat.conf` \\
\Clunk[LP728a] & \verb`   mode = dummy-loop` \\
\Clunk[LP729]  & \verb`   desc = "Watch over NUT"` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsconf\ for \mgmt.\label{fig:upsconf.mgmt}}
\vspace{3mm}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# heartbeat.conf -- 10 min`  \\
\Clunk[LP730]  & \verb`ups.status: OL`  \\
\Clunk[LP731]  & \verb`TIMER 300`  \\
\Clunk[LP732]  & \verb`ups.status: OB`  \\
\Clunk[LP733]  & \verb`TIMER 300`  \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{\textbf{\heartbeatconf} for \mgmt.\label{fig:heartbeatconf.mgmt}}
\vspace{3mm}
\end{minipage} \\
\end{tabular}

\gold: On lines \ref{LP716}-\ref{LP710} we offer specimen definitions for
\UPSiii\ and \UPSii.  You will need to review these to take into account the
UPS's you are using.  Lines \ref{LP711} and \ref{LP717} specify the drivers
that \upsd\ will use.  For the full list of drivers, see the Hardware
Compatibility list and the required drivers at
\href{http://www.networkupstools.org/stable-hcl.html}%
{http://{\allowbreak}www.networkupstools.org/{\allowbreak}stable-hcl.html}.

The \texttt{offdelay} and \texttt{ondelay} on lines \ref{LP71A}-\ref{LP71B}
and \ref{LP714}-\ref{LP715} are given their default values.  You may need
something different.  See the discussion in chapter
\refpage{section:delayedUPSshutdown} of the delayed UPS shutdown.

In order to distinguish the two USB attached UPS units on \gold, we specify
their serial numbers on lines \ref{LP71S} and \ref{LP71T}.  See
\NUTman{usbhid-ups}.

\mgmt: On lines \ref{LP720}-\ref{LP725} we offer a specimen definition for
\UPSi\ and on lines \ref{LP730}-\ref{LP733} we propose the dummy UPS
``heartbeat'' discussed in chapter \refpage{heartbeat}.  The heartbeat requires
the definition file \heartbeatconf, lines \ref{LP730}-\ref{LP733}, to be placed
in the same directory as \upsconf.


\subsection{\Hsep\ Configuration files \upsdconf}\label{section:upsdconf.big}

\begin{tabular}{cp{5mm}c}
\textbf{\gold} & & \textbf{\mgmt} \\
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.conf  -- gold --` \\
\Clunk[LP740]  & \verb`LISTEN 10.8.0.5 3493` \\
\Clunk[LP741]  & \verb`LISTEN X::Y::Z 3493` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsdconf\ for \gold.\label{fig:upsdconf.gold}}
\vspace{3mm}
\end{minipage}
& &
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.conf  -- mgmt --` \\
\Clunk[LP742]  & \verb`LISTEN 127.0.0.1 3493` \\
\Clunk[LP743]  & \verb`LISTEN ::1 3493` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsdconf\ for \mgmt.\label{fig:upsdconf.mgmt}}
\vspace{3mm}
\end{minipage} \\
\end{tabular}

This configuration file declares on which ports the \upsd\ daemon will listen,
and provides a basic access control mechanism.  You will need a secure means
of accessing \gold\ from \mgmt.  This could be for example through an SSH
tunnel or over a VPN.  The limited access defined by the \texttt{LISTEN}
directive is part of a defense in depth.

\gold: Line \ref{LP740} declares that \upsd\ is to listen on a prefered port
for traffic from \mgmt.  The example is for the \texttt{tun0} interface of an
OpenVPN secure network.  See
\href{https://openvpn.net/}{https://{\allowbreak}openvpn.net/} .  It is
possible to specify 0.0.0.0 which says ``listen for traffic from all sources''
and use your firewall to filter traffic to port \IANAnut.  You must modify lines
\ref{LP740} and \ref{LP741} for your own needs.

\mgmt: Line \ref{LP742} declares that \upsd\ is to listen on it's prefered
port for traffic from the localhost.  It is possible to replace 127.0.0.1 by
0.0.0.0 which says ``listen for traffic from all sources'' and use your
firewall to filter traffic to port \IANAnut.

If you do not have IPv6, remove or comment out lines \ref{LP741} and
\ref{LP743}.

See \NUTman{upsd.conf} for more detail, and a description of the OpenSSL
support.


\subsection{\Hsep\ Configuration files \upsdusers}\label{section:upsdusers.big}

\begin{tabular}{cp{5mm}c}
\textbf{\gold} & & \textbf{\mgmt} \\
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.users  -- gold --` \\
\Clunk[LP750]  & \verb`[nut-admin]` \\
\Clunk[LP751]  & \verb`   password = sekret`\\
\Clunk[LP752]  & \verb`   upsmon primary` \\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsdusers\ for \gold.}
\vspace{3mm}
\end{minipage}
& &
\begin{minipage}[t]{0.5\LinePrinterwidth}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk         & \verb`# upsd.users  -- mgmt --` \\
\Clunk[LP753]  & \verb`[nut-admin]` \\
\Clunk[LP754]  & \verb`   password = sekret`\\
\Clunk[LP755]  & \verb`   upsmon primary`\\
\end{LinePrinter}
\vspace{-6mm}
\captionof{figure}{File \upsdusers\ for \mgmt.}
\vspace{3mm}
\end{minipage} \\
\end{tabular}

This configuration file declares who has write access to the UPS.  The
``user name'' used in these files is independent of
\texttt{/etc/passwd}.  For good security, ensure that only users
nut\footnote{This is for Debian 11.  See table \ref{fig:UD} in
appendix \ref{section:UD} for other user names.} and root can read and
write this file.  The configuration files for \upsmon\ must match
these declarations for \upsmon\ to operate correctly.

For lots of details, see \NUTman{upsd.users}.

\gold: Line \ref{LP750} declares the ``user name'' of the system administrator
who has write access to \UPSii\ and \UPSiii\ managed by \upsd.  The
\upsmon\ client daemon in \mgmt\ will use this name to poll and command the
UPS's.

Line \ref{LP751} provides the password.  You may prefer something
better than ``sekret''.  \textbf{Warning:} Avoid placing spaces
\texttt{U+0020} and quotation marks \texttt{"} \texttt{U+0022} in
passwords.

Line \ref{LP752} declares the type of relationship between the \upsd\ daemon
on \gold\ and the \upsmon\ in \mgmt\ which has the authority to shutdown
\gold.  The declaration ``\texttt{upsmon secondary}'' would allow monitoring but
not shutdown.  See \NUTman{upsd.users}.  See also \NUTman{upsmon} section UPS
DEFINITIONS, but our configuration is not exactly what that man page refers
to.

\mgmt: Line \ref{LP753} declares the ``user name'' of the system administrator
who has write access to \UPSi\ and to the heartbeat managed by \upsd.  

Line \ref{LP754} provides another uberl33t password.

Line \ref{LP755} declares the type of relationship between the \upsd\ daemon
and \upsmon\ which has the authority to shutdown \mgmt.


%\newcolumn
\subsection{\Hsep\ Configuration file \upsmonconf}\label{section:upsmonconf.big}

\textsl{The previous chapters have repeatedly modified \upsmonconf\ so we
  provide here a complete description of the file.}

\begin{figure}[ht]
\begin{LinePrinter}[0.75\LinePrinterwidth]
\Clunk[LP760]  & \verb`# upsmon.conf  -- mgmt --` \\
\Clunk[LP761]  & \verb`MONITOR UPS-3@gold          0 nut-admin sekret primary` \\
\Clunk[LP762]  & \verb`MONITOR UPS-2@gold          0 nut-admin sekret primary` \\
\Clunk[LP763]  & \verb`MONITOR UPS-1@localhost     1 nut-admin sekret primary` \\
\Clunk[LP764]  & \verb`MONITOR heartbeat@localhost 0 nut-admin sekret primary` \\
\Clunk[LP765]  & \verb`MINSUPPLIES 1` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for \mgmt, part 1 of 5.\label{fig:upsmonconf1.big}}
\end{figure}

This configuration file declares how \upsmon\ in \mgmt\ is to handle
NOTIFY events from \gold\ and from \mgmt\ itself.  For good security,
ensure that only users nut\footnote{This is for Debian 11.  See table
\ref{fig:UD} in appendix \ref{section:UD} for other user names.} and
root can read and write this file.

Line \ref{LP761} specifies that \upsmon\ on \mgmt\ will monitor \UPSiii\ which
supplies power to the undisclosed device.

\ul

\li The UPS name \UPSiii\ must correspond to that declared in \upsconf\ line
\ref{LP715}.

\li The ``power value'' \texttt{1} is the number of power supplies that this
UPS feeds on the local system.  A ``power value'' of 0 means that the
\UPSiii\ does not supply power to \mgmt.

\li \texttt{nut-admin} is the ``user'' declared in \upsdusers\ line \ref{LP750}.

\li \texttt{sekret} is the l33t password declared in \upsdusers\ line
\ref{LP751}.

\li \texttt{primary} means this system will shutdown last, allowing any secondaries
time to shutdown first.  There are no secondaries on \gold.

\eul

Line \ref{LP762} specifies that \upsmon\ on \mgmt\ will also monitor
\UPSii\ which supplies the \gold\ computer.

Line \ref{LP763} specifies that \upsmon\ on \mgmt\ will monitor \UPSi\ which
supplies power to \mgmt\ itself.  Note the ``power value'' of 1.

Line \ref{LP764} declares that \upsmon\ is also to monitor the heartbeat.

On line \ref{LP765}, \texttt{MINSUPPLIES} sets the number of power supplies
that must be receiving power to keep the \mgmt\ system running.  A lot of
computers have just one power supply, so the default value of 1 is
acceptable. See \NUTman{upsmon.conf} and file
\href{http://www.susaaland.dk/sharedoc/nut-2.0.3/docs/big-servers.txt}{\texttt{big-servers.txt}}
in the NUT documentation for more details.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP770]  & \verb`SHUTDOWNCMD "/sbin/shutdown -h +0"` \\
\Clunk[LP771]  & \verb`NOTIFYCMD /usr/sbin/upssched` \\
\Clunk[LP772]  & \verb`POLLFREQ 5` \\
\Clunk[LP773]  & \verb`POLLFREQALERT 5` \\
%\Clunk[LP774]  & \verb`HOSTSYNC 15` \\
\Clunk[LP775]  & \verb`DEADTIME 15` \\
\Clunk[LP776]  & \verb`POWERDOWNFLAG /etc/killpower` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for \mgmt, part 2 of 5.\label{fig:upsmonconf2.big}}
\end{figure}

Line \ref{LP770} declares the command to be used to shut down \mgmt.
A second instance of the \upsmon\ daemon running as root on
\mgmt\ will execute this command.  Multiple commands are possible, for
example \texttt{SHUTDOWNCMD "logger -t upsmon.conf \bsl"SHUTDOWNCMD
  calling /sbin/shutdown to shut down system\bsl" ; /sbin/shutdown -h
  +0"} will also log the action of \texttt{SHUTDOWNCMD}.  Note that
internal " have to be escaped.  Note also that any calls of the
command \texttt{upsmon -c fsd} will also execute this command.  See
line \ref{LP894}.

The shutdown command for \gold\ is not specified in \upsmonconf.  It appears
in the user script \upsschedcmd\ in chapter \ref{section:upsschedcmd.big}.

Line \ref{LP771} says which program is to be invoked when \upsmon\ detects a
NOTIFY event flagged as \texttt{EXEC}.

Line \ref{LP772}, \texttt{POLLFREQ}, declares that the \upsmon\ daemon will
poll \upsd\ in \gold\ and in \mgmt\ every 5 seconds.

Line \ref{LP773}, \texttt{POLLFREQALERT}, declares that the \upsmon\ daemon
will poll the \upsd\ daemons every 5 seconds while any UPS in on battery.

Line \ref{LP775}, \texttt{DEADTIME} specifies how long \upsmon\ will allow a
UPS to go missing before declaring it ``dead''. The default is 15 seconds.

Daemon \upsmon\ requires a UPS to provide status information every few seconds
as defined by \texttt{POLLFREQ} and \texttt{POLLFREQALERT}. If the status
fetch fails, the UPS is marked stale. If it stays stale for more than
\texttt{DEADTIME} seconds, the UPS is marked dead.

A dead \UPSi\ that was last known to be on battery \status{\OB} is assumed to
have changed to a low battery condition \statuschange{\OB}{\OB\ \LB}. This may
force a shutdown of \mgmt. Disruptive, but the alternative is barreling ahead
into oblivion and crashing when you run out of power.  See chapter
\ref{section:shutdown.dual} for more discussion.

Line \ref{LP776}, \texttt{POWERDOWNFLAG} declares a file created by
\upsmon\ when running in primary mode when \UPSi\ needs to be powered off.  See
\NUTman{upsmon.conf} for details.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP780]  & \verb`NOTIFYMSG ONLINE   "UPS %s: On line power."` \\
\Clunk[LP781]  & \verb`NOTIFYMSG ONBATT   "UPS %s: On battery."` \\
\Clunk[LP782]  & \verb`NOTIFYMSG LOWBATT  "UPS %s: Battery is low."` \\
\Clunk[LP783]  & \verb`NOTIFYMSG REPLBATT "UPS %s: Battery needs to be replaced."` \\
\Clunk[LP784]  & \verb`NOTIFYMSG FSD      "UPS %s: Forced shutdown in progress."` \\
\Clunk[LP785]  & \verb`NOTIFYMSG SHUTDOWN "Auto logout and shutdown proceeding."` \\
\Clunk[LP787]  & \verb`NOTIFYMSG COMMOK   "UPS %s: Communications (re-)established."` \\
\Clunk[LP786]  & \verb`NOTIFYMSG COMMBAD  "UPS %s: Communications lost."` \\
\Clunk[LP788]  & \verb`NOTIFYMSG NOCOMM	  "UPS %s: Not available."` \\
\Clunk[LP789]  & \verb`NOTIFYMSG NOPARENT "upsmon parent dead, shutdown impossible."` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for \mgmt, part 3 of 5.\label{fig:upsmonconf3.big}}
\end{figure}

Lines \ref{LP780}-\ref{LP789} assign a text message to each NOTIFY event.
Within each message, the marker \texttt{\%s} is replaced by the name of the
UPS which has produced this event.  On \mgmt\ \upsmon\ passes this message to
program \texttt{wall} to notify the system administrator of the event.  You
can change the default messages to something else if you like.  The format is
\texttt{NOTIFYMSG event "\textsl{message}"} where \texttt{\%s} is replaced
with the identifier of the UPS in question.  Note that program \texttt{wall}
has not been internationalized and does not support accented letters or non
latin characters.  When the corresponding \texttt{NOTIFYFLAG} contains the
symbol \texttt{EXEC}, \upsmon\ also passes the message to the program
specified by \texttt{NOTIFYCMD} on line \ref{LP771}.

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP790]  & \verb`NOTIFYFLAG ONLINE   EXEC` \\
\Clunk[LP791]  & \verb`NOTIFYFLAG ONBATT   EXEC` \\
\Clunk[LP792]  & \verb`NOTIFYFLAG LOWBATT  SYSLOG+WALL` \\
\Clunk[LP793]  & \verb`NOTIFYFLAG REPLBATT SYSLOG+WALL` \\
\Clunk[LP794]  & \verb`NOTIFYFLAG FSD      SYSLOG+WALL` \\
\Clunk[LP795]  & \verb`NOTIFYFLAG SHUTDOWN SYSLOG+WALL` \\
\Clunk[LP797]  & \verb`NOTIFYFLAG COMMOK   SYSLOG+WALL` \\
\Clunk[LP796]  & \verb`NOTIFYFLAG COMMBAD  SYSLOG+WALL` \\
\Clunk[LP798]  & \verb`NOTIFYFLAG NOCOMM   SYSLOG+WALL` \\
\Clunk[LP799]  & \verb`NOTIFYFLAG NOPARENT SYSLOG+WALL` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for \mgmt, part 4 of 5.\label{fig:upsmonconf4.big}}
\end{figure}

Lines \ref{LP790}-\ref{LP799} declare what is to be done at each NOTIFY event.
The declarations, known as ``flags'' are shown in table \refpage{fig:flags}. You
may specify one, two or three flags for each event, in the form
\texttt{FLAG[+FLAG]*}, however \texttt{IGNORE} must always be alone.

Lines \ref{LP790}-\ref{LP791} carry only the \texttt{EXEC} flag: Since the
heartbeat induces a lot of \NOTev{\ONLINE} and \NOTev{\ONBATT} traffic, the
\texttt{SYSLOG} option would flood the log and \texttt{WALL} would put far
too many useless messages in xterm windows.  When the NOTIFY event occurs,
\texttt{EXEC} declares that \upsmon\ should call the program identified by the
\texttt{NOTIFYCMD} on line \ref{LP771}.

Note that if you have multiple UPS's, the same actions are to be performed for
a given NOTIFY event for all the UPS's.  \textsl{Once again, we see that this
  is not good news.}

\begin{figure}[ht]
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[LP800]  & \verb`RBWARNTIME 43200` \\
\Clunk[LP801]  & \verb`NOCOMMWARNTIME 300` \\
\Clunk[LP802]  & \verb`FINALDELAY 5` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsmonconf\ for \mgmt, part 5 of 5.\label{fig:upsmonconf5.big}}
\end{figure}

When a UPS says that it needs to have its battery replaced, upsmon will
generate a \NOTev{\REPLBATT}\ NOTIFY event.  Line \ref{LP800} say that this happens
every \texttt{RBWARNTIME} = 43200 seconds (12 hours).

Line \ref{LP801}: Daemon \upsmon\ will trigger a \NOTev{\NOCOMM}\ NOTIFY event after
\texttt{NOCOMMWARNTIME} seconds if it can't reach any of the UPS entries in
configuration file \upsmonconf.  It keeps warning you until the situation is
fixed.

Line \ref{LP802}: When running in primary mode, \upsmon\ waits this
long after sending the \NOTev{\SHUTDOWN}\ NOTIFY event to warn the
users. After the timer elapses, it then runs your \texttt{SHUTDOWNCMD}
as specified on line \ref{LP770}.  If you need to let your users do
something in between those events, increase this number. Don't make
this too big, even though the battery still has charge.
Alternatively, you can set this very low so you don't wait around when
it's time to shut down.

For lots and lots of details, see \NUTman{upsmon.conf}.  See also the file
\href{https://github.com/networkupstools/nut/blob/master/docs/config-notes.txt}
     {\texttt{config{\allowbreak}-notes.txt}} in the distribution.

\subsection{\Hsep\ Configuration file \upsschedconf\ for mgmt}\label{section:upsschedconf.big}

Daemon \upsmon\ in \mgmt\ detects the NOTIFY events due to status
changes in \gold\ and in \mgmt, and for those flagged as \texttt{EXEC}
in \upsmonconf\ calls \upssched\ as indicated by the
\texttt{NOTIFYCMD} directive.  The program \upssched\ provides a
richer set of actions than \upsmon, especially the management of
timers.

\begin{figure}[ht]
\begin{LinePrinter}[1.00\LinePrinterwidth]
\Clunk[LP810]  & \verb`# upssched.conf  -- mgmt --` \\
\Clunk[LP811]  & \verb`CMDSCRIPT /usr/bin/upssched-cmd` \\
\Clunk         & \verb`# PIPEFN LOCKFN suitable for Debian 11` \\
\Clunk[LP812]  & \verb`PIPEFN /run/nut/upssched.pipe` \\
\Clunk[LP813]  & \verb`LOCKFN /run/nut/upssched.lock` \\
\Clunk         & \\
\Clunk[LP820]  & \verb`AT ONBATT UPS-3@gold      START-TIMER UPS-3-two-minute-warning-timer 5` \\
\Clunk[LP821]  & \verb`AT ONBATT UPS-3@gold      START-TIMER UPS-3-shutdown-timer 125` \\
\Clunk[LP822]  & \verb`AT ONLINE UPS-3@gold      CANCEL-TIMER UPS-3-two-minute-warning-timer` \\
\Clunk[LP823]  & \verb`AT ONLINE UPS-3@gold      CANCEL-TIMER UPS-3-shutdown-timer` \\
\Clunk[LP824]  & \verb`AT ONLINE UPS-3@gold      EXECUTE UPS-3-back-on-line` \\
\Clunk         & \\
\Clunk[LP830]  & \verb`AT ONBATT UPS-2@gold      START-TIMER UPS-2-two-minute-warning-timer 5` \\
\Clunk[LP831]  & \verb`AT ONBATT UPS-2@gold      START-TIMER UPS-2-shutdown-timer 125` \\
\Clunk[LP832]  & \verb`AT ONLINE UPS-2@gold      CANCEL-TIMER UPS-2-two-minute-warning-timer` \\
\Clunk[LP833]  & \verb`AT ONLINE UPS-2@gold      CANCEL-TIMER UPS-2-shutdown-timer` \\
\Clunk[LP834]  & \verb`AT ONLINE UPS-2@gold      EXECUTE UPS-2-back-on-line` \\
\Clunk         & \\
\Clunk[LP840]  & \verb`AT ONBATT UPS-1@localhost START-TIMER UPS-1-two-minute-warning-timer 5` \\
\Clunk[LP841]  & \verb`AT ONBATT UPS-1@localhost START-TIMER UPS-1-shutdown-timer 125` \\
\Clunk[LP842]  & \verb`AT ONLINE UPS-1@localhost CANCEL-TIMER UPS-1-two-minute-warning-timer` \\
\Clunk[LP843]  & \verb`AT ONLINE UPS-1@localhost CANCEL-TIMER UPS-1-shutdown-timer` \\
\Clunk[LP844]  & \verb`AT ONLINE UPS-1@localhost EXECUTE UPS-1-back-on-line` \\
\Clunk         & \\
\Clunk[LP850]  & \verb`AT ONBATT heartbeat@localhost CANCEL-TIMER heartbeat-failure-timer` \\
\Clunk[LP851]  & \verb`AT ONBATT heartbeat@localhost START-TIMER  heartbeat-failure-timer 660` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Configuration file \upsschedconf\ for \mgmt.\label{fig:upsschedconf.big}}
\end{figure}

On line \ref{LP811} \texttt{CMDSCRIPT} points to a user script to be called
for designated NOTIFY events.  This script will receive as argument the user
chosen timer name.

Line \ref{LP812} defines \texttt{PIPEFN} which is the file name of a socket
used for communication between \upsmon\ and \upssched.  It is important that
the directory be accessible to NUT software and nothing else.  For line
\ref{LP812} the Debian distribution uses
\texttt{/var/{\allowbreak}run/nut/{\allowbreak}upssched.pipe}.

Daemon \upsmon\ requires the \texttt{LOCKFN} declaration on line \ref{LP813}
to avoid race conditions.  The directory should be the same as
\texttt{PIPEFN}.

\subsubsection{\Hsep\ \UPSiii\ on gold}\label{UPSiiigold}

Lines \ref{LP820} and \ref{LP821} say what is to be done by \upssched\ for a
NOTIFY event \NOTev{\ONBATT} due to \UPSiii\ on \gold.  On line \ref{LP820}
the \texttt{START-TIMER} says that \upssched\ is to create and manage a timer
called ``\UPSiiiwarntime'' which runs for 5 seconds.  When this timer
completes, \upssched\ calls the user script specified by \texttt{CMDSCRIPT}
with argument ``\UPSiiiwarntime''.  Line \ref{LP821} does a similar thing for
the 125 second timer ``\UPSiiishutdown''.

Hopefully the back-up generator starts, and power returns before 2 minutes
have gone by.  Lines \ref{LP822}-\ref{LP824} say what is to be done by
\upssched\ for NOTIFY event \NOTev{\ONLINE}.  The \texttt{CANCEL-TIMER}
declarations say that \upssched\ must cancel the timers ``\UPSiiiwarntime''
and ``\UPSiiishutdown''.  The user script is not called.

Line \ref{LP824} command \texttt{EXECUTE} says that \upssched\ is to call the
user script immediately with the argument ``\UPSiiionline''.


\subsubsection{\Hsep\ \UPSii\ on gold}\label{UPSiigold}

\UPSii\ on \gold\ is handled in exactly the same way as \UPSiii.  Lines
  \ref{LP830} and \ref{LP831} define the timers which start when
  \upssched\ receives a NOTIFY event \NOTev{\ONBATT}, and lines \ref{LP832}
  and \ref{LP833} cancel those timers when hopefully \upssched\ receives
  NOTIFY event \NOTev{\ONLINE}.

Line \ref{LP834} command \texttt{EXECUTE} says that \upssched\ is to call the
user script immediately with the argument ``\UPSiionline''.


\subsubsection{\Hsep\ \UPSi\ on mgmt}\label{UPSigold}

\UPSi\ on \mgmt\ is also handled in exactly the same way as \UPSiii.  Lines
\ref{LP840} and \ref{LP841} define the timers which start when
\upssched\ receives a NOTIFY event \NOTev{\ONBATT}, and lines \ref{LP842} and
\ref{LP843} cancel those timers when hopefully \upssched\ receives NOTIFY
event \NOTev{\ONLINE}, however if power does not return before two minutes
have gone by, the timer ``\UPSishutdown'' will complete and \upssched\ will
call the user script with the parameter ``\UPSishutdown'' .

Line \ref{LP844} command \texttt{EXECUTE} says that \upssched\ is to call the
user script immediately with the argument ``\UPSionline''.


\subsubsection{\Hsep\ \texttt{heartbeat} on mgmt}\label{heartbeatmgmt}

On line \ref{LP850}, when daemon \upssched\ receives an \NOTev{\ONBATT} it
executes the command \texttt{CANCEL{\allowbreak}-TIMER \heartfailtimer}.  This
kills the timer.  \upssched\ does not call the user script.

Immediately afterwards, on line \ref{LP851}, and for the same \NOTev{\ONBATT}
event, \upssched\ executes command \texttt{START{\allowbreak}-TIMER
  \heartfailtimer\ 660} which restarts the \heartfailtimer\ which will run for
another 660 sec, i.e. 11 minutes.  If the timer completes, \upssched\ will
call the user script \upsschedcmd\ with parameter ``\heartfailtimer''.

%\newcolumn
\subsection{\Hsep\ User script \upsschedcmd}\label{section:upsschedcmd.big}

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP860]  & \verb`#!/bin/bash -u` \\
\Clunk[LP861]  & \verb`# upssched-cmd  -- mgmt --` \\
\Clunk[LP862]  & \verb`logger -i -t upssched-cmd Calling upssched-cmd $1` \\
\Clunk         & \\
\Clunk[LP863]  & \verb`# Send emails to/from these addresses` \\
\Clunk[LP864]  & \verb`EMAIL_TO="sysadmin@example.com"` \\
\Clunk[LP865]  & \verb`EMAIL_FROM="upssched-cmd@${HOSTNAME:-nut}.example.com"` \\
\Clunk         & \\
\Clunk[LP866]  & \verb`function make-STCH {` \\
\Clunk[LP867]  & \verb`   STCH="[$( upsc $1 ups.status )]:$( upsc $1 battery.charge )%"}` \\
\Clunk[LP868]  & \verb`case $1 in` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{User script \upsschedcmd\ on \mgmt, 1 of 5.\label{fig:upsschedcmd1.big}}
\end{figure}

The user script \upsschedcmd, the example we show is in Bash, manages the
completion of \UPSiiiwarntime, \UPSiiwarntime, \UPSiwarntime, \UPSiiishutdown,
\UPSiishutdown, \UPSishutdown, \UPSiiionline, \UPSiionline, \UPSionline\ and
\heartfailtimer.
  
There is no such thing as a single script which fits all industrial
situations, but here is an example of what can be done.  You will probably
need to modify this for your own use.  Note that this script could be written
in the language of your choice, as long as the resulting program is able to
receive the timer names as a parameter, send e-mails and log and notify the
users of messages.  Bash has the advantage of being widely available and is
understood by many sysadmins.

In figure \ref{fig:upsschedcmd1.big}, on lines \ref{LP864} and \ref{LP865},
  change the e-mail addresses to something that works for you.

Lines \ref{LP866}-\ref{LP867} declare a function which prepares a Bash
variable \texttt{STCH} which gives the current UPS status and battery charge.
This is to be included in messages, so we get a clearer idea of what is
happening.

The bulk of the user script is a case statement beginning at line \ref{LP868}
covering all the possible parameter values (timer names) that the user script
may expect.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP880]  & \verb`(UPS-3-two-minute-warning-timer)  make-STCH UPS-3@gold`  \\
\Clunk[LP881]  & \verb`   MSG="UPS-3: gold power failure. $STCH" ;;`  \\
\Clunk[LP882]  & \verb`(UPS-3-shutdown-timer)            make-STCH UPS-3@gold`  \\
\Clunk[LP883]  & \verb`   MSG="UPS-3: gold shutdown. $STCH" ;;`  \\
\Clunk[LP884]  & \hspace{25mm}\textsl{Commands for undisclosed device shutdown, e.g. saltstack} \\
\Clunk[LP885]  & \verb`(UPS-3-back-on-line)              make-STCH UPS-3@gold`  \\
\Clunk[LP886]  & \verb`   MSG="UPS-3: power returns. $STCH"  ;;`  \\
\end{LinePrinter}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP889]  & \hspace{25mm}\textsl{Case ``UPS-2'' is very similar}  \\
\end{LinePrinter}
\vspace{-6mm}
\caption{User script \upsschedcmd\ on \mgmt, 2 of 5.\label{fig:upsschedcmd2.big}}
\end{figure}

In figure \ref{fig:upsschedcmd2.big}, lines \ref{LP880}-\ref{LP886} cover the
events associated with \UPSiii\ on \gold.  When an \NOTev{\ONBATT} occurs the
sysadmin receives \texttt{wall} and \texttt{notify} warnings that power to the
undisclosed device has failed, and that unless alternative power becomes
available in two minutes, the undisclosed device will be shut down.  These
warnings contain the text assembled in Bash variable \texttt{MSG}.
Additionally, when the \NOTev{\ONBATT} occurs \upssched\ begins a two minute
timer \UPSiiishutdown.  If no alternative power appears, and this timer
expires, the installation specific code on line \ref{LP884} will shut down the
undisclosed device attached to \gold.  This code might for example be based on 
\href{https://docs.saltstack.com/en/latest/topics/index.html}%
{the \texttt{saltstack} remote management tools}.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP890]  & \verb`(UPS-1-two-minute-warning-timer)  make-STCH UPS-1`  \\
\Clunk[LP891]  & \verb`   MSG="UPS-1: gold power failure. $STCH" ;;`  \\
\Clunk[LP892]  & \verb`(UPS-1-shutdown-timer)            make-STCH UPS-1`  \\
\Clunk[LP893]  & \verb`   MSG="UPS-1: gold shutdown. $STCH"`  \\
\Clunk[LP894]  & \verb`   /usr/sbin/upsmon -c fsd ;;`  \\
\Clunk[LP895]  & \verb`(UPS-1-back-on-line)              make-STCH UPS-1`  \\
\Clunk[LP896]  & \verb`   MSG="UPS-1: power returns. $STCH"  ;;`  \\
\end{LinePrinter}
\vspace{-6mm}
\caption{User script \upsschedcmd\ on \mgmt, 3 of 5.\label{fig:upsschedcmd3.big}}
\end{figure}

In figure \ref{fig:upsschedcmd3.big}, lines \ref{LP890}-\ref{LP896}
cover the events associated with \UPSi\ on \mgmt.  When an
\NOTev{\ONBATT} occurs the sysadmin receives \texttt{wall} and
\texttt{notify} warnings that power to the management workstation has
failed, and that unless alternative power becomes available in two
minutes, the workstation will be shut down.  These warnings contain
the text assembled in Bash variable \texttt{MSG}.  Additionally, when
the \NOTev{\ONBATT} occurs \upssched\ begins a two minute timer
\UPSishutdown.  If no alternative power appears, and this timer
expires, the command \texttt{upsmon -c fsd} on line \ref{LP894} will
shut down the workstation by executing the command specified by
\texttt{SHUTDOWNCMD} on line \ref{LP770}.


\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP900]  & \verb`(heartbeat-failure-timer)         make-STCH heartbeat` \\
\Clunk[LP901]  & \verb`   MSG="NUT heart beat fails. $STCH" ;;` \\
\Clunk[LP902]  & \verb`   MSG1="Hello, upssched-cmd reports NUT heartbeat has failed."` \\
\Clunk[LP903]  & \verb`   MSG2="Current status: $STCH \n\n$0 $1"` \\
\Clunk[LP904]  & \verb`   MSG3="\n\n$( ps -elf | grep -E 'ups[dms]|nut' )"` \\
\Clunk[LP905]  & \verb`   echo -e "$MSG1 $MSG2 $MSG3" | /bin/mail -r "$EMAIL_FROM" \` \\
\Clunk[LP906]  & \verb`        -s "NUT heart beat fails. Currently $CHMSG" "$EMAIL_TO" ;;` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{User script \upsschedcmd\ on \mgmt, 4 of 5.\label{fig:upsschedcmd4.big}}
\end{figure}

In figure \ref{fig:upsschedcmd4.big}, lines \ref{LP900}-\ref{LP906} cover the
event associated with \texttt{heartbeat} on \mgmt.  The ``heartbeat''
technique is discussed in detail in chapter \refpage{heartbeat}.  If the
\heartfailtimer\ completes then something is wrong with NUT, and lines
\ref{LP902}, \ref{LP903} and \ref{LP904} prepare a message for the sysadmin in
Bash variables \texttt{MSG1}, \texttt{MSG2} and \texttt{MSG3}.  Lines
\ref{LP905}-\ref{LP906} e-mail the message to the sysadmin.  The message
includes the current state of those NUT kernel processes which are
operational.

\begin{figure}[ht]
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP910]  & \verb`(*) logger -i -t upssched-cmd "Bad arg: \"$1\", $CHMSG"` \\
\Clunk[LP911]  & \verb`      exit 1 ;;` \\
\Clunk[LP912]  & \verb`esac`  \\
\Clunk[LP913]  & \verb`logger -i -t upssched-cmd $MSG` \\
\Clunk[LP914]  & \verb`notify-send-all "$MSG"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{User script \upsschedcmd\ on \mgmt, 5 of 5.\label{fig:upsschedcmd5.big}}
\end{figure}

In figure \ref{fig:upsschedcmd5.big}, lines \ref{LP910}-\ref{LP911} cover any
unexpected parameter values, and lines \ref{LP913}-\ref{LP914} log the message
and pass it to the system notification.

\newcolumn
\subsection{\Hsep\ The shutdown story}\label{section:goldshutdown}

\UPSiii\ on \gold: If \UPSiii\ detects that power has failed, and takes over
the supply to the undisclosed device, then the NUT setup will advise the
system administrator on the \mgmt\ workstation.  If the backup generator comes
on automatically before two minutes, then the sysadmin on \mgmt\ will be
informed, but if power does not re-appear, then script \upsschedcmd\ in
\mgmt\ will remotely command the ``shutdown'' of the undisclosed device.  A
complete shutdown may be impossible, and all that can be done for some
equipment is to put it into a quiescent state.  The management workstation
\mgmt\ is not shut down.

\UPSii\ on \gold: If \UPSii\ detects that its own power supply has failed, and
that it is now powering \gold, then the NUT setup of this chapter will advise
the system administrator on the \mgmt\ workstation.  With the example
configuration, if power is not restored in two minutes then an action in the
script \upsschedcmd\ will shut down both \gold\ and the undisclosed device.
Workstation \mgmt\ is not shut down.

\UPSi\ on \mgmt: If \UPSi\ detects that its own power supply has failed, and
the workstation management is now on battery power, then we enter the scenario
described in detail in chapter \refpage{section:bad}.  There is no need to shutdown
the undisclosed device or \gold.  A backup workstation on a different site
could take over the management of \UPSiii\ and \UPSii.

\vspace*{\fill}
\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}
\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-3.jpg, height=36mm}
\end{center}

\vspace*{\fill}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                            P A R T  2                                  %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage

% Layout for the body.  See the LaTeX Companion, p.96.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[TLS Support]{TLS Support}                              % \lhead[left-header-even]{left-header-odd}
\chead[ConfigExamples \Version]%
      {ConfigExamples \Version}                               % \chead[centre-header-even]{centre-header-odd}
\rhead[\LaTeX\ run \isodate]{\LaTeX\ run \isodate}            % \rhead[right-header-even]{right-header-odd}
\lfoot[]{}                                                    % \lfoot[left-footer-even]{left-footer-odd}
\cfoot[\fancyplain{}{Page \thepage\ of \pageref{LastPage}}]%
      {\fancyplain{}{Page \thepage\ of \pageref{LastPage}}}   % \cfoot[centre-footer-even]{centre-footer-odd}
\rfoot[]{}                                                    % \rfoot[right-footer-even]{right-footer-odd}

%\setcounter{section}{19}
\begin{center}
\addtocontents{toc}{\protect\vspace{3mm}}
\part[\hspace{\fill}\textsf{TLS support for \upsd\ and clients}\hspace{\fill}]{}\label{part:shim}
\addtocontents{toc}{\protect\vspace{3mm}}
\vspace{7mm}
\scalebox{1.0}[1.2]{\textsf{\Huge{TLS support for upsd and clients}}}
\vspace{7mm}
\end{center}

\textit{This part describes TLS support for current release 2.8.0 and
  the previous release 2.7.4 which is still part of current
  distributions.}

\textit{If you are not interested in Python internals, then one click
  and you are in chapter \ref{section:TLS}.}

\vspace{7mm}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
%\newcolumn
\section{\Hsep\ Introduction}\label{section:pyIntro}

The description of the Python3 scripts in this Part supposes that you have
some experience as a system administrator and that you are already familiar
with NUT, it's component daemons and configuration files as described in Part
\ref{part:NUT}.

\subsection{\Hsep\ Use of Python3}\label{section:pyUse}

\subsubsection{\Hsep\ No object orientation}\label{section:OO}

\textit{The Python language was originally designed in the apparent
  belief that all would be OO, but this is now weakening\footnote{ See
  \href{https://medium.com/better-programming/object-oriented-programming-the-trillion-dollar-disaster-92a4b666c7c7}%
       {Object-Oriented Programming — The Trillion Dollar Disaster,
         Ilya Suzdalnitski.}}  as one writer put it « in order to
  attract a larger audience} ».

The Python3 scripts are not ``object oriented'' (OO).  NUT itself is a
process control application and is ``event oriented'', not ``object
oriented''.  The Python scripts of part \ref{part:shim} are similarly
``event oriented'', and the design will be evident to those familiar
with the NUT C code.

The Python scripts proposed for NUT provide a set of functions, and a main
program written in an imperative style --- very similar to the NUT C programs.
The coding syntax itself is influenced by the OO origins of Python.  For
example the concatenation of two strings \texttt{a} and \texttt{b} is written
\texttt{''.join([a, b])}.  In OO parlance the class of the empty string
\texttt{''} provides the method \texttt{join} with a list of parameters.
However no OO skill or conviction is needed to read the proposed scripts.

\subsubsection{\Hsep\ Lint-free code}\label{section:lint}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|r|p{0.9\LinePrinterwidth}|}
\hline
    & \multicolumn{1}{|c|}{\textbf{Global changes from default in \pylintrc}} \\ \hline\hline
 1  & Indentation string reduced from 4 to 2 spaces. \\ \hline
 2  & Allow lines up to 132 characters instead of 100. \\ \hline
 3  & Disabled the undefined-variable option.  This looks like a pylint bug. \\ \hline
 4  & Disabled the bad-whitespace, bad-continuation, multiple-statements and broad-except options. \\ \hline
 5  & Removed statistical reports from output. \\ \hline
 6  & Comment out the deprecated option ``symbols''. \\ \hline
 7  & Option include-naming-hint is turned on. \\ \hline
 8  & Option max-module-lines increased from 1000 to 4000. \\ \hline
 9  & Options module-rgx and module-naming-hint changed.
      Modules may have names of form \texttt{[a-zA-Z][a-zA-Z0-9]*} \\ \hline
10  & Option variable-rgx allows uppercase letters.
      Variables may have names of the form \texttt{[a-zA-Z\_][a-zA-Z0-9\_]\{2,30\}} \\ \hline
11  & Option const-rgx allows lower case letters.
      Constants may have names of the form \texttt{([a-zA-Z\_][a-zA-Z0-9\_]*)|(\_\_.*\_\_)} \\ \hline\hline
\multicolumn{2}{c}{\vphantom{3mm}} \\ \hline
    & \multicolumn{1}{|c|}{\textbf{Local changes from default included in code}} \\ \hline\hline
12  & \verb`# pylint: disable=global-statement`
      Python PEP 8 dislikes the use of global variables.
      We find simple and effective use, and inhibit the warning. \\ \hline
13  & \verb`# pylint: disable=anomalous-backslash-in-string`
      This warning is a Pylint false positive. \\ \hline
14  & \verb`# pylint: disable=undefined-loop-variable`
      Pylint dislikes \texttt{var = var + ...} \\ \hline\hline
\end{tabular}
\caption{File \pylintrc, Changes to the default Python style.\label{fig:lint}}
\end{center}
\end{figure}

The Python3 scripts described in this documentation are ``lint free''
as determined by the \href{https://www.pylint.org/}{pylint program}
which follows the \href{https://www.python.org/dev/peps/pep-0008/}{PEP
  8 style guide for Python code}.  Since the Python3 programs
described here are a contribution to NUT rather than the general
Python ecosystem, changes have been made to allow NUT characteristics
to be freely expressed.  These changes to the default Python style are
defined by file \pylintrc, and shown in figure \ref{fig:lint}.

The \href{https://www.python.org/dev/peps/pep-0008/}{PEP 8 style guide
  for Python code} requires that no line include trailing spaces.  To
remove trailing spaces using emacs, try command
\verb`M-x replace-regexp RET `\textvisiblespace\verb`+$ RET RET`
where \textvisiblespace\ is a space.  How does vim do this?  The l33t
use commnd \verb`:%s/\s\+$//e`


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ \mkNUTcert\ builds TLS certificates}\label{section:TLS}

A secure network connection between the Attachment Daemon and the
Management Daemon requires use of TLS (Transport Layer Security)
public and private keys.  TLS replaces its now-deprecated predecessor,
Secure Sockets Layer (SSL) used by release 2.7.4 \upsd\ and \upsmon.
Building keys which meet the increasingly complex requirements of the
Internet is not obvious.  The Python3 utility script
\mkNUTcert\ described here builds a TLS private key for a server such
as \upsd, a self-signed CA certificate and a certificate for a client
such as \upsmon\ that wishes to access the server. The status is
``experimental''.  The script is optimised for use with NUT and is
expected to be run on the same machine as \upsd.  It is intended for
demonstration and experiment.  The license is GPL v3 or later at your
choice, with support in the \mailinglist.


\subsection{\Hsep\ Very Short Introduction to TLS Certificates}\label{section:TLS.intro}

SSL and the TLS that has replaced SSL are a quagmire of technical terms many
of which are out-of-date, confusing or incorrectly used.  The OpenSSL project
has produced a Swiss Army Knife\footnote{I counted 48 tools in version
  1.1.0f.} of utilities which are the best known tools for work in this area.
Anyone venturing into this mess has to do a lot of reading.  Here is a very
short list.

\ul

\li The Network UPS Tools User Manual,
  \href{https://networkupstools.org/docs/user-manual.chunked/ar01s09.html}%
       {chapter 9, Notes on securing NUT}.

\li The NUT man pages \NUTman{upsd.conf} and \NUTman{upsmon.conf}.

\li The command \texttt{openssl help} followed by \texttt{openssl
  \textsl{command} -help} for details of the options offered by the
\texttt{\textsl{command}} tool.

\li The \href{https://linux.die.net/man/1/openssl}%
             {openssl man page} and it's copious ``See Also''. 
       
\li Ivan Risti\'{c}'s ``A Short Guide to the Most Frequently Used OpenSSL
Features and Commands'' available at web site feistyduck.com
\href{https://www.feistyduck.com/library/openssl-cookbook/online/}%
     {OpenSSL Cookbook}.

\li Web site digitalocean.com,
     \href{https://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs}%
     {OpenSSL Essentials: Working with SSL Certificates, Private Keys and CSRs}.

\li Web site zytrax.com, 
  \href{http://www.zytrax.com/tech/survival/ssl.html}%
       {Survival guides - TLS/SSL and SSL (X.509) Certificates}.

\li Website how2ssl.com, 
\href{http://how2ssl.com/articles/openssl\_commands\_and\_tips/}%
     {OpenSSL tips and common commands}.

\eul
       
Here is a short summary of technical terms used in this chapter, see also
\href{https://serverfault.com/questions/9708/what-is-a-pem-file-and-how-does-it-differ-from-other-openssl-generated-key-file}%
     {this post}.

\begin{description}

\item[Certificate] A file containing the public key used by clients to
  communicate with the server, possibly with additional information.  For
  public keys we use file names of the form \\ 
  \texttt{\textit{mybox}-client.cert.pem} where \textit{mybox} is the name
  of the \upsd\ server.
  
\item[Certificate Authority (CA)] Commercial businesses and others who
  want their customers to feel safe using their sites have their TLS
  certificates verified by a Certificate Authority (CA). You apply
  with a Certificate Signing Request (CSR), pay and receive a copy of
  your certificate linked to a trusted root certificate, for some
  meaning of ``trust''.

  Where does NUT stand?  We are our own Certificate Authority and the
  certificate we create is itself the root certificate.  We do nut use
  CSRs.  We trust ourselves.  In a closed industrial context where few
  people have access to the systems, this provides better security
  than the commercial offerings used on the web.  Quoting from
  \RFCkey, section 3.2:
\begin{quotation}
  (a)  Certification paths start with a public key of a CA in a
       user's own domain, or with the public key of the top of a
       hierarchy.  Starting with the public key of a CA in a user's
       own domain has certain advantages.  In some environments, the
       local domain is the most trusted.
\end{quotation}

\item[Root certificate] A Certifying Authority takes the private key
  and provides a certificate of authenticity known as a ``root
  certificate''.  However in the commercial world intermediaries
  appear and get paid to add their certificates, thus forming a
  ``chain of trust''.  NUT does not have such a chain.  The root
  certificate is the only one.  In NUT's self-signed world, the
  \upsd\ server uses as private key a file which contains the private
  key and then the root certificate\footnote{In that order.  See
  figure \ref{fig:privatekeycert}}.  For the private key we use a file
  name of the form \texttt{\textit{mybox}.cert.pem} where
  \textit{mybox} is the name of the \upsd\ server.  The clients will
  use just the root certificate which contains the public key.

\item[PEM] PEM is an encoding \footnote{Historically, this encoding was used
  for early networks which only guaranteed to transmit 7 of the 8 bits in a
  byte.}  format for a certificate which is already ASN1 encoded and which
  allows it to be included in ``ascii'' base 64 files.  If you are curious,
  the three letters PEM stand for Privacy-enhanced Electronic Mail.  We use
  file type \texttt{.cert.pem} for these certificate files, but you will also
  find such certificates with just the \texttt{pem} extension.

\item[CSR] A Certificate Signing Request contains the private key and the
  additional information needed to build the public key certificate.  A CSR is
  needed for public sites for which an expensive external service will sign
  the certificate as authentic and valid (for some value of authentic and
  valid).  Since UPS units are not a public matter, we sign our own
  certificates.  NUT does not use CSR's.

\end{description}

\newcolumn
\subsection{\Hsep\ Overview of \mkNUTcert}\label{section:TLSoview}

The script has many options, but in general few and in some simple cases none
at all are needed.  To see the options and their default values enter command
\texttt{mkNUTcert.py -\/-help}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.85\LinePrinterwidth]
\Clunk[MK000]  & \verb`$ mkNUTcert.py --help` \\
\Clunk[MK001]  & \verb`usage: mkNUTcert.py  [-h] [-SAN <list of server names>]` \\
\Clunk[MK002]  & \verb`  [-C <ISO 3166 two letters>] [-O <name>] [-OU <unit name>]` \\
\Clunk[MK003]  & \verb`  [--serialNumber <integer>] [--notBefore <integer>]` \\
\Clunk[MK004]  & \verb`  [--notAfter <integer>] [-s <filename>] [-c <filename>] [-v]` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Command \texttt{mkNETcert.py -\/-help}.\label{fig:optionhelp}}
\end{figure}

Let's look at these optional arguments in more detail.  

\begin{description}
\item[\texttt{-\/-clientcertfile \textit{<filename>}},
      \texttt{-c \textit{<filename>}}]
  File path and name for the client's certificate.  \mkNUTcert\ tries
  to guess where to put things.  Lucky Debian users might see
  \texttt{/etc/nut/{\allowbreak}\textit{mybox}-client.cert.pem}
  .  All the clients of the \upsd\ server use this certificate.

\item[\texttt{-\/-countryName \textit{<ISO 3166 two letters>}},
      \texttt{-C \textit{<ISO 3166 two letters>}}]
  \hfill Please feel free to specify your 2 digit \ISOpays.
  The default is ``\texttt{FR}''.

\item[\texttt{-h, -\/-help}] show this help message and exit

\item[\texttt{-O \textit{<name>}},
      \texttt{-\/-organisationName \textit{<name>}}]
  The proud default for organisation name is \texttt{``Network UPS
    Tools''}.  You probably don't have to change this.

\item[\texttt{-OU \textit{<unit name>}},
      \texttt{-\/-organisationUnitName \textit{<unit name>}}]
  The default value for the Organisation Unit
  name is ``\texttt{mkNUTcert.py version 1.1}''.  Again, you probably
  don't have to change this.

\item[\texttt{-\/-serialNumber \textit{<integer>}}] The default for
  the serial number is \texttt{1}.

\item[\texttt{-\/-servercertfile    \textit{<filename>}},
      \texttt{-s \textit{<filename>}}]
  File path and name for the server's
  certificate.  \mkNUTcert\ tries to guess where to put things.  Lucky
  users of Debian might see
  \texttt{/etc/nut/{\allowbreak}\textit{mybox}.cert.pem}
  .  See table \ref{fig:UD} for a list of possible directories.

\item[\texttt{-\/-subjectAltName \textit{<list of server names>}},
      \texttt{-SAN \textit{<list of server names>}}]
  \hfill You may well want to change this option.
  It defines a space separated list of names of the upsd server.  The
  default is ``\texttt{\textit{mybox} localhost 10.218.0.19
    mybox.example.com}'' where \texttt{\textit{mybox}} is the name of
  the machine on which you have run \mkNUTcert.  In earlier releases
  of SSL/TLS the option CN (Common Name) was used to specify the
  server name.  This is now deprecated in favour of SAN
  (subjectAltName).

\item[\texttt{-\/-notAfter \textit{<integer>}}] The validity end time
  in seconds from now.  The default is \texttt{0}, i.e.  indefinite
  validity.  Note that the value specified in the certificate is
  \texttt{Dec 31 23:59:59 9999 GMT} as required by
  \href{https://tools.ietf.org/html/rfc5280#section-4.1.2.5}{RFC 5280
    para 4.1.2.5}.

\item[\texttt{-\/-notBefore \textit{<integer>}}] The validity start
  time is seconds from the moment you run the program. The default is
  \texttt{0}, i.e. now.  You probably don't have to change this.

\item[\texttt{-v, -\/-version}] Show \mkNUTcert, Python and SSL/TLS versions,
  then exit.
\end{description}

\subsection{\Hsep\ What \mkNUTcert\ provides}\label{section:PEMencoding}

The private key and public keys, known as certificates) provided by
\mkNUTcert\ are in the form of PEM encoded files:
\ul
\li Root certificate \textsl{mybox}\texttt{.cert.pem}
\li Public certificate \textsl{mybox}\texttt{-client.key.pem}
\eul

%\newcolumn
\subsubsection{\Hsep\ Private Key and Certificate = Root Certificate}\label{section:privatekeycert}

The server's root certificate, i.e.\ private key with a self-signed
certificate, PEM encoding can be seen with command shown on line
\ref{MK010} in figure \ref{fig:privatekeycert}:

\begin{center}
\colorbox{yellow}{\parbox{0.7\LinePrinterwidth}{This file, like the root
    certificate, should be protected.  It should have very restricted
    ownership and permissions.}}
\end{center}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[MK010]  & \verb`$ grep -A1 -E "^---" /etc/nut/titan.cert.pem ` \\
\Clunk[MK011]  & \verb`-----BEGIN PRIVATE KEY-----` \\
\Clunk[MK012]  & \verb`MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQC2sJigLVujiJ0/` \\
\Clunk[MK013]  & \verb`--` \\
\Clunk[MK014]  & \verb`-----END PRIVATE KEY-----` \\
\Clunk[MK015]  & \verb`-----BEGIN CERTIFICATE-----` \\
\Clunk[MK016]  & \verb`MIIFhDCCA2ygAwIBAgIBATANBgkqhkiG9w0BAQ0FADBMMQswCQYDVQQGEwJGUjEa` \\
\Clunk[MK017]  & \verb`--` \\
\Clunk[MK018]  & \verb`-----END CERTIFICATE-----` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Root certificate = private key and certificate.\label{fig:privatekeycert}}
\end{figure}

If you attempt to display the contents of the root certificate using
the command.  \texttt{openssl x509 -text -noout -in
  /etc/nut/titan.cert.pem} then only the certificate is displayed, as
shown in figure \ref{fig:selfsign}.


\subsubsection{\Hsep\ Public Key Certificate}\label{section:publiccert}

The client's public key certificate contains the public key and
certifies\footnote{A public key certificate provides a safe way for an
entity to pass on its public key to be used in asymmetric
cryptography. The public key certificate avoids the following
situation: if Charlie creates his own public key and private key, he
can claim that he is Alice and send his public key to Bob. See
\href{https://www.techtarget.com/searchsecurity/definition/public-key-certificate}%
     {techtarget.com}.}
that it is indeed the public key corresponding to the
\upsd\ server's private key. It contains only a \texttt{CERTIFICATE}
part, not the \texttt{PRIVATE KEY} part.  The PEM encoding can be seen
with command shown on line \ref{MK250} in figure \ref{fig:publiccert}:

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[MK250]  & \verb`root@titan ~ grep -A1 -E "^---" /etc/nut/titan-client.cert.pem` \\
\Clunk[MK251]  & \verb`-----BEGIN CERTIFICATE-----` \\
\Clunk[MK252]  & \verb`MIIFhDCCA2ygAwIBAgIBATANBgkqhkiG9w0BAQ0FADBMMQswCQYDVQQGEwJGUjEa` \\
\Clunk[MK253]  & \verb`--` \\
\Clunk[MK254]  & \verb`-----END CERTIFICATE-----` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{The client's PEM encoded public certificate.\label{fig:publiccert}}
\end{figure}

Details of the certificate can be seen with the command shown on line
\ref{MK020} in figure \ref{fig:selfsign} which shows a self-signed
public certificate:

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[MK020]  & \verb`root@titan ~ openssl x509 -text -noout -in /etc/nut/titan-client.cert.pem` \\
\Clunk[MK021]  & \verb`Certificate:` \\
\Clunk[MK022]  & \verb`  Data:` \\
\Clunk[MK023]  & \verb`    Version: 3 (0x2)` \\
\Clunk[MK024]  & \verb`    Serial Number: 1 (0x1)` \\
\Clunk[MK025]  & \verb`    Signature Algorithm: sha512WithRSAEncryption` \\
\Clunk[MK026]  & \verb`    Issuer: C = FR, O = Network UPS Tools, OU = mkNUTcert.py version 1.0` \\
\Clunk[MK027]  & \verb`    Validity` \\
\Clunk[MK028]  & \verb`      Not Before: Oct 22 10:55:53 2020 GMT` \\
\Clunk[MK029]  & \verb`      Not After : Dec 31 23:59:59 9999 GMT` \\
\Clunk[MK030]  & \verb`    Subject: C = FR, O = Network UPS Tools, OU = mkNUTcert.py version 1.0` \\
\Clunk[MK031]  & \verb`    Subject Public Key Info:` \\
\Clunk[MK032]  & \verb`      Public Key Algorithm: rsaEncryption` \\
\Clunk[MK033]  & \verb`        RSA Public-Key: (4096 bit)` \\
\Clunk[MK034]  & \verb`        Modulus:` \\
\Clunk[MK035]  & \verb`          00:c0:91:c2:1c:68:83:b7:83:1e:c7:89:45:1e:c4:` \\
\Clunk[MK036]  & \verb`          ...` \\
\Clunk[MK037]  & \verb`        Exponent: 65537 (0x10001)` \\
\Clunk[MK038]  & \verb`    X509v3 extensions:` \\
\Clunk[MK039]  & \verb`      X509v3 Basic Constraints: critical` \\
\Clunk[MK040]  & \verb`        CA:TRUE` \\
\Clunk[MK041]  & \verb`      X509v3 Subject Alternative Name: ` \\
\Clunk[MK042]  & \verb`        DNS:titan, DNS:localhost, DNS:10.218.0.19, DNS:titan.example.com` \\
\Clunk[MK043]  & \verb`      X509v3 Subject Key Identifier: ` \\
\Clunk[MK044]  & \verb`        DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09` \\
\Clunk[MK045]  & \verb`  Signature Algorithm: sha512WithRSAEncryption` \\
\Clunk[MK046]  & \verb`     8c:39:6a:dc:74:41:65:de:c6:e2:0d:68:1e:61:bf:8f:d7:56:` \\
\Clunk[MK047]  & \verb`     ...` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{The self-signed public certificate.\label{fig:selfsign}}
\end{figure}

\ol 

\li The certificate is certified directly by the server's root
certificate and there are no intermediate certificates.  NUT acts as
it's own certifying authority.  For tightly controlled situations such
as UPS management, this provides better security.

\li The certificate is self-signed.  The issuer on line \ref{MK026} is also
the subject on line \ref{MK030} as required by
\href{https://tools.ietf.org/html/rfc5280#section-4.1.2.4}{RFC 5280 para
  4.1.2.4 last sentence}.

\li The value ``\texttt{Dec 31 23:59:59 9999 GMT}'' on line \ref{MK029} is
defined by \href{https://tools.ietf.org/html/rfc5280#section-4.1.2.5}{RFC 5280
  para 4.1.2.5}.

\li The public key begins on line \ref{MK035}.

\li There is no Authority Key Identifier which is obligatory for Web
certificates.  This omission is specific to self-signed certificates,
\href{https://tools.ietf.org/html/rfc5280#section-4.2.1.1}{see RFC 5280 para
  4.2.1.1}.

\eol

\clearpage
\subsection{\Hsep\ Running \mkNUTcert}\label{section:TLSrun}

\ol

\li Before running the script, check the shebang \verb`#!` in the
first line.  The default value is \verb`#!/usr/bin/python3 -u`\ .
Check that you have a sufficiently recent version of Python3 at that
address.  If your version is not sufficiently recent, you will receive
an error message from \mkNUTcert.  How do I know if I have a
sufficiently recent version of Python3?  Try running the script.  If
it runs, you're ok.  Otherwise you will need to upgrade your Python
installation.

\li Run command \texttt{mkNUTcert.py -\/-help} to see the default
values. Pay extra attention to the following:

\begin{center}
\begin{tabular}{|l|p{0.75\LinePrinterwidth}|}\hline
\textbf{Option}             & \textbf{Default Value} \\ \hline\hline
\texttt{-\/-subjectAltName} & \textit{host} \texttt{localhost 10.218.0.19} \textit{host}\texttt{.example.com} \\ \hline
\texttt{-\/-servercertfile} & \textit{Script-tries-to-guess}\texttt{/}\textit{host}\texttt{.cert.pem} \\ \hline
\texttt{-\/-clientcertfile} &\textit{Script-tries-to-guess}\texttt{/}\textit{host}\texttt{.client.cert.pem} \\ \hline
\end{tabular}
%\caption{Default values used by \mkNUTcert.\label{fig:mkNUTcertdefaults}}
\end{center}

The script also attempts to guess the owner:group for the two output
files.  You should review that choice.

\li When you run the command \texttt{mkNUTcert.py} you will be
reminded of the proposed file paths and file names for the
certificates.  Enter ``\texttt{yes}'' to confirm and anything else to
exit immediately.  If you continue, \mkNUTcert\ will report:

\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[MK300]  & \verb`Writing private key with self-signed certificate for server to file ...` \\
\Clunk[MK301]  & \verb`This file must be protected.  E.g. do not make it world readable.` \\
\Clunk[MK302]  & \verb`Current owner is nut:nut with permissions 0o600.` \\
\Clunk         & \\
\Clunk[MK303]  & \verb`Writing user certificate for client to file ...` \\
\Clunk[MK304]  & \verb`The user (i.e. client) certificate should be installed in all monitors.` \\
\Clunk[MK305]  & \verb`Current owner is nut:nut with permissions 0o644.` \\
\end{LinePrinter}
\end{center}

\li Ensure that the private key and the root certificate are properly
protected.  Only root and the user designated to run \upsd\ should
have access to the private key.  No-one else.

The root certificate is given restrictive permissions \texttt{600}.
If you attempt to run the script a second time it may well refuse if
there is already a root certificate at the same address with such
restrictive permissions.  You have to remove the old root certificate
yourself as user root.  Take care!

The user (i.e.\ the client) certificate is given permissions
\texttt{644}.

\li Transfer the user certificate to the machine(s) running the
Management Daemon, e.g.\ \upsmon.  Check that ownership and
permissions are correct on the destination machine.

\eol

%\vspace*{\fill}

%\begin{center}
%   \epsfig{file=UPS-1.jpg, height=36mm}
%\end{center}

%\vspace*{\fill}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage 
\newcolumn
\section{\Hsep\ Encrypted connections}\label{section:SSL}

\textsl{The configurations we have seen so far assume that the
  connection between the NUT client and the NUT server is either in
  the same machine or over a local, well protected network.  The
  client's password is transmitted in clear text to the server.  This
  may be a reasonable risk locally, but is not acceptable if client
  and server are connected by a public network or by a network deemed
  to be at risk.  This chapter looks at the technique for encrypting
  the traffic between client and server made possible by TLS 1.3
  support in NUT 2.8.0.}

\textsl{Chapter \ref{section:shims} discusses the use of TLS shims to
  provide the same encryption for NUT 2.7.4.}

\vspace{10mm}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=remote.pdf,width=1.2\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{Encrypted connection to remote server.\label{fig:SSL}}
\end{figure}

\vspace{10mm}

See chapter \ref{section:TLS.intro} for a very short introduction to
the quagmire of technical terms many of which are confusing or
incorrectly used.

This chapter will continue the habit of chapter \ref{section:big} of
referring to the server to which the UPS is connected as \gold\ and
the management client as \mgmt.

\newcolumn
\subsection{\Hsep\ Additional configuration files}\label{section:addfiles}

In addition to the configuration files discussed in previous chapters,
the following configuration files are also needed for encrypted
communication between remote NUT server \gold\ and management client
\mgmt.

\subsubsection{\Hsep\ In the remote server ``gold''}\label{section:TLSgoldconf}

\gold: Add the following lines to \upsdconf.  See \NUTman{upsd.conf}

\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk         & \verb`# upsd.conf` \\
\Clunk         & \verb`...` \\
\Clunk[UD001]  & \verb`DISABLE_WEAK_SSL true` \\
\Clunk[UD002]  & \verb`CERTFILE /etc/nut/titan.cert.pem` \\
\end{LinePrinter}
\end{center}

Line \ref{UD001} prevents use of insecure early versions of SSL/TLS by
restricting \upsd\ to use TLSv1.2 or better.

On line \ref{UD002} the \upsd\ daemon access control \upsdconf\ needs
the private key generated by \mkNUTcert.  The
\texttt{CERTFILE}\footnote{The name ``\texttt{CERTFILE}'' is a poor
choice since it is a private key not a public key.  A name such as
``\texttt{KEYFILE}'' would have been better.  Normally it is public
keys that are referred to as ``certificates''.}  declaration declares
the file containing the root certificate, i.e.\ the private key and
the certificate in PEM format.  See chapter \ref{section:privatekeycert}.

\subsubsection{\Hsep\ In each management client ``mgmt''}\label{section:TLSmgmtconf}

\mgmt: Add the following lines to \upsmonconf.  See \NUTman{upsmon.conf}

\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk         & \verb`# upsmon.conf` \\
\Clunk         & \verb`...` \\
\Clunk[UD011]  & \verb`CERTVERIFY 1` \\
\Clunk[UD012]  & \verb`CERTPATH /etc/nut/titan-client.cert.pem` \\
\end{LinePrinter}
\end{center}

Line \ref{UD011} makes \upsmon\ verify all connections with
certificates.  Without this, there is no guarantee that the \upsd\ is
the right host. Enabling this greatly reduces the risk of
man-in-the-middle attacks. This effectively forces the use of SSL, so
don’t use this unless all of your \upsd\ hosts are ready for SSL and
have their certificates in order.

In line \ref{UD012} \texttt{CERTPATH} points to a file containing a
certificate in PEM format, used to verify the server certificate
presented by the \upsd\ server.



\newcolumn
\subsection{\Hsep\ Debugging: Sniffing port 3493}\label{section:SSL.sniff}

Testing is essential to achieve the required level of security, and a
key part of this testing is sniffing the network to ensure that the
connections to port \IANAnut\ on the NUT server \gold\ are indeed encrypted.

We use tcpdump on Debian for this testing.  Other network sniffing
software is available.  The first test is to see the clear text nature
of the non-encrypted communication.

\ol

\li In the server, \gold, or in the management client \mgmt, run the
command \texttt{tcpdump -A port nut} as root.

\li In the management client \mgmt, stop \upsmon, and then restart it with
the command \texttt{systemctl restart nut-monitor.service}.

\li \texttt{tcpdump} will display the trace shown in figure
\ref{fig:tcpdump.1} which has been edited to make it easier to read.
Line \ref{SSL100} shows the client \mgmt\ attempting to begin an
encrypted session which is refused by server \gold\ on line
\ref{SSL101}.  \colorbox{yellow}{Line \ref{SSL102} shows the password
transmitted in clear text}.  \textsl{Let this be a warning to you.}

Lines \ref{SSL103}-\ref{SSL104}: Client \mgmt\ then makes a plain text
request every 5 seconds for the status of \UPSiii\ which the
server \gold\ then answers in plain text.

\begin{figure}[ht]
\begin{LinePrinter}[1.05\LinePrinterwidth]
\Clunk         & \verb`listening on wlan0, link-type EN10MB (Ethernet), capture size 262144 bytes` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut:` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656:` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut:` \\
\Clunk[SSL100] & \verb`IP mgmt.33656 > gold.nut: STARTTLS` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656:` \\
\Clunk[SSL101] & \verb`IP gold.nut > mgmt.33656: ERR FEATURE-NOT-CONFIGURED` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut:` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut: USERNAME upsmaster` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: OK` \\
\Clunk[SSL102] & \verb`IP mgmt.33656 > gold.nut:` \colorbox{yellow}{\texttt{PASSWORD sekret}} \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: OK` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut: LOGIN UPS-3` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: OK` \\
\Clunk         & \verb`IP mgmt.33656 > gold.nut: MASTER UPS-3` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: OK MASTER-GRANTED` \\
\Clunk[SSL103] & \verb`IP mgmt.33656 > gold.nut: GET VAR UPS-3 ups.status` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: VAR UPS-3 ups.status "OL"` \\
\Clunk         & \verb`IP mgmt.33658 > gold.nut:` \\ 
\Clunk[SSL104] & \verb`IP mgmt.33656 > gold.nut: GET VAR UPS-3 ups.status` \\
\Clunk         & \verb`IP gold.nut > mgmt.33656: VAR UPS-3 ups.status "OL"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{tcpdump of \texttt{systemctl start nut-monitor.service} without encryption.\label{fig:tcpdump.1}}
\end{figure}

\eol

\newcolumn
\subsection{\Hsep\ Testing the TLS setup}\label{section:SSL.test}

This test was done using a hybrid setup in which a version 2.8.0
\upsmon\ talks to a version 2.7.4 \upsd\ equipped with a shim
\upsdTLS.  As shown in figure \ref{fig:upsdTLS} \upsd\ listens on
customary port \IANAnut\ (nut), but the shim is listening on port
\IANAups.

First we trace the unencrypted traffic on port \IANAnut\ (nut).  The
trace has been edited to make it easier to read:

\begin{figure}[ht]
\begin{LinePrinter}[1.05\LinePrinterwidth]
\Clunk         & \verb`~ tcpdump -i any port 3493 -c 2 -A` \\
\Clunk         & ... \\
\Clunk         & \verb`IP mgmt.53634 > gold.nut: GET VAR UPS-3 ups.status` \\
\Clunk         & \verb`IP gold.nut > mgmt.53634: VAR UPS-3 ups.status "OL"` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Unencrypted traffic on port 3493 (nut).\label{fig:unencrypted}}
\end{figure}

And now the same message exchange but on port 401:

\begin{figure}[ht]
\begin{LinePrinter}[1.05\LinePrinterwidth]
\Clunk         & \verb`~ tcpdump -i any port 401 -c 2 -A` \\
\Clunk         & ... \\
\Clunk         & \verb`IP mgmt.41248 > gold.401: *..'5Q.W.2..U.&..!......i.^..-..j.....%..Q~` \\
\Clunk         & \verb`IP gold.401 > mgmt.41248: +6...&..u....6.F6.h.R................G5..1Y` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Encrypted traffic on port 401.\label{fig:encrypted}}
\end{figure}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}

%\input{Debian-NSS.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Shim daemons \upsdTLS\ and \upsmonTLS}\label{section:shims}

\textit{ The NUT project is now mature and proceeds at cautious speed.
  The SSL/TLS features of release 2.7.4 became obsolete and were
  deprecated before the next relase 2.8.0 appeared.  The
  \RFCshort\ proposed to address this security problem with a pair of
  TLS support shims sitting one beside \upsd\ and the other in the
  client system.}

\textit{This chapter describes an experimental implementation of the
  shims in of the scripts \upsdTLS\ and \upsmonTLS. The scripts and
  their SHA1 check sums may be downloaded from}
  \href{http://rogerprice.org/NUT}{http://{\allowbreak}rogerprice.org/{\allowbreak}NUT}

\begin{figure}[ht]
%\vspace{-6mm}
\begin{center}
   \epsfig{file=upsdTLS.pdf,width=1.2\LinePrinterwidth}
\end{center}
%\vspace{-6mm}
\caption{NUT 2.7.4 TLS support using shims \upsdTLS\ and \upsmonTLS.\label{fig:upsdTLS}}
\end{figure}

NUT 2.7.4 did not support the latest versions of TLS.  This prevented NUT
2.7.4 from using TLS since TLS strongly deprecates use of earlier versions
which are no longer considered secure.  To overcome this difficulty, Python
script \upsdTLS\ provides a shim to help \upsd\ work with the latest, and most
secure, versions of TLS.  \upsdTLS\ runs as a daemon alongside
\upsd\ receiving TLS encrypted traffic from it's companion shim \upsmonTLS\ or
from a TLS enabled client such as \UPSmon\ and passing on that traffic to
local \upsd\ using an unencrypted socket.  The script's status is
"experimental", and is intended for demonstration and experiment.  It must run
on the same machine as \upsd.  The license is GPL v3 or later at your choice,
with support in the \mailinglist.

%\vspace*{\fill}

%\newcolumn
\subsection{\Hsep\ Overview of Shim \upsdTLS}\label{section:upsdTLS}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk  & \verb`$ upsdTLS.py --help` \\
\Clunk  & \verb`usage: upsdTLS.py  [--backlog <integer>] [-D] [-h] [-l <file>] ` \\
\Clunk  & \verb`  [--listen <IPv4_address> <port_number>] [--listentimeout <float>]` \\
\Clunk  & \verb`  [--maxconn <integer>] [--PIDfile<file>] [-s <file>] [-u <user>]` \\
\Clunk  & \verb`  [--upsdport <integer>] [--upsdtimeout <float>] [-v]` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Command \texttt{upsdTLS.py -\/-help}}\label{fig:upsdTLShelp}
\end{figure}

The script has no configuration files, but has many options.  In
general few and in some simple cases none at all are needed.  To see
the options and their default values you can enter command
\texttt{upsdTLS.py -\/-help} .

Let's look at these optional arguments in more detail.   XXX

\begin{description}

\item[\texttt{-\/-backlog <integer>}] Maximum incoming message
  backlog, default value 5.  You should not usually need to change
  this.

\item[\texttt{-D, -\/-debug}] Increase the debugging level, may be
  repeated but then you get more than any human can read.  Debugging
  output is written into the NUT log file.

\item[\texttt{-h, -\/-help}]  Show this help message and exit

\item[\texttt{-\/-listen \textit{<IPv4\_address>}
    \textit{<port\_number>}}] \upsdTLS\ listens to (i.e.\ receives
  commands from) shim \upsmonTLS\ or a TLS enabled client on this
  interface and port, with the default \texttt{'127.0.0.1'
    \IANAups}. Temporarily, we squat IANA \IANAups/tcp (ups). Setting
  a port number < 1024 requires starting the daemon as root.

\item[\texttt{-\/-listentimeout \textit{<float>}}] Socket timeout for
  exchanges on the port specified by \texttt{-\/-listen}.  The default
  is 5.0 seconds.

\item[\texttt{-l \textit{<file>}, -\/-logfile \textit{<file>}}] The
  log file, with default \texttt{/var/log/NUT.log} . Progress and
  error messages and the copious stuff generated by option \texttt{-D}
  go into this file.  See chapter \ref{section:logrotate} for an
  extension to \texttt{logrotate} to cover this file.

\item[\texttt{-\/-maxconn \textit{<integer>}}] Maximum number of
  incoming connections, the default is \texttt{10}.  Strictly
  speaking, the maximum number of sockets the daemon process may have
  open, where \texttt{getconf OPEN\_MAX} gives system file maximum.
  You should not usually need to change this.

\item[\texttt{-\/-PIDfile \textit{<file>}}] The child PID is written
  into this file, for the greater pleasure of systemd.  The default
  for \upsdTLS\ is \texttt{/run/nut/{\allowbreak}upsdTLS.pid} . Do not
  change this unless you know what you are doing.  You should also
  review the systemd service unit.

\item[\texttt{-s \textit{<file>}, -\/-servercertfile \textit{<file>}}]
  The file path and file name of the server's private key.
  \upsdTLS\ tries to guess where to put things.  The default on Debian
  systems is
  \texttt{/etc/{\allowbreak}nut/\textit{mybox}.cert.pem}
  .  OpenSUSE sysadmins would probably use
  \texttt{/etc/{\allowbreak}ups/...}  See table \ref{fig:UD} for a
  list of possible directories.

\item[\texttt{-u \textit{<user>}, -\/-user \textit{<user>}}] After
  launch as root, run as this user.  \upsdTLS\ tries to guess the
  user. OpenSUSE admins would probably see \texttt{upsd}, whereas
  Debian admins would see \texttt{nut}.  See table \ref{fig:UD} for a
  list of possible users.

\item[\texttt{-\/-upsdport \textit{<integer>}}] Relay incoming
  commands to this \upsd\ port, and (no surprise) the default relay
  port to \upsd\ is \IANAnut.  \upsd\ is assumed to be running on
  llocalhost.

\item[\texttt{-\/-upsdtimeout \textit{<float>}}] Socket timeout for
  exchanges with \upsd. The default is 5.0 seconds.

\item[\texttt{-v, -\/-version}] Show program, Python and SSL/TLS
  versions, then exit.

\end{description}

%\newcolumn
\subsection{\Hsep\ Overview of Shim \upsmonTLS}\label{section:upsmonTLS}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk  & \verb`$ upsmonTLS.py --help` \\
\Clunk  & \verb`usage: upsmonTLS.py [--backlog <integer>] [-c <file>] [-D] [-h]` \\
\Clunk  & \verb`  [--listen <IPv4_address> <port_number>] [--listentimeout <float>]` \\
\Clunk  & \verb`  [-l <file>] [--maxconn <integer>] [--PIDfile<file>]` \\
\Clunk  & \verb`  [-u <user>] [--upsdname <domain>] [--upsdport <integer>]` \\
\Clunk  & \verb`  [--upsdtimeout <float>] [-v]` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Command \texttt{upsmonTLS.py -\/-help}}.\label{fig:upsmonTLShelp}
\end{figure}

The script has no configuration files, but lots of options.  In
general few and in some simple cases none at all are needed.  To see
the options and their default values you can enter command
\texttt{upsmonTLS.py -\/-help} .

Let's look at these optional arguments in more detail.  

\begin{description}

\item[\texttt{-\/-backlog <integer>}] Maximum incoming message
  backlog, default value 5.  You should not usually need to change
  this.

\item[\texttt{-c \textit{<file>}, -\/-clientcertfile \textit{<file>}}]
  The file path and file name of the client's certificate (public
  key).  \upsmonTLS\ tries to guess where to put things.  The default
  on Debian systems is
  \texttt{/etc/{\allowbreak}nut/\textit{mybox}-client.cert.pem}
  .  OpenSUSE sysadmins would probably use
  \texttt{/etc/{\allowbreak}ups/...}  See table \ref{fig:UD} for a
  list of possible directories.

\item[\texttt{-D, -\/-debug}] Increase the debugging level, may be
  repeated but then you get more than any human can read.  Debugging
  output is written into the NUT log file.

\item[\texttt{-h, -\/-help}]  Show this help message and exit

\item[\texttt{-\/-listen \textit{<IPv4\_address>}}]
  \upsmonTLS\ listens to the client such as \upsmon\ or \upsc\ on this
  interface and port, with the default \texttt{'127.0.0.1' \IANAnut}.

\item[\texttt{-\/-listentimeout \textit{<float>}}] Socket timeout for
  exchanges on the port specified by \texttt{-\/-listen}.  The default
  is 5.0 seconds.

\item[\texttt{-l \textit{<file>}, -\/-logfile \textit{<file>}}] The
  log file, with default \texttt{/var/log/NUT.log} . Progress and
  error messages and the copious stuff generated by option \texttt{-D}
  go into this file.  See chapter \ref{section:logrotate} for an
  extension to \texttt{logrotate} to cover this file.

\item[\texttt{-\/-maxconn \textit{<integer>}}] Maximum number of
  incoming connections, the default is \texttt{10}.  Strictly
  speaking, the maximum number of sockets the daemon process may have
  open, where \texttt{getconf OPEN\_MAX} gives system file maximum.
  You should not usually need to change this.

\item[\texttt{-\/-PIDfile \textit{<file>}}] The child PID is written
  into this file, for the continuing pleasure of systemd.  The default
  for \upsmonTLS\ is \texttt{/run/nut/{\allowbreak}upsmonTLS.pid} Do
  not change this unless you know what you are doing.  You should also
  review the systemd service unit.

\item[\texttt{-u \textit{<user>}, -\/-user \textit{<user>}}] After
  launch as root, run as this user.  \upsdTLS\ tries to guess the
  user. OpenSUSE admins would probably see \texttt{upsd}, whereas
  Debian admins would see \texttt{nut}.  See table \ref{fig:UD} for a
  list of possible users.

\item[\texttt{-\/-upsdname \textit{<domain>}}] Relay incoming commands
  from the client to the system running the shim \upsdTLS.  For
  example \texttt{-\/-updsname "bigserver.example.com"}. The default
  name is \texttt{localhost}.

\item[\texttt{-\/-upsdport \textit{<integer>}}] Relay incoming
  commands from \upsmon, \upsc, etc.\ to this upsd/shim port. The
  default relay port for \upsmonTLS\ is \IANAups\ which the companion
  script \upsdTLS\ listens to by default.  Temporarily, we squat IANA
  \IANAups/tcp (ups). Setting a port number < 1024 requires starting
  the daemon as root.
  
\item[\texttt{-\/-upsdtimeout \textit{<float>}}] Socket timeout for
  exchanges with \upsd. The default is 5.0 seconds.

\item[\texttt{-v, -\/-version}] Show program, Python and SSL/TLS
  versions, then exit.

\end{description}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ Summary of shims \upsdTLS\ and \upsmonTLS}\label{section:shimsummary}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\multicolumn{2}{|c|}{\textbf{\upsdTLS\ and \upsmonTLS}} \\ \hline\hline
\texttt{-\/-backlog \textit{<integer>}}           & 5  \\ \hline
\texttt{-\/-debug}                                &    \\ \hline
\texttt{-\/-help}                                 &    \\ \hline
\texttt{-\/-listentimeout \textit{<float>}}       & 5.0 secs   \\ \hline
\texttt{-\/-logfile \textit{<file>}}              & \texttt{/var/log/NUT.log}  \\ \hline
\texttt{-\/-maxconn \textit{<integer>}}           & 10  \\ \hline
\texttt{-\/-upsdtimeout \textit{<float>}}         & 5.0 secs   \\ \hline
\texttt{-\/-user \textit{<user>}}                 & Debian: \texttt{nut}   \\ \hline
\texttt{-\/-version}                              & \\ \hline\hline

\multicolumn{2}{|c|}{\textbf{\upsdTLS\ only}}     \\ \hline\hline
\texttt{-\/-listen \textit{<IPv4> <port>}}        & 127.0.0.1 \IANAups  \\ \hline
\texttt{-\/-PIDfile \textit{<file>}}              & \texttt{/run/nut/upsdTLS.pid}  \\ \hline
\texttt{-\/-servercertfile \textit{<file>}}       & \texttt{/etc/nut/\textit{mybox}.cert.pem}  \\ \hline
\texttt{-\/-upsdport \textit{<port>}}             & \IANAnut\  \\ \hline\hline

\multicolumn{2}{|c|}{\textbf{\upsmonTLS\ only}}   \\ \hline\hline
\texttt{-\/-clientcertfile \textit{<file>}}       & \texttt{/etc/nut/\textit{mybox}-client.cert.pem}  \\ \hline
\texttt{-\/-listen \textit{<IPv4> <port>}}        & 127.0.0.1 \IANAnut  \\ \hline
\texttt{-\/-PIDfile \textit{<file>}}              & \texttt{/run/nut/upsmonTLS.pid}  \\ \hline
\texttt{-\/-upsdname \textit{<domain>}}           & \texttt{localhost} \\ \hline
\texttt{-\/-upsdport \textit{<port>}}             & \IANAups\  \\ \hline

\end{tabular}
\caption{Summary of \upsdTLS\ and \upsmonTLS\ options and default values.\label{fig:shimsummary}}
\end{center}
\end{figure}

%\newcolumn
\subsection{\Hsep\ Running the shims \upsdTLS\ and \upsmonTLS}\label{section:UPrun}

The daemons \upsdTLS\ and \upsmonTLS\ usually start with user root and fork to
run as the same user as \upsd.

If you use systemd to manage your boxes, then you will need to create new
service units, since systemd is unable to start two forking services from the
same unit.  See \LINman{systemd.service}{5}.  There can only be one
\texttt{Type=forking} per unit.

In the box running \upsd\ create a new file by copying the service
unit file
\texttt{/usr/lib/{\allowbreak}systemd/{\allowbreak}system/{\allowbreak}nut-server.{\allowbreak}service}
to
\texttt{/etc/systemd/{\allowbreak}system/{\allowbreak}nut-py-server-shim.{\allowbreak}service}
and modify the new file as shown in figure \ref{fig:shimstart1}.
where lines \ref{UP011}-\ref{UP013} and \ref{UP015}-\ref{UP016} have
been changed.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[UP010]  & \verb`[Unit]` \\
\Clunk[UP011]  & \verb`Description=Network UPS Tools - nut-server TLS shim support daemon` \\
\Clunk[UP012]  & \verb`After=local-fs.target network.target nut-server.service` \\
\Clunk[UP013]  & \verb`Before=nut-py-client.service` \\
               & \\
\Clunk[UP014]  & \verb`[Service]` \\
\Clunk[UP015]  & \verb`ExecStart=/usr/sbin/upsdTLS.py` \\
\Clunk[UP016]  & \verb`PIDfile=/run/nut/upsdTLS.pid` \\
\Clunk[UP017]  & \verb`Type=forking` \\
               & \\
\Clunk[UP018]  & \verb`[Install]` \\
\Clunk[UP019]  & \verb`WantedBy=multi-user.target` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{systemd service unit \texttt{nut-py-server-shim.service} for \upsdTLS.}\label{fig:shimstart1}
\end{figure}

\newcolumn

In the box running \upsmon\ copy the service unit file
\texttt{/usr/lib/{\allowbreak}systemd/{\allowbreak}system/{\allowbreak}nut-monitor.{\allowbreak}service}
to
\texttt{/etc/systemd/{\allowbreak}system/{\allowbreak}nut-py-client-shim.{\allowbreak}service}
and modify the new file as shown in figure \ref{fig:shimstart2}
where lines \ref{UP021}-\ref{UP023} and \ref{UP025}-\ref{UP026} have
been changed.

The \texttt{PIDfile} declarations are there to help systemd find the
daemon since \upsdTLS\ and \upsmonTLS\ do not keep the parent process
running when they fork.  Note that systemd service units in
\texttt{/etc} take precedence over those in \texttt{/usr/lib}.  See
\LINman{systemd.unit}{5}.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[UP020]  & \verb`[Unit]` \\
\Clunk[UP021]  & \verb`Description=Network UPS Tools - TLS shim support daemon for nut clients` \\
\Clunk[UP022]  & \verb`After=local-fs.target network.target nut-server.service\` \\
               & \verb`      nut-py-server-shim.service` \\
\Clunk[UP023]  & \verb`Before=nut-client.service` \\
               & \\
\Clunk[UP024]  & \verb`[Service]` \\
\Clunk[UP025]  & \verb`ExecStart=/usr/sbin/upsmonTLS.py` \\
\Clunk[UP026]  & \verb`PIDfile=/run/nut/upsmonTLS.pid` \\
\Clunk[UP027]  & \verb`Type=forking` \\
               & \\
\Clunk[UP028]  & \verb`[Install]` \\
\Clunk[UP029]  & \verb`WantedBy=multi-user.target` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{systemd service unit \texttt{nut-py-client-shim.service} for \upsmonTLS.}\label{fig:shimstart2}
\end{figure}

You may choose to place the \upsdTLS\ and \upsmonTLS\ scripts in directory
\texttt{/usr/sbin} or make
\texttt{/usr/{\allowbreak}sbin/{\allowbreak}upsdTLS.py} and
\texttt{/usr/{\allowbreak}sbin/{\allowbreak}upsmonTLS.py} links to wherever
you put the Python scripts.  After you have made the changes, you should run
the command \texttt{systemctl daemon-reload} See \LINman{systemctl}{1}.

\newcolumn
\subsubsection{\Hsep\ Enabling the shims \upsdTLS\ and \upsmonTLS}\label{section:UPenable}

Before running the shims the first time, you will need to run the
command
\begin{verbatim}
systemctl enable nut-py-server-shim.service nut-py-client-shim.service
\end{verbatim}

The following \texttt{systemctl} commands will be of use to you:

\ul

\li \texttt{systemctl daemon-reload} \\
to make any changes to the service unit available to systemd.

\li \texttt{systemctl enable nut-py-server-shim.service} \\
\texttt{systemctl enable nut-py-client-shim.service} \\
to make the daemons
\upsdTLS\ and \upsmonTLS\ operational and ``startable''.

\li \texttt{systemctl start nut-py-server-shim.service} \\
\texttt{systemctl start nut-py-client-shim.service} \\
to start \upsdTLS\ and
\upsmonTLS.  Note that this will not erase the log file.  If you want to clear
the log file then you need to do that yourself.  See also chapter
\ref{section:logrotate} for a discussion of log rotation.

\li \texttt{systemctl status nut-py-server-shim.service} \\
\texttt{systemctl status nut-py-client-shim.service} \\
to see the current status of the shims.

\li \texttt{systemctl stop nut-py-server-shim.service} \\
\texttt{systemctl stop nut-py-client-shim.service} \\
to stop \upsdTLS\ and \upsmonTLS.

\eul

\upsdTLS\ and \upsmonTLS\ should start automatically when the system starts,
but they can also be stopped and started manually with the \texttt{systemctl}
commands.

Serious errors will prevent the shims from starting and you can read about
them in the NUT log and in the system log.  After starting the shims, check
the NUT log for warnings and other error messages.

\newcolumn
\subsubsection{\Hsep\ Listing the systemd activity}\label{section:UPlist}

During the debugging of the shims, I saw a summary of the NUT systemd
service unit activity on a Debian 11 (NUT 2.7.4) system with the
command:

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[UP039]  & \verb`root@titan ~ systemctl list-unit-files | grep -i -E "nut|UPS|VENDOR"` \\
\Clunk         & \verb`UNIT FILE                                 STATE           VENDOR PRESET` \\
\Clunk[UP040]  & \verb`nut-driver-enumerator.path                disabled        enabled` \\
\Clunk[UP041]  & \verb`nut-client.service                        alias           -` \\
\Clunk[UP042]  & \verb`nut-delayed-ups-shutdown.service          enabled         enabled` \\
\Clunk[UP043]  & \verb`nut-driver-enumerator.service             disabled        enabled` \\
\Clunk[UP044]  & \verb`nut-driver.service                        static          -` \\
\Clunk[UP045]  & \verb`nut-driver@.service                       disabled        enabled` \\
\Clunk[UP046]  & \verb`nut-monitor.service                       disabled        enabled` \\
\Clunk[UP047]  & \verb`nut-py-client-shim.service                enabled         enabled` \\
\Clunk[UP048]  & \verb`nut-py-monitor.service                    enabled         enabled` \\
\Clunk[UP049]  & \verb`nut-py-server-shim.service                enabled         enabled` \\
\Clunk[UP050]  & \verb`nut-server.service                        enabled         enabled` \\
\Clunk[UP051]  & \verb`ups-monitor.service                       masked          enabled` \\
\Clunk[UP052]  & \verb`nut-driver.target                         disabled        enabled` \\
\Clunk[UP053]  & \verb`nut.target                                disabled        enabled` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Example of systemd service unit activity for NUT.}\label{fig:NUTsummary}
\end{figure}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                            P A R T  3                                  %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Dont forget the \setcounter in the Appendices

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                           A P P E N D I C E S                          %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\appendix

% Layout for the body.  See the LaTeX Companion, p.96.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[Appendices]{Appendices}                                % \lhead[left-header-even]{left-header-odd}
\chead[ConfigExamples \Version]%
      {ConfigExamples \Version}                               % \chead[centre-header-even]{centre-header-odd}
\rhead[\LaTeX\ run \isodate]{\LaTeX\ run \isodate}            % \rhead[right-header-even]{right-header-odd}
\lfoot[]{}                                                    % \lfoot[left-footer-even]{left-footer-odd}
\cfoot[\fancyplain{}{Page \thepage\ of \pageref{LastPage}}]%
      {\fancyplain{}{Page \thepage\ of \pageref{LastPage}}}   % \cfoot[centre-footer-even]{centre-footer-odd}
\rfoot[]{}                                                    % \rfoot[right-footer-even]{right-footer-odd}

% Number sections in the style B, B.2, B.2.3
\renewcommand{\thesection}{\Alph{section}}
\renewcommand{\thesubsection}{\Alph{section}.\arabic{subsection}}
\renewcommand{\thesubsubsection}{\Alph{section}.\arabic{subsection}.\arabic{subsubsection}}

%\setcounter{section}{29}
\begin{center}
\addtocontents{toc}{\protect\vspace{3mm}}
\part[\hspace{\fill}\textsf{Appendices}\hspace{\fill}]{}\label{part:appendices}
\addtocontents{toc}{\protect\vspace{3mm}}
\vspace{8mm}
\scalebox{1.0}[1.2]{\textsf{\Huge{Appendices}}}
%\vspace{16mm}
\end{center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
%\newcolumn
%\vspace{-15mm}
\section{\Hsep\ Starting NUT}\label{section:Start}

\begin{wrapfigure}{l}{0.5\LinePrinterwidth}
\vspace{-9mm}
\begin{center}
\begin{LinePrinter}[0.4\LinePrinterwidth]
\Clunk[LP920]  & \verb`# nut.conf` \\
\Clunk         & \verb`# No spaces around the "="` \\
\Clunk[LP921]  & \verb`MODE=standalone` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \nutconf.\label{fig:Start}}
\end{wrapfigure}

\textsl{This chapter discusses the techniques used to start the NUT
  software.  Each distribution has it's own view of how this is to be
  done, so you should review the systemd service units involved and
  the scripts that they call.}

The NUT software contains several daemons which need to be started to
offer the promised NUT service.  These daemons are shown in the table
in figure \ref{fig:daemons}.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|p{0.52\LinePrinterwidth}|}
\hline \textbf{Daemon} & \textbf{systemd service unit} &
\textbf{Notes} \\ \hline\hline
\upsd       & \texttt{nut-server.service}
            & The central daemon which maintains the abstracted view 
              of the UPS units. \\ \hline
\driver     & \texttt{nut-driver.service}
            & One or more driver daemons as specified in file \upsconf.  This
              service unit is started automatically by systemd whenever
              \upsd\ starts. The driver needs more time to get started?, see
              \href{https://alioth-lists.debian.net/pipermail/nut-upsuser/2022-January/012653.html}%
                   {Manuel Wolfshant's post in the NUT mailing list}. \\ \hline
\upsmon     & \texttt{nut-monitor.service}
            & The monitor daemon specifies what is to be done for 
              \hyperref[fig:NOTIFYevents]{NOTIFY events}. \\ \hline
\upssched   & \textit{none}
            & For activity such as the heartbeat, the timed action daemon 
              is called by the \upsschedcmd\ script which is specified 
              by the \texttt{NOTIFYCMD} command in \upsmonconf.  \\ \hline\hline
\multicolumn{3}{|c|}{\textit{TLS Shim daemons defined in Part \ref{part:shim}}} \\ \hline
\upsdTLS    & \texttt{nut-py-server-shim.service}
            & The shim daemon placed in front of \upsd\ 2.7.4 to provide TLS support. \\ \hline
\upsmonTLS  & \texttt{nut-py-monitor-shim.service}
            & The shim placed in front of \upsmon\ 2.7.4 to provide TLS support. \\ \hline\hline
% \multicolumn{3}{|c|}{\textit{Experimental daemon defined in Part \ref{part:UPSmon}}} \\ \hline
% \UPSmon     & \texttt{nut-py-monitor.service}
%             & An experimental replacement for the monitor daemon \upsmon\ which
%               includes TLS support. \\ \hline
\end{tabular}
\caption{Daemons used by NUT.\label{fig:daemons}}
\end{center}
\end{figure}
  
Configuration file \nutconf\ specifies which of these daemons the operating
system should start, but distributions often ignore the file.  The
distribution choice is normally correct for a standalone workstation protected
by a single UPS, but for more complex situations, you need to review what your
distribution does.  See chapter \refpage{section:nutconf.big} and \NUTman{nut.conf}.

Strictly speaking, this file is not for NUT, but for the process which starts
NUT.  The initialization process is expected to source this file to know which
parts of nut are to be started.  Some distributions, e.g.\ openSUSE, ignore
\nutconf\ and start the three NUT layers \driver, \upsd\ and \upsmon.  They
assume that \texttt{MODE=standalone}.  Note that there is no space around the
``\texttt{=}'' since it is assumed that shell scripts such as Debian's
\texttt{/sbin/upsd} source this file.

The possible \texttt{MODE} values are:

\ul

\li \texttt{MODE=none} \quad Indicates that NUT should not get started
automatically, possibly because it is not configured or that an Integrated
Power Management or some external system, is used to start up the NUT
components. If you enable \texttt{nut-server.service} Debian \footnote{See
script \texttt{/sbin/upsd}.} will display the message:
\vspace{-3mm}
\begin{quotation}
\emph{upsd disabled, please adjust the configuration to your needs.
Then set MODE to a suitable value in /etc/nut/nut.conf to enable it.}
\end{quotation}
\vspace{-3mm}

Enabling \texttt{nut-monitor.service} will produce a similar
message\footnote{See script \texttt{/sbin/upsmon}.}.

\li \texttt{MODE=standalone} \quad This is the most common situation in which
line \ref{LP921} in figure \ref{fig:Start} declares that NUT should be
started in the ``\texttt{standalone}'' mode suitable for a local only
configuration, with 1 UPS protecting the local system. This implies starting
the 3 NUT layers, \driver, \upsd\ and \upsmon\, and reading their
configuration files.

\li \texttt{MODE=netserver} \quad Like the standalone configuration, but may
possibly need one or more specific \texttt{LISTEN} directive(s) in
\upsdconf. Since this \texttt{MODE} is open to the network, a special care
should be applied to security concerns.  Debian accepts starting \upsmon\ in
this mode.

\li \texttt{MODE=netclient} \quad When only \upsmon\ is required, possibly
because there are other hosts that are more closely attached to the UPS, the
\texttt{MODE} should be set to netclient.  If you enable Debian's systemd
service unit \texttt{nut-server.service} with this mode, then you will get the
same message as for \texttt{MODE=none}.

\eul

However these alternate modes are merely wishful thinking if your distribution
ignores file \nutconf.  There are other options, see \NUTman{nut.conf}.

%\vspace*{\fill}

%\begin{center}
%   \epsfig{file=UPS-4.jpg, height=36mm}
%\end{center}

%\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Stopping NUT}\label{section:Stop}

\subsection{\Hsep\ Delayed UPS shutdown with NUT script}\label{section:delayedUPSshutdown.script}

We saw in chapter \refpage{section:server}, line \ref{LP203}, that the
\upsmonconf\ \texttt{SHUTDOWNCMD} directive specifies the command to be used
to shut down the system, but what about the UPS which must keep supplying
power while the system shuts down?  Does the UPS also shut down?, and if so,
how?

Chapter \refpage{section:delayedUPSshutdown} \textit{``The shutdown
  story for a simple server''} explains that somewhere in your
distribution, as part of the system shutdown process, there needs to
be an action to send a message to the UPS to tell it that some time
later, it too will shut down.  The notion of ``shutdown'' for a UPS
unit is subtle.  What shuts down is usually the supply of power to the
power outlets.  The UPS unit cuts off the equipment for which it
provides battery backup.  When this happens you may hear the audible
``clunk'' of the relays.  The unit may also act as a power strip with
surge protection, but those outlets are not covered by the protection
afforded by the battery.

Note that the UPS does not shutdown at the same time as the system it
protects.  The UPS shutdown is \textbf{delayed}.  By default the delay is 20
seconds.  See line \refpage{LP104} if you want to change this.

The delayed UPS shutdown command may be from a shell script or a systemd
service unit, but in all cases the key element is the command
\texttt{upsdrvctl shutdown}.

The NUT project provides a sample script, which is to be placed in a directory
of things to be done at the end of the system shutdown.  This depends on the
distribution.  

The Debian 11 distribution places the delayed shutdown script provided by NUT
and shown in figure \ref{fig:delayedUPSshutdown.script} in file
\texttt{/usr{\allowbreak}/lib{\allowbreak}/systemd{\allowbreak}/system-shutdown{\allowbreak}/nutshutdown}\ .
The openSUSE distribution does the same.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP922]  & \verb`#!/bin/sh` \\
\Clunk[LP923]  & \verb`/usr/sbin/upsmon -K >/dev/null 2>&1 && /usr/sbin/upsdrvctl shutdown` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{UPS shutdown script \nutshutdown.\label{fig:delayedUPSshutdown.script}}
\end{figure}

On line \ref{LP923} the call to \upsmon\ with option \texttt{-K} checks the
\texttt{POWERDOWNFLAG} defined by line \ref{LP209}.  The \upsmon\ daemon
creates this file when running in primary (master) mode whenever the UPS needs
to be powered off.  See \NUTman{upsmon.conf} for details.  If the check
succeeds, we are free to call \upsdrvctl\ to shut down the UPS's.  Note that
if you have multiple UPS's, the command \texttt{ upsdrvctl shutdown} will shut
them all down.  If you have say three UPS's, \UPSi, \UPSii\ and \UPSiii, and
you want to shut down just \UPSii\ and \UPSiii, then you should specify those
UPS's as shown in line \ref{LP925}.  See also \NUTman{upsdrvctl}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.95\LinePrinterwidth]
\Clunk[LP924]  & \verb`#!/bin/sh` \\
\Clunk[LP925]  & \verb`/usr/sbin/upsmon -K >/dev/null 2>&1\` \\
               & \verb`    && /usr/sbin/upsdrvctl shutdown UPS-2\` \\
               & \verb`    && /usr/sbin/upsdrvctl shutdown UPS-3` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{UPS shutdown script \nutshutdown\ for 2 of 3 UPS's.\label{fig:delayedUPSshutdown.2.script}}
\end{figure}

%\newcolumn
\subsection{\Hsep\ Delayed UPS shutdown with a systemd service unit}\label{section:delayedUPSshutdown.unit}

The script provided by the NUT project in chapter
\ref{section:delayedUPSshutdown.script} is executed very late in the shutdown
sequence, when it is no longer possible to log the action.  If you think that
power management is a critical operation and that all critical operations
should be logged, then you will need to call for the delayed UPS shutdown
earlier in the system shutdown sequence when logging is still possible.  This
can be done using the systemd service unit shown in figure
\ref{fig:delayedUPSshutdown.unit}.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP930]  & \verb`# nut-delayed-ups-shutdown.service` \\
\Clunk[LP931]  & \verb`[Unit]` \\
\Clunk[LP932]  & \verb`  Description=Initiate delayed UPS shutdown` \\
\Clunk[LP933]  & \verb`  Before=umount.target` \\
\Clunk[LP934]  & \verb`  DefaultDependencies=no` \\
\Clunk[LP935]  & \verb`[Service]` \\
\Clunk[LP936]  & \verb`  Type=oneshot` \\
\Clunk[LP937]  & \begin{minipage}[t]{0.85\LinePrinterwidth}
                 \begin{verbatim}
  ExecStart=/usr/bin/logger -t nut-delayed-ups-shutdown\
                            "upsdrvctl shutting down UPS"\end{verbatim}
                 \end{minipage} \\
\Clunk[LP938]  & \verb`  ExecStart=/usr/sbin/upsdrvctl shutdown   # Debian` \\
\Clunk[LP939]  & \verb`[Install]` \\
\Clunk[LP940]  & \verb`  WantedBy=final.target` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{UPS shutdown service unit \nutshutdownservice.\label{fig:delayedUPSshutdown.unit}}
\end{figure}

The \texttt{ExecStart} directive on line \ref{LP938} will shutdown
\footnote{The \upsdrvctl\ program is normally a frontend to the
  drivers, but in the case of the \texttt{shutdown} option
  \upsdrvctl\ does not use the existing driver; it creates a new
  driver for itself.}  all the UPS units managed by this system.  The
code given is for Debian: other distributions put
\upsdrvctl\ elsewhere.  If you have say three UPS's, \UPSi,
\UPSii\ and \UPSiii, and you want to shut down just \UPSii\ and
\UPSiii, then instead of line \ref{LP938} you should specify the
required UPS's as shown in lines \ref{LP941}-\ref{LP942}.

\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LP941]  & \verb`  ExecStart=/sbin/upsdrvctl shutdown UPS-2   # Debian` \\
\Clunk[LP942]  & \verb`  ExecStart=/sbin/upsdrvctl shutdown UPS-3` \\
\end{LinePrinter}

Note that this service unit does not perform the \texttt{upsmon -K}
test for the \texttt{POWERDOWNFLAG}.

The position of this service unit may vary from one distribution to
another, see
\href{https://www.freedesktop.org/software/systemd/man/systemd.unit.html}{section
  ``unit file load path'' in \LINman{systemd.unit}{5}}.  For example
in the openSUSE and Debian distributions,
\texttt{/etc{\allowbreak}/systemd{\allowbreak}/system} is for a user's
scripts, and
\texttt{/usr{\allowbreak}/lib{\allowbreak}/systemd{\allowbreak}/system-shutdown}
is for system scripts.  You might use the
\texttt{/etc{\allowbreak}/systemd{\allowbreak}/system} directory if
your script is not part of an officially distributed product.

If you install or change this service unit, run command \texttt{systemctl
  -\/-system reenable
  /etc/{\allowbreak}systemd/{\allowbreak}system/{\allowbreak}nut-delayed-ups-shutdown{\allowbreak}.service} .
Maybe your distribution offers a graphical manager to do this.

For gory details see the systemd documentation.  There are over 200 man pages
starting with \href{https://www.freedesktop.org/software/systemd/man/}{an
  index}.  For details of the directories used, see 
\href{https://www.freedesktop.org/software/systemd/man/systemd.unit.html}{section
  ``unit file load path'' in \texttt{man systemd.unit}}.

%\vspace*{\fill}
%\begin{center}\rule{\LinePrinterwidth}{0.5mm}\end{center}

%\vspace*{\fill}

%\begin{center}
%   \epsfig{file=UPS-3.jpg, height=36mm}
%\end{center}

%\vspace*{\fill}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
%\newcolumn
\section{\Hsep\ Users and Directories for NUT}\label{section:UD}

NUT normally runs as a non-root user, however the user varies from one
distribution to another.  Table \ref{fig:UD} shows a list of users for
a range of distributions.  Table \ref{fig:UD} also shows the
directories used by different distributions for configuration files
such as \upsdconf.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|l|l|l|}
\hline
\textbf{Distribution} & \textbf{ID} & \textbf{User:} & \textbf{Directory}            & \textbf{ID source} \\
            &                      & \textbf{Group}  &                               & \\ \hline\hline
Aix         & \texttt{aix}         & \texttt{nut} ?  & \texttt{/etc/nut/} ?          & \texttt{uname -a} \\ \hline
Amazon      & \texttt{amzn}        & \texttt{nut}    & \texttt{/etc/ups/} ?          & \texttt{/etc/os-release} \\ \hline
Arch        & \texttt{arch}        & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
CentOS      & \texttt{centos}      & \texttt{nut}    & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
Apple       & \texttt{darwin}      & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{uname -a} \\ \hline
Debian      & \texttt{debian}      & \texttt{nut:nut}& \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
Fedora      & \texttt{fedora}      & \texttt{nut}    & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
FreeBSD     & \texttt{freebsd}     & \texttt{uucp}   & \texttt{/usr/local/etc/nut/}  & \texttt{uname -a} \\ \hline
Gentoo      & \texttt{gentoo}      & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/gentoo-release} \\ \hline
HP-UX       & \texttt{hpux}        & \texttt{nut} ?  & \texttt{/etc/nut/} ?          & \texttt{uname -a} \\ \hline
IPFire      & \texttt{ipfire}      & \texttt{nutmon} & \texttt{/etc/nut/}            & \texttt{uname -a} \\ \hline
Kali        & \texttt{kali}        & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
Mint        & \texttt{linuxmint}   & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
Apple       & \texttt{mac}         & \texttt{nut} ?  & \texttt{/etc/nut/} ?          & \texttt{uname -a} \\ \hline
Mageia      & \texttt{mageia}      & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
Manjaro     & \texttt{manjaro}     & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
NetBSD      & \texttt{netbsd}      & \texttt{nut} ?  & \texttt{/etc/nut/} ?          & \texttt{uname -a} \\ \hline
Oracle      & \texttt{ol}          & \texttt{nut}    & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
OpenBSD     & \texttt{openbsd}     & \texttt{ups (1)}& \texttt{/etc/nut/}            & \texttt{uname -a} \\ \hline
OpenIndiana & \texttt{openindiana} & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{uname -a} \\ \hline
OpenSUSE    & \texttt{opensuse}    & \texttt{upsd}   & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
Raspbian    & \texttt{raspbian}    & \texttt{nut}    & \texttt{
  /etc/nut/}            & \texttt{/etc/os-release} \\ \hline
Red Hat     & \texttt{rhel}        & \texttt{nut}    & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
Slackware   & \texttt{slackware}   & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline
SUSE        & \texttt{sles}        & \texttt{upsd}   & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
SUSE+SAP    & \texttt{sles\_sap}   & \texttt{upsd}   & \texttt{/etc/ups/}            & \texttt{/etc/os-release} \\ \hline
Synology    & \texttt{synology}    & \texttt{root} ? & \texttt{/usr/syno/etc/nut/}   & \texttt{uname -a} \\ \hline
Ubuntu      & \texttt{ubuntu}      & \texttt{nut}    & \texttt{/etc/nut/}            & \texttt{/etc/os-release} \\ \hline\hline
\multicolumn{5}{|c|}{\textsl{The editor will be very pleased to hear of errors or omissions in this table.}} \\ \hline
\end{tabular}
\caption{Users and directories for NUT.\label{fig:UD}}
\end{center}
\end{figure}

Notes: 
\ol

\li The OpenBSD user may be \texttt{\_ups} which is an OpenBSD
convention for identifying unprivileged users. Most OpenBSD add-on
software uses unprivileged usernames beginning with an underscore.

\li If NUT is built without specifying the user, then the user is
\texttt{nobody:nobody}.

\li FreeNAS identifies itself in \texttt{/etc/os-release} as FreeBSD.

\li The \href{https://wiki.ipfire.org/addons/nut}{IPFire wiki} suggests user
\texttt{nutmon} for \upsmon\ but makes no mention of \upsd.

\li OpenIndiana: historically, NUT was not included as a package in
OpenIndiana, and
\href{https://wiki.openindiana.org/oi/Network+UPS+Tools+(NUT)+and+NUT+Monitor}%
     {an OpenIndiana Wiki entry dated 2013} recommended user \texttt{ups} and
     directory \texttt{/opt/nut/etc/}.  The values in the table are taken from
     \href{https://github.com/OpenIndiana/oi-userland/blob/oi/hipster/components/sysutils/nut/files}%
          {OpenIndiana's current Github data for NUT}.

\eol

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Using \notifysend}\label{section:notifysend}

\textsl{The program ``wall'' used by NUT to put notifications in front of the
  users is now well past it's best-before date and hardly fit for purpose. It
  has not been internationalized, does not support accented letters or
  non-latin characters, and is ignored by popular desktop environments such as
  Xfce, Gnome and KDE.  It's apparent replacement \notifysend\ gives the
  impression that it has never been tested in any other than the simplest
  cases, and that it is not ready for industrial strength use.  Getting
  \notifysend\ to work with NUT is not immediately evident, so although
  \notifysend\ is not a part of NUT, we discuss this problem here.}

\begin{figure}[ht]
\begin{center}
   \epsfig{file=notification.jpg, height=15mm}
\end{center}
\vspace{-6mm}
\caption{Example of a notification.\label{fig:notification}}
\end{figure}

\subsection{\Hsep\ What's wrong with \notifysend?}\label{section:notifysend.intro}

The program \notifysend\ is part of a set of programs which implement
the Gnome
\href{https://specifications.freedesktop.org/notification-spec/latest/}{Desktop
  Notifications Specification}.  The introduction says:

\begin{quotation}
$\ll$ This is a draft standard for a desktop notifications service, through
  which applications can generate passive popups to notify the user in an
  asynchronous manner of events. ...  Example use cases include:

\ul
\li Scheduled alarm
\li Low disk space/\textbf{battery warnings} ... $\gg$
\eul
\end{quotation}

From this introduction it would seem that desktop notifications are exactly
what is needed to present \statuschange{\OL}{\OB} and
\statuschange{\OB}{\OB\ \LB} warnings to the users, but unfortunately, things
are not that simple.

Program \notifysend\ is a utility which feeds message objects to a
message server, such as \texttt{notifyd}.  Taking the Xfce desktop
environment as an example, Xfce provides it's message server called
\texttt{xfce4-notifyd}.  See \DEBman{xfce4-notifyd-config},
\DEBman{notify-send} and the Desktop Notifications
\href{https://specifications.freedesktop.org/notification-spec/latest/}{Specification}.
There is also an \texttt{xfce4-notifyd}
\href{https://docs.xfce.org/apps/notifyd/start}{web page}.

Experience shows that just calling \notifysend\ in the script
\upsschedcmd\ does not work.  The message simply disappears.  Closer
examination on the openSUSE distribution with command \texttt{ps -elf
  | grep ups} shows that if daemon \upsmon\ running as user ``upsd''
calls \notifysend\ to present a message, the notify daemon is launched
with the same userid ``upsd'' as the caller.  In Debian, NUT runs as
user ``nut'' and the notify daemon is launched with the name userid
``nut''.  \textit{Users such as ``upsd'' and ``nut'' do not have
  access to the desktop environment.}
 
If the caller is the \upsmon\ daemon which has no access to the
desktop environment, then neither will the corresponding notification
daemon.  This is surprising.  One would expect a design closer to that
of the printer daemon \texttt{cupsd} which runs permanently in the
background receiving files to be printed.  There is only one daemon
\texttt{cupsd} and that daemon isolates the user from needing to know
how to drive printers.

To get the message to show on the user's screen appears to require two
actions:

\ol
\li Give user ``upsd'' (``nut'' on Debian) the right to act as any user,
\li Search for logged in users, and for each user construct the user's
environment variable \texttt{DISPLAY}, and call utility \notifysend\ as that
user to notify the user.
\eol

\subsection{\Hsep\ Give user ``nut'' (``upsd'') the right to act as any user}\label{section:notifysend.sudoer}

To improve security in NUT, the \upsd\ and \upsmon\ daemons is not executed as
root, but rather as a non-root userid.  This userid is typically called
``nut'' or ``upsd''.  See table \ref{fig:UD} for a list of possible users.  We
will use the name ``nut''.  ``nut'' is not a regular user and does not have
the access to the X-server needed to display data.  This is a problem for the
notification service, which we now fix.

Add the following lines to the file \texttt{/etc/sudoers}

\begin{figure}[ht]
\begin{LinePrinter}[0.95   \LinePrinterwidth]
\Clunk[LP3600]  & \verb`# Host alias specification`\\
\Clunk[LP3601]  & \verb`Host_Alias LAN = 10.218.0/255.255.255.0,127.0.0.1,localhost,gold` \\
\Clunk          & \\
\Clunk[LP3602]  & \verb`nut  LAN = (ALL)  NOPASSWD:SETENV: /usr/bin/notify-send` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Modifications to file \texttt{/etc/sudoers}\label{fig:notify.sudoer}}
\end{figure}

Line \ref{LP3601} corresponds to the editor's system and should be adapted to
your setup.  

On line \ref{LP3602} the directive \texttt{SETENV:} is needed for openSUSE but
optional for Debian.

The file \texttt{/etc/sudoers} contains the following warning:
\begin{quotation}
\emph{This file MUST be edited with the 'visudo' command as root.  Failure to use
'visudo' may result in syntax or file permission errors that prevent sudo from
running.}
\end{quotation}

See \href{https://www.sudo.ws/man/1.8.13/sudoers.man.html}{\texttt{man
    sudoers}} and
\href{https://www.sudo.ws/man/1.8.13/visudo.man.html}{\texttt{man visudo}}.
The un-l33t do not have to use vi.  Luckily, the command
\texttt{VISUAL=/usr/{\allowbreak}bin/{\allowbreak}emacs visudo -f
  /etc/sudoers} also does the job.


\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ Search for and notify logged in users}\label{section:notifysend.user}

Figure \ref{fig:notifysendall} shows a Bash script \notifysendall\ which can
be used in place of \notifysend\ to send messages from \upsschedcmd\ to all
the X display users currently logged in.  Script \notifysendall\ accepts as
argument the message to be displayed.  The message will be displayed
indefinitely as ``critical''.  The editor places the script in file
\texttt{/usr/local/bin/{\allowbreak}notify-send-all}.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk          & \verb`#! /bin/bash -u` \\
\Clunk[LP3604]  & \verb`# notify-send-all sends notifications to all X displays` \\
\Clunk[LP3605]  & \verb`# Assumes /etc/sudoers allows caller to sudo as any user.` \\
\Clunk          & \verb`# E.g. nut LAN = (ALL) NOPASSWD:SETENV: /usr/bin/notify-send` \\
\Clunk[LP3606]  & \verb`# Call with text to be displayed as argument.` \\
\Clunk[LP3609]  & \verb`XUSERS=( $( who | grep -E "\(:[0-9](\.[0-9])*\)" \` \\
\Clunk          & \verb`         | awk '{print $1$NF}' | sort -u ) )` \\
\Clunk[LP3610]  & \verb`for XUSER in $XUSERS      # E.g. jschmo(:0)` \\
\Clunk[LP3611]  & \verb`do NAME=(${XUSER/\(/ })   # Insert space, make NAME an array` \\
\Clunk[LP3612]  & \verb`   DISPLAY=${NAME[1]/)/}  # E.g. :0` \\
\Clunk[LP3613]  & \verb`   sudo -u ${NAME[0]} DISPLAY=${DISPLAY} \` \\
\Clunk          & \verb`           /usr/bin/notify-send -t 0 -u critical "$@"; RC=$?` \\
\Clunk[LP3614]  & \verb`   if [[ $RC -ne 0 ]]; then exit $RC; fi` \\
\Clunk[LP3615]  & \verb`done` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Bash script \notifysendall\label{fig:notifysendall}}
\end{figure}

Line \ref{LP3609} produces a Bash array of all the users identified by
\texttt{who} who have X displays.  Each item in the array corresponds
to a logged in user with an X display and is of the form
\texttt{jschmo(:0)}.

For each user logged in with an X display, line \ref{LP3611} creates a
Bash array containing the user name and the X display number in the
form \texttt{jschmo :0)}.

Line \ref{LP3612} extracts the X display number \texttt{:0} and on
line \ref{LP3613} calls \notifysend\ to notify the user as if user
``nut'' (``upsd'' on openSUSE) was that logged in user.  Note that
environment variable \texttt{DISPLAY} is set for that user.

See the discussion
\href{https://unix.stackexchange.com/questions/2881/show-a-notification-across-all-running-x-displays}{``Show
  a notification across all running X displays''} on the stackexchange
site.


\subsection{\Hsep\ Testing the \notifysendall\ setup}\label{section:test.notify.test}

A simple way of testing the use of \notifysend\ if you are using the chapter
\ref{section:workstation} configuration is to simply disconnect the wall power
for 10 seconds.  This is sufficient to provoke \upsmon\ into calling
\upsschedcmd\ which in turn calls \notifysendall\ as shown at line \ref{LP35H}.
 
While wall power is disconnected, use a command such as \texttt{ps -elf | grep
  -E "ups[dms]|nut"} to find the programs running as user ``nut'' (``upsd'' on
openSUSE):

\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[A100] & \verb`nut   2635     1  ... /usr/bin/usbhid-ups -a Eaton` \\
\Clunk       & \verb`nut   2637     1  ... /usr/bin/dummy-ups -a heartbeat` \\
\Clunk       & \verb`nut   2641     1  ... /usr/sbin/upsd` \\
\Clunk       & \verb`root  2645     1  ... /usr/sbin/upsmon` \\
\Clunk       & \verb`nut   2646  2645  ... /usr/sbin/upsmon` \\
\Clunk[A101] & \verb`nut   3217     1  ... /usr/sbin/upssched UPS Eaton@localhost: On battery` \\
\Clunk[A102] & \verb`nut   3236     1  ... dbus-launch --autolaunch=d1cd...ca5d2` ... \\
\Clunk       & \verb`nut   3237     1  ... /bin/dbus-daemon --fork --print-pid 5` ... \\
\Clunk[A103] & \verb`nut   3241     1  ... /usr/lib/xfce4/notifyd/xfce4-notifyd` \\
\Clunk[A104] & \verb`nut   3243     1  ... /usr/lib/xfce4/xfconf/xfconfd` \\
\end{LinePrinter}

Lines \ref{A100}-\ref{A101} are due to NUT activity, and lines
\ref{A102}-\ref{A104} are due to the use of \notifysend.  Note on line
\ref{A103} that the \texttt{xfce4-notifyd} daemon is running as user
``nut ''!
 
\subsection{\Hsep\ References for \notifysend}\label{section:notifysend.references}

\ol

\li For a suggestion of how to send notifications on an Apple Mac, see
the
\href{https://lists.alioth.debian.org/pipermail/nut-upsuser/2017-June/010729.html}{posting}
by Robbie van der Walle, Sun Jun 11 11:27:55 UTC 2017, in the
nut-upsuser mailing list.

\li For a discussion of how to send notifications to all running X-server users, see
\href{https://unix.stackexchange.com/questions/2881/show-a-notification-across-all-running-x-displays}%
{stackexchange question 2881}.

\li The Gnome \href{https://developer.gnome.org/notification-spec/}{``Desktop
  Notifications Specification''} is still a very long way from being RFC quality.

\li Man pages: See \DEBman{xfce4-notifyd-config} and \DEBman{notify-send}

\li Xfce4 web page: There is also an \texttt{xfce4-notifyd}
\href{https://docs.xfce.org/apps/notifyd/start}{web page}.

\eol

\quad

\textsl{These techniques have been tested with the Xfce desktop environment on
  openSUSE and Debian. The editor would be pleased to hear of any successful
  adoption of the techniques on Fedora, Arch or Ubuntu based systems, using
  other desktop environments such as Cinnamon, KDE or Gnome.}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}

%\input{ConfigExamples.buildOpenSSLandPython}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
%\newcolumn
\section{\Hsep\ Log rotation for \upsdTLS\ and \UPSmon}\label{section:logrotate}

The well known Unix/GNU Linux utility program \texttt{logrotate} provides a
convenient way of managing log files.  See \LINman{logrotate}{8}.  NUT 2.7.4
already provides a declaration for it's log files.  The following declaration
provides separate management for the log files created by \upsdTLS\ and
\UPSmon.

The file should be created as \texttt{/etc/logrotate.d/NUT} with ownership
\texttt{root:root} and permissions \texttt{644}.

\begin{figure}[ht]
\begin{LinePrinter}[0.9\LinePrinterwidth]
\Clunk[LR000] & \verb`# Log rotation configuration for upsdTLS.py, UPSmon.py` \\
\Clunk[LR001] & \verb`# Rotate NUT log file either monthly or when exceeding 5 Mb` \\
\Clunk[LR002] & \verb`#` \\
\Clunk[LR003] & \verb`# For more information, refer to logrotate(8) manual page:` \\
\Clunk[LR004] & \verb`#   http://linuxcommand.org/man_pages/logrotate8.html` \\
\Clunk[LR005] & \verb`#` \\
\Clunk[LR006] & \verb`/var/log/NUT.log {` \\
\Clunk[LR007] & \verb`    missingok` \\
\Clunk[LR008] & \verb`    notifempty` \\
\Clunk[LR009] & \verb`    size=5M` \\
\Clunk[LR010] & \verb`    rotate 12` \\
\Clunk[LR011] & \verb`    monthly` \\
\Clunk[LR012] & \verb`    create 0600 nut nut` \\
\Clunk[LR013] & \verb`}` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Log rotation for \upsdTLS\ and \UPSmon}\label{fig:logrotate}
\end{figure}

Line \ref{LR011} calls for a log rotation every month, and line \ref{LR010}
requires keeping 12 previous months' logs, so in all there will be one year's
records.

Line \ref{LR012} creates a file with owner \texttt{nut:nut} suitable for Debian.
You should adapt this for your distribution.  See table \ref{fig:UD}.

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-1.jpg, height=36mm}
\end{center}

\vspace*{\fill}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                            P A R T  4                                  %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage

% Layout for the body.  See the LaTeX Companion, p.96.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[\UPSmon\ 1.3]{\UPSmon\ 1.3}                             % \lhead[left-header-even]{left-header-odd}
%\chead[ConfigExamples \Version]%
%      {ConfigExamples \Version}                               % \chead[centre-header-even]{centre-header-odd}
%\rhead[Build \isodate]{Build \isodate}                        % \rhead[right-header-even]{right-header-odd}
%\lfoot[]{}                                                    % \lfoot[left-footer-even]{left-footer-odd}
%\cfoot[\fancyplain{}{Page \thepage\ of \pageref{LastPage}}]%
%      {\fancyplain{}{Page \thepage\ of \pageref{LastPage}}}   % \cfoot[centre-footer-even]{centre-footer-odd}
%\rfoot[]{}                                                    % \rfoot[right-footer-even]{right-footer-odd}

\begin{center}
\addtocontents{toc}{\protect\vspace{3mm}}
\part[\hspace{\fill}\textsf{UPS monitoring using Python3 script}\hspace{\fill}]{}\label{part:UPSmon}
\addtocontents{toc}{\protect\vspace{3mm}}
\vspace{5mm}
\textsf{\huge{UPS monitoring using Python3 script}} \\[2mm]
\textsf{\textsl{\Large{Warning: This is Work in Progress}}}
\vspace{7mm}
\end{center}

\textit{Part \ref{part:NUT} of this documentation discussed the way in
  which UPS activity reported by \upsd\ can be monitored using the
  monitoring software provided with NUT 2.8.0.  This part
  \ref{part:UPSmon} covers the use of Python3 scripts and openSSL/TLS
  to monitor the same UPS activity.}

\textit{This Part provides descriptions of Python3 scripts
  \UPSmon\ and \mkUPSmonconf.  The script \UPSmon\ requires a helper
  script to create TLS certificates. The script \mkNUTcert\ is
  described in part \ref{part:shim} chapter \ref{section:TLS}.}

\textit{The scripts and their SHA1 check sums may be downloaded from
        \href{rogerprice.org/NUT}{http://rogerprice.org/NUT}}

\vspace{10mm}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
%\newcolumn
\section{\Hsep\ Python3 script \UPSmon\ version 1.2}\label{section:Umintro}

\begin{figure}[ht]
\vspace{-6mm}
\begin{center}
   \epsfig{file=UPSmon.pdf,width=1.0\LinePrinterwidth}
   \epsfig{file=UPSmon-OB.pdf,width=1.0\LinePrinterwidth}
\end{center}
\vspace{-6mm}
\caption{\UPSmon\ requires TLS.\label{fig:UPSmon-OB}}
\end{figure}

\subsection{\Hsep\ What is \UPSmon\ ?}\label{section:Umwhat}

\UPSmon\ is a Python3 script which replaces \upsmon, \upssched\ and
\upsschedcmd.  The configuration files \upsmonconf\ and \upsschedconf\ are
replaced by a single configuration file \UPSmonconf.  The current version 1.2
of \UPSmon\ is ``experimental'', intended for experiment and demonstration.

\subsubsection{\Hsep\ Principal differences between \upsmon\ and \UPSmon}\label{section:differences}

The principal differences between NUT's \upsmon\ and \UPSmon\ are:

\ol

\li \UPSmon\ is written in \href{https://www.python.org}{Python3} rather than
K{\&}R C.  It is hoped that this use of a well known higher level language
will encourage further experimentation.  The script is in one single file
rather than the many separate files used in NUT C code.  Like the NUT C code,
the script is \textbf{not} object oriented.  To assist further development,
the script provides 116 error and warning messages, and the \texttt{-D} and
\texttt{-Y} debug options provide a detailed ``walk-through'' of the script's
operations.

\li Unlike \upsmon, \UPSmon\ does not retain the parent process when forking
to a non-privileged user.  This improves security, but implies that the
non-privileged user such as \texttt{nut} has \texttt{sudo} rights for programs
\texttt{wall}, \texttt{notify-send} and \texttt{shutdown}.

\li \UPSmon\ assumes that it will be managing a large number of physical and
virtual UPS and other power supply units.  The management may be of the type
``primary'' or ``secondary'', known formerly as ``master'' or ``slave'', or
simply as an observer with the primary/secondary shutdown decisions taken
elsewhere.

\li The UPS units, real and virtual, are collected into groups.  Every UPS
must be in exactly one group.  \upsmon\ does not support groups.

\li All UPS's must be individually identified.  Unlike NUT, there are no
``wildcard'' UPS's.  Each UPS has a formal ``fully qualified'' name which is
of the form
\textit{group}\texttt{:}\textit{ups}\texttt{@}\textit{host}\texttt{:}\textit{port}\ ,
for example \texttt{HB:heartbeat@bigbox:3493} , although shortened forms are
used where there is no ambiguity.

\li The configuration file \UPSmonconf\ is read by
\href{https://www.dabeaz.com/ply/}{PLY}, Python Lex and Yacc.  This implies
a slightly slower start-up than NUT but allows freer formats and many
possibilities for future expansion.

\li The \upsmonconf\ declarations \texttt{DEADTIME}, \texttt{FINALDELAY},
\texttt{HOSTSYNC}, \texttt{NOCOMMWARNTIME} and \\ \texttt{RBWARNTIME} are not
needed in \UPSmonconf\ since they are timers which can be expressed directly
if needed.

\li All communication between \UPSmon\ and \upsd\ is TLS encrypted. The
version of OpenSSL used is too recent to be compatible with nut 2.7.4, so a
shim front end for \upsd\ called \upsdTLS\ is provided to accept TLS encrypted
commands from \UPSmon\ and then relay that traffic to the local \upsd.  Part
\ref{part:shim} describes \upsdTLS.  The options chosen for TLS call for the
latest version with full checking of the certificates.  Use of the earlier and
now deprecated SSL is excluded.

\li \UPSmon\ supports two loggers: the system log and a text based
NUT-specific log.

\li \UPSmon\ does not require a supplementary program such as \upssched\ or a
script such as \upsschedcmd.  The functions of those programs are available in
\UPSmon.  NUT's \upsmon\ provides three \texttt{NOTIFYFLAG} options:
\texttt{SYSLOG}, \texttt{WALL} and \texttt{EXEC}, \UPSmon\ replaces these with
the more complete set of actions shown in figure \ref{fig:ACTIONS}.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|p{0.65\LinePrinterwidth}|}
\hline
\multicolumn{1}{|c|}{Action} & \multicolumn{1}{|c|}{Effect} \\ \hline\hline
\texttt{STARTTIMER} \textit{name value} & Start timer with the given name and value in seconds. \\ \hline
\texttt{CANCELTIMER} \textit{name}      & Cancel timer with the given name. \\ \hline
 \begin{tabular}{ll}
 \texttt{EMAIL} & \texttt{FROM} \textit{text} \\ 
                & \texttt{TO} \textit{text} \\ 
                & \texttt{SUBJECT} \textit{text} \\ 
                & \texttt{MESSAGE} \textit{text} \\ 
 \end{tabular}                          & Send email. \\ \hline
\texttt{WALL} \textit{text}             & Send text to local wall. \\ \hline
\texttt{NOTIFY} \textit{text}           & Place text on screens of all logged-in local accounts. \\ \hline
\texttt{PRINT} \textit{text}            & Send text to STDOUT. \\ \hline
\texttt{EPRINT} \textit{text}           & Send text to STDERR. \\ \hline
\texttt{NUTLOG} \textit{text}           & Send text to NUT-specific logger. \\ \hline
\texttt{SYSLOG} \textit{text}           & Send text to system logger. \\ \hline
\texttt{SETFSD} \textit{name}           & Send \FSD\ to \upsd\ for UPS \textit{name}. \\ \hline
\texttt{SHUTDOWN} \textit{option when}  & Shutdown the system, e.g. with \\
                                        & \texttt{/usr/sbin/shutdown -h now} . \\ \hline
\texttt{DEBUG} \textit{level}           & Turn on/off the debugging output to the NUT log. \\ \hline
\end{tabular}
\caption{Actions provided by \UPSmon.\label{fig:ACTIONS}}
\end{center}
\end{figure}

\li Texts to be included in messages may be given names, and may incorporate
other named messages.  The \upsmon\ \texttt{NOTIFYMSG} \texttt{\%}
substitution is extended to provide the substitutions shown in table
\ref{fig:substitutions}.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\texttt{\%(u)s} & Fully qualified name of the UPS unit \\ \hline
\texttt{\%(c)s} & Current charge of the UPS unit \\ \hline
\texttt{\%(e)s} & The event which has produced this message \\ \hline
\texttt{\%(b)s} & A banner of the form ``2020-08-15 upsd@bigbox'' \\ \hline
\texttt{\%(h)s} & The hostname, the name of the local machine \\ \hline
\end{tabular}
\caption{\texttt{\%} substitutions available in messages.\label{fig:substitutions}}
\end{center}
\end{figure}

\li The low battery status \status{\LB} provided by \upsd\ is supplemented by
three further low battery statuses \status{\LBi}, \status{\LBii} and
\status{\LBiii} for which the trip levels may be set in \UPSmonconf.

\li When the sum of the \texttt{POWERVALUE} in a group with status \status{\OL} does
not meet the group's \texttt{MINSUPPLIES} requirement, \UPSmon\ raises status
\status{\LS}.  In \upsmon\ this is implicit in the client's logic.

\eol


\subsection{\Hsep\ Compatibility with \upsmon.}\label{section:UMcompat}

\UPSmon\ can be run at the same time and in the same machine as
\upsmon. \UPSmon\ does not interfere with direct access to \upsd\ port \IANAnut.
Command line utility programs such as \texttt{upsc} still function normally.

\subsection{\Hsep\ Overview of \UPSmon}\label{section:UMoview}

The script has a configuration file, and many options.  In general few options
and in some simple cases none at all need be changed.  To see the options and
their default values you can enter command \texttt{UPSmon.py -\/-help}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[UM000]  & \verb`$ UPSmon.py --help` \\
\Clunk[UM001]  & \verb`usage: UPSmon.py [-h] [--command fsd|reload|stop] [--config <file>]` \\
\Clunk[UM002]  & \verb`       [--debug] [--debugYacc] [--logfile <file>] [--notify <executable>]` \\
\Clunk[UM003]  & \verb`       [--PIDfile <file>] [--shell <executable>] [--sudo <executable>]` \\
\Clunk[UM004]  & \verb`       [--testSHUTDOWNflag] [--upsdtimeout <float>] [--user <user>]` \\
\Clunk[UM005]  & \verb`       [--version] [--wall <executable>]` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Command \texttt{UPSmon.py -\/-help}}.\label{fig:UMhelp}
\end{figure}

Let's look at these optional arguments in more detail.  

\begin{description}

\item[\texttt{-h, -\/-help}]  Show this help message and exit.

\item[\texttt{-\/-command fsd|reload|stop}] Send command to
  \UPSmon\ process and exit. Valid commands are \texttt{fsd},
  \texttt{reload}, \texttt{stop}.

\item[\texttt{-c \textit{<file>}, -\/-config \textit{<file>}}] The
  configuration file.  \UPSmon\ tries to guess where you put this.  Debian
  sysadmins might see \texttt{/etc/nut/UPSmon.conf} . OpenSUSE admins might
  see \texttt{/etc/ups/...}  See table \ref{fig:UD} for a list of possible
  directories.

\item[\texttt{-D, -\/-debug}] Increase the debugging level, may be repeated
  but then you get more than any human can read.  Debugging output is written
  into a NUT log file.  This option does not cover Lex and Yacc.

\item[\texttt{-Y, -\/-debugYacc}] Increase the debugging level for Lex and
  Yacc.  No human being should ever be required to read this stuff.  Debugging
  output is written into a NUT log file.

\item[\texttt{-l \textit{<file>}, -\/-logfile \textit{<file>}}] The log file,
  with default \texttt{/var/log/NUT.log} . Progress and error messages and the
  stuff generated by options \texttt{-D} and \texttt{-Y} go into this file.
  Note that if \upsdTLS\ and \UPSmon\ are running in the same machine they
  will write into the same log.  See chapter \ref{section:logrotate} for an
  extension to \texttt{logrotate} to cover this file.

\item[\texttt{-n \textit{<executable>}, -\/-notify \textit{<executable>}}] The
  notification executable. The default is
  \texttt{/usr/{\allowbreak}bin/{\allowbreak}notify-send -t 0 -u critical}

\item[\texttt{-\/-PIDfile \textit{<file>}}] The child PID is written
  into this file, for the greater pleasure of systemd.  The default is
  \texttt{/run/nut/{\allowbreak}UPSmon.pid} Do not change this unless
  you know what you are doing.  You should also review the systemd
  service unit.

\item[\texttt{-\/-shell \textit{<file>}}] The shell that will process the
  \texttt{SHELLCMD} actions. The default is \texttt{/bin/bash -c}

\item[\texttt{-\/-sudo \textit{<executable>}}] Authorise user to
  execute code as another user.  The default is
  \texttt{/usr/bin/{\allowbreak}sudo} . Use of \texttt{sudo} assumes
  that file \texttt{/etc/sudoers} allows the caller to sudo as the
  required user.  For example \\ \texttt{nut LAN = (ALL)
    NOPASSWD:SETENV: /usr/bin/notify-send, /usr/bin/wall}
  \\ \texttt{nut LAN = (ALL) NOPASSWD:SETENV:
    /usr/sbin/{\allowbreak}shutdown} \\ where LAN is defined by a
  declaration such as \\ \texttt{Host\_Alias LAN =
    10.218.0/255.255.255.0, 127.0.0.1, localhost} \\ To update
  \texttt{/etc/sudoers} , use \texttt{visudo} , for example
  \texttt{VISUAL=/usr/{\allowbreak}bin/{\allowbreak}emacs visudo -f
    /etc/{\allowbreak}sudoers} .

\item[\texttt{-K \textit{<executable>}, -\/-testSHUTDOWNflag }] Test
  the \texttt{SHUTDOWN} flag. \textit{Not implemented.}

\item[\texttt{-\/-upsdtimeout \textit{<float>}}] Socket timeout for exchanges
  with \upsd. The default is 5.0 seconds.

\item[\texttt{-u \textit{<user>}, -\/-user \textit{<user>}}] After launch as
  root, run as this user.  \UPSmon\ tries to guess the user. OpenSUSE admins
  would probably see \texttt{upsd}, whereas Debian admins would see
  \texttt{nut}. See table \ref{fig:UD} for a list of possible users.

\item[\texttt{-v, -\/-version}] Show program, Python and SSL/TLS versions,
  then exit.

\item[\texttt{-w \textit{<executable>}, -\/-wall \textit{<executable>}}] The
  wall executable. The default is \texttt{/usr/bin/wall}

\end{description}

\newcolumn
\subsection{\Hsep\ Running \UPSmon}\label{section:UMrun}

It is possible, in a simple installation, to run the daemon
\UPSmon\ in the same machine as \upsd.  However the design is for
remote monitoring of one or more \upsd\ servers across a hostile
network.  \UPSmon\ assumes that the server(s) is/are already running
and ready to receive the \texttt{STARTTLS} command.

If you use systemd to manage your box, then you will need to create a
new service unit, since systemd is unable to start two forking
services from the same unit.  See \LINman{systemd.service}{5}.  There
can only be one \texttt{Type=forking} per unit.

Copy the file
\texttt{/usr/lib/{\allowbreak}systemd/{\allowbreak}system/{\allowbreak}nut-monitor.{\allowbreak}service}
to
\texttt{/etc/systemd/{\allowbreak}system/{\allowbreak}nut-py-monitor.{\allowbreak}service}
and modify the new file shown in figure \ref{fig:UMstart}.  Lines \ref{UM012},
\ref{UM014} and \ref{UM015} have been changed.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[UM010]  & \verb`[Unit]` \\
\Clunk[UM011]  & \verb`Description=Network UPS Tools - Python - power device monitor` \\
\Clunk[UM012]  & \verb`After=local-fs.target network.target` \\
               & \\
\Clunk[UM013]  & \verb`[Service]` \\
\Clunk[UM014]  & \verb`ExecStart=/usr/sbin/UPSmon.py` \\
\Clunk[UM015]  & \verb`PIDfile=/run/nut/UPSmon.pid` \\
\Clunk[UM016]  & \verb`Type=forking` \\
               & \\
\Clunk[UM017]  & \verb`[Install]` \\
\Clunk[UM018]  & \verb`WantedBy=multi-user.target` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{systemd service unit \texttt{nut-py-monitor.service} for \UPSmon.}\label{fig:UMstart}
\end{figure}

You may choose to place the \UPSmon\ script in directory \texttt{/usr/sbin/} or
make \texttt{/usr/{\allowbreak}sbin/{\allowbreak}UPSmon.py} a link to wherever
you put the Python script.  Note that systemd service units in \texttt{/etc/}
take precedence over those in \texttt{/usr/lib/}.  See
\LINman{systemd.unit}{5}.  After you have made the changes, you should run the
command \texttt{systemctl daemon-reload} . See \LINman{systemctl}{1}.  Before
running \upsdTLS\ the first time, you will need to run the command
\begin{verbatim}
systemctl enable nut-py-monitor.service
\end{verbatim}

The following \texttt{systemctl} commands will be of use to you:

\begin{description}

\item[\texttt{systemctl daemon-reload}] to make any changes to the service
  unit available to systemd.
\item[\texttt{systemctl enable nut-py-monitor.service}] to make the daemon
  \UPSmon\ operational and ``startable''.
\item[\texttt{systemctl start nut-py-monitor.service}] to start \UPSmon.  Note
  that this will not erase the log file.  If you want to clear the log file
  then you need to do that yourself. See also chapter \ref{section:logrotate}
  for a discussion of log rotation.
\item[\texttt{systemctl status nut-py-monitor.service}] to see the current
  status of daemon \UPSmon.
\item[\texttt{systemctl stop nut-py-monitor.service}] to stop \UPSmon.

\end{description}

\UPSmon\ should start automatically when the system starts, but it can also
be stopped and started manually with the \texttt{systemctl} commands.

Serious errors will prevent \UPSmon\ from starting and you can read about them
in the NUT log and in the system log.  After starting \UPSmon, check the NUT
log for warnings and other error messages.  Look for the reports beginning
``\texttt{Sanity checks for this configuration ...}''.

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-3.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\newcolumn
\subsection{\Hsep\ \UPSmon's events based un \upsd's status changes}\label{section:stch}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|r|p{0.65\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{\textbf{Status change symbol}} & \multicolumn{1}{c|}{\textbf{Event based on Status Change}} \\ \hline\hline
\EVENT{\None}{\ALARM}   & \EVENT{\ALARM}{\None}     & The UPS has raised/dropped the alarm signal. \\ \hline
\EVENT{\None}{\BOOST}   & \EVENT{\BOOST}{\None}     & The UPS is now boosting/not boosting the output voltage. \\ \hline
\EVENT{\None}{\BYPASS}  & \EVENT{\BYPASS}{\None}    & The UPS is/is not now bypassing its own batteries. \\ \hline
\EVENT{\None}{\CAL}     & \EVENT{\CAL}{\None}       & The UPS is/is not now in calibration mode. \\ \hline
\EVENT{\None}{\CHRG}    & \EVENT{\CHRG}{\None}      & The UPS is/is not now recharging its batteries. \\ \hline
\EVENT{\None}{\DISCHRG} & \EVENT{\DISCHRG}{\None}   & The UPS is/is not now discharging its batteries. \\ \hline
\EVENT{\None}{\LB}      & \EVENT{\LB}{\None}        & The driver says the UPS battery charge is now low/no longer low
                                                      with respect to level defined by \upsrw.
                                                      See chapter \ref{section:upsrw}. \\ \hline
\EVENT{\None}{\OFF}     & \EVENT{\OFF}{\None}       & The driver says the UPS is/is not now OFF. \\ \hline
\EVENT{\OL}{\OB}        & \EVENT{\OB}{\OL}          & The UPS is now on battery/no longer on battery. \\ \hline
\EVENT{\None}{\OVER}    & \EVENT{\OVER}{\None}      & The UPS is/is not now in status \status{\OVER}. \\ \hline
\EVENT{\None}{\RB}      & \EVENT{\RB}{\None}        & The UPS needs/no longer needs to have its battery replaced. \\ \hline
\EVENT{\None}{\TEST}    & \EVENT{\TEST}{\None}      & The UPS is/is not now performing a test. \\ \hline
\EVENT{\None}{\TRIM}    & \EVENT{\TRIM}{\None}      & The UPS is now trimming/not trimming the output voltage. \\ \hline\hline
\end{tabular}
\caption{Symbols used to represent events monitored by \UPSmon.\label{fig:UPSmonEVENT}}
\end{center}
\end{figure}

\UPSmon, like NUT's \upsmon\ is an example of a client of \upsd\footnote{See
  chapter \ref{section:upsd} for details of \upsd.}.  Just as \upsmon\ does,
it runs permanently as a daemon in a local or remote box, polling the status
changes of the UPS unit.  It is able to react to changes in the UPS state for
example by emitting warning messages, or shutting down the box.  The actions
are specified in the configuration file \UPSmonconf\ which will be discussed
in specific examples.

As the state of a UPS evolves, each status change, called an ``EVENT'', is
identified with the symbols shown in figure \ref{fig:UPSmonEVENT}.
\textit{(These correspond to the NOTIFY events, also known as a ``notifytype''
  in NUT.)}

For example, figure \ref{fig:UPSmon-OB} shows what happens when wall power
fails.  Daemon \upsd\ has polled the UPS, and has discovered that the UPS is
supplying power from it's battery.  The \upsstatus\ changes to \status{\OB}.
Daemon \UPSmon\ has polled \upsd, has discovered the status change and has
generated the \EVENT{\OL}{\OB} event.

\subsubsection{\Hsep\ \UPSmon's additional status symbols and events}\label{section:stcha}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|p{0.9\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{\textbf{Other statuses generated by \UPSmon}} \\ \hline
\status{\COMM}    & \UPSmon, via \upsd\ is in effective communication the the UPS.  \\ \hline
\status{\NOCOMM}  & \UPSmon\ is no longer in effective communication the the UPS.  \\ \hline
\status{\FSD}     & The UPS unit is in Forced ShutDown mode. \\ \hline
\status{\LBi}     & The battery charge is below a critical level specified by declaration
                    \texttt{LET battery.charge.low.1 = '}$L$\texttt{'}. \\ \hline
\status{\LBii}    & The battery charge is below a critical level specified by declaration
                    \texttt{LET battery.charge.low.2 = '}$L$\texttt{'}. \\ \hline
\status{\LBiii}   & The battery charge is below a critical level specified by declaration
                    \texttt{LET battery.charge.low.3 = '}$L$\texttt{'}. \\ \hline
\status{\LS}      & Within a group, the total power value of the UPS units
                    with status \status{\OL} does
                    not satisfy the group's MINSUPPLIES declaration. \\ \hline
\status{\TICK}    & Status generated by a heartbeat UPS. \\ \hline
\status{\TOCK}    & Status generated by a heartbeat UPS. \\ \hline
\status{\TO}      & A \UPSmon\ timer has completed. \\ \hline
\end{tabular}
\caption{Additional status symbols generated by \UPSmon.\label{fig:statussymbolsa}}
\end{center}
\end{figure}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|r|p{0.65\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{\textbf{Status change symbol}} & \multicolumn{1}{c|}{\textbf{Other Events generated by \UPSmon}} \\ \hline\hline
\EVENT{\COMM}{\NOCOMM}  & \EVENT{\NOCOMM}{\COMM}    & Communication with the UPS in now lost/restored. \\ \hline
\EVENT{\None}{\FSD}     & \EVENT{\FSD}{\None}       & The UPS is/is not now in Forced ShutDown mode. \\ \hline
\EVENT{\None}{\LBi}     & \EVENT{\LBi}{\None}       & The UPS battery charge is now low/no longer 
                                                      low with respect to critical level 1. \\ \hline
\EVENT{\None}{\LBii}    & \EVENT{\LBii}{\None}      & The UPS battery charge is now low/no longer 
                                                      low with respect to critical level 2. \\ \hline
\EVENT{\None}{\LBiii}   & \EVENT{\LBiii}{\None}     & The UPS battery charge is now low/no longer
                                                      low with respect to critical level 3. \\ \hline
\EVENT{\None}{\LS}      & \EVENT{\LS}{\None}        & Within a group, the total power value of the UPS units
                                                      with status \status{\OL} does/does not
                                                      satisfy the MINSUPPLIES declaration. \\ \hline
\EVENT{\None}{\TICK}    & \EVENT{\TICK}{\None}      & A heartbeat UPS has/has not generated a \status{\TICK}. \\ \hline
\EVENT{\None}{\TOCK}    & \EVENT{\TOCK}{\None}      & A heartbeat UPS has/has not generated a \status{\TOCK}. \\ \hline
\multicolumn{2}{|c|}{\EVENT{\TO}{my-timer}}         & Timer ``my-timer'' has completed. \\ \hline
\end{tabular}
\caption{Additional events monitored by \UPSmon.\label{fig:UPSmonEVENTa}}
\end{center}
\end{figure}

In addition to the events based on \upsd\ status changes, \UPSmon\ also
generates further statuses and status changes based on its monitoring of
\upsd.  See figure \ref{fig:statussymbolsa}.  Changes in these additional
statuses give rise to additional events shown in figure
\ref{fig:UPSmonEVENTa}.

\subsection{\Hsep\ Configuration file}\label{section:UPSmonconffile}

There is just one configuration file for \UPSmon\ which replaces \upsmonconf,
\upsschedconf\ and \upsschedcmd.  The formal grammar for this configuration
file is in chapter \ref{section:grammar}.  The file contains:

\ol

\li Comments and blank lines.  A comment begins with a \texttt{\#} character
found outside a quoted text, and continues up the the end-of-line.

\li Initial declarations.  See section \ref{section:initdecl}

\li One or more group declarations.  See section \ref{section:grpdecl}.

\eol

The following technical terms are used in the descriptions of the
configuration file:

\begin{description}

\item[\ttit{quotation mark}] \hspace{7mm} One of the following five
  styles\footnote{I couldn't decide which ones to use so I kept them all. Ed.}
  of text marker.  See chapter \ref{section:brackets} for help in typing the
  characters which may not be on your keyboard.

\ol

\li double quotation marks: "\textit{bla..bla...}" which are probably on your
keyboard,

\li single quotation marks: '\textit{bla..bla...}'  which are also on your
keyboard,

\li french guillemets: «\textit{bla..bla...}»,

\li mathematical left ceiling/right floor ⎡\textit{bla..bla...}⎦ and 

\li corner brackets used for quotations in asian lanuages:
⸢\textit{bla...bla...}⸥.

\eol

\item[\ttit{quotetext}] \hspace{7mm} A text in quotation marks.  E.g. «Hello
  World»

\item[\ttit{quotetexts}] \hspace{7mm} A sequence of one or more
  \textit{quotetext} declarations.  E.g. «Today is » «Friday.» This results in
  a single text ``Today is Friday.''

\item[\ttit{number}] \hspace{7mm} An integer or floating point number such
  as 15 or 2.8.

\item[\ttit{name}] \hspace{7mm} Names for groups, timers, UPS's, messages.
  The name begins with \texttt{[a-zA-Z\_]} and continues with as many of
  \texttt{[a-zA-Z0-9.\_\%+-]} as you like.  E.g. \texttt{UPS31.a-BIG\_BOX}.

\item[\ttit{ups-name}] \hspace{7mm} All UPS's must be individually
  identified.  Unlike NUT, there are no ``wildcard'' UPS's.  Each UPS has a
  formal ``fully qualified'' name which is of the form
  \textit{group}\texttt{:}\textit{ups}\texttt{@}\textit{host}\texttt{:}\textit{port}
  for example \texttt{HB:heartbeat@bigbox:3493} , although shortened forms are
  used where there is no ambiguity.

\end{description}

\subsubsection{\Hsep\ Initial declarations}\label{section:initdecl}

The initial declarations are 

\begin{description}

\item[\texttt{SMTPSERVER \textit{quotetext} PORT \textit{number} USER
    \textit{quotetext} PASSWORD \textit{quotetext}}] \hspace{7mm} If you want
  to send e-mails, you must provide details of your e-mail service provider.
  For example \texttt{SMTPSERVER 'mail.gandi.net' PORT 465 USER
    'mbox@example.com' PASSWORD «1234»} . Connections with the SMTP server
  are always TLS encrypted.

\item[\texttt{LET \textit{name} = \textit{quotetexts}}] \hspace{7mm} Provide a
  name for one or more \textit{quotetext}.  This saves a lot a typing.  For
  example \texttt{LET banner = ⸢[\%(b)s] UPS=\%(u)s charge=\%(c)s
    event=\%(e)s⸥} .  The named message \texttt{LET hostname =
    \textit{hostname}} is built in.  There may be multiple \texttt{LET}
  declarations, and each may make use of names declared in previous
  \texttt{LET}s.

\item[\texttt{MAXNOTIFY \textit{number}}] \hspace{7mm} This limits the number
  of on-screen notifications, and was needed during early debugging when
  things often exploded.  It will probably be removed in the future.  The
  default is 20.

\item[\texttt{POLLFREQ \textit{number}}] \hspace{7mm} This is the polling
  period for all UPS units managed by this \UPSmon\ instance.  The default,
  which is the recommended value, is 5 seconds.  See also \NUTman{upsmon.conf}

\item[\texttt{POLLFREQALERT \textit{number}}] \hspace{3mm} This is the polling
  period for all UPS units managed by this \UPSmon\ instance when any one of
  them is in status \status{OB}.  The default is 5 seconds.

\end{description}


\subsubsection{\Hsep\ Group declarations}\label{section:grpdecl}

Each group in a sequence of groups begins with a \texttt{GROUP}
declaration header followed by other declarations described in this
section.

Within a group, a \texttt{\textit{condition}} is either empty or has
the form \texttt{IF \textit{old-status} -> \textit{new-status}}. The
condition has the value True if in the sequence of events from the
given UPS, that UPS now has status \textit{new-status}.  For example
the expression \texttt{IF OB -> OL} is True if the UPS currently has
status \status{OL} and False if the UPS has status \status{OB}.  Note
that \textit{old-status} -> \textit{new-status} must be a valid event
as listed in chapter \ref{section:stch}.

The \texttt{GROUP} declaration header is as follows:

\begin{description}

\item[\texttt{GROUP \textit{name} HOST \textit{name} PORT
    \textit{number} CERTFILE \textit{name/quotetext}}] \hspace{7mm}
  One or more UPS units share the same \texttt{HOST}, \texttt{PORT}
  and TLS \texttt{CERTFILE}.  E.g.  \texttt{GROUP LOCAL HOST localhost
    PORT 401 CERTFILE /etc/nut/gold-client.cert.pem} . The UPS units
  attached to this host are grouped together and each is specified by
  a \texttt{MONITOR} declaration in this group.

\end{description}

Within each group the following declarations may appear:

\begin{description}

\item[\texttt{LET \textit{name} = \textit{quotetexts}}] \hspace{7mm} Further
  named texts.  Note that there is only one name space shared by all
  \texttt{LET} declarations.  It's up to you to avoid clashes.

  The \textit{name} \texttt{battery.charge.low.}$i$ for $i = 1..3$ is a
  special case in which the \textit{quotetexts} must be quoted integer.  The
  effect is to assign the integer value as the battery charge level at which
  the events \EVENT{None}{LB$i$} and \EVENT{LB$i$}{None} will occur.  For
  example \texttt{LET battery.charge.low.2 = '33'} The level is set for the
  most recently defined UPS, i.e. the previous \texttt{MONITOR} declaration.
  The default levels are \LBi=50, \LBii=25 and \LBiii=12.

\item[\texttt{MONITOR \textit{ups-name} POWERVAL \textit{number} UPSDUSER
    \textit{name} PASSWORD \textit{quotetext} TYPE
    \textit{name}}] \ \\
  Each UPS unit to be managed must be declared.  The \textit{ups-name} must
  match the name in the \upsconf\ declaration.  See for example line
  \refpage{LP100}.  The \texttt{POWERVAL} is the number of power supplies that
  this UPS feeds.  The \texttt{UPSDUSER} is the ``user'' declared in
  \upsdusers.  See line \refpage{LP120}.  The \texttt{PASSWORD} is the value
  declared in \upsdusers.  See line \refpage{LP121}.  The \texttt{TYPE} value must
  be \texttt{primary} or \texttt{secondary}.  The earlier values
  \texttt{master}, \texttt{slave} are accepted.  In NUT's
  \upsmonconf\ \texttt{primary} means this system will shutdown last, allowing
  any secondaries time to shutdown first.  The declaration is included here to
  facilitate interworking with \upsmon\ but in \UPSmon, it is merely a
  declaration of intention, since the logic is decided by the declared
  actions.

  E.g. \texttt{MONITOR ups1 POWERVAL 1 UPSDUSER leboss PASSWORD 'sekret' TYPE primary}

\item[\texttt{MINSUPPLIES} \ttit{number}] \hspace{7mm} 

Declare for each \texttt{GROUP} the number of power supplies which must be
operational, and that if fewer are available, NUT must shut down the server.
The default value is 1 if this declaration is omitted.  See chapter
\ref{section:upsmonconf.dual}

\textit{More work needed here to create a MINSUPPLIES event.}

\item[\texttt{WHEN \textit{ups-name} REPORTS
    \textit{old-status}->\textit{new-status} : \textit{actions}}] \ \\
  Declare what, if anything, is to be done when an event, i.e.\ a
  status change occurs.  The \textit{ups-name} may be abbreviated when
  there is no ambiguity, but the fully qualified UPS name is always
  used internally.

  The sequence \textit{old-status}\texttt{->}\textit{new-status} defines a
  status change, i.e. an event.  The valid events are listed in chapter
  \ref{section:stch}.

  When the event specified for this UPS is detected, the \textit{actions} will
  be executed.  For example \texttt{WHEN ups1 REPORTS None->LB :
    \textit{actions}} Let's hope those actions do something useful.

\item[\texttt{WHEN \textit{ups-name} TIMEOUT \textit{timer-name} :
    \textit{actions}}] \ \\ Declare what, if anything, is to be done when a
  timeout occurs.  The \textit{timer-name} will have been declared by a
  previous \texttt{STARTTIMER} action.  \texttt{TIMEOUT} may be written as
  \texttt{TO}. For example \texttt{WHEN ups1 TO final-delay : SHUTDOWNCMD
    «/sbin/shutdown -h now»}

\item[\ttit{actions}]\label{item:condition} \hspace{7mm} A sequence
  of one or more of the following:

\begin{description}

\item[\ttit{condition} \texttt{CANCELTIMER}
  \ttit{timer-name}] \hspace{7mm} The \ttit{timer-name} must have been
  declared by a previously\footnote{``Previous'' means previous in
  time, not in the order of declarations in \UPSmonconf.}  executed
  \texttt{STARTTIMER} action.  It is not an error to cancel a timer
  after it has run out.

\item[\ttit{condition} \texttt{DEBUG 0/1/2}] \hspace{7mm} Initiate or terminate
debugging output.  Note that since a set of actions is executed in random
order, you should not rely on a \texttt{DEBUG} in the same set of actions as
the action you wish to trace.

\item[\ttit{condition} \texttt{EMAIL FROM} \ttit{quotetext}]
\vspace{-2mm}\item[\hspace{2cm} \texttt{TO} \ttit{quotetext}]
\vspace{-2mm}\item[\hspace{2cm} \texttt{SUBJECT} \ttit{quotetext}]
\vspace{-2mm}\item[\hspace{2cm} \texttt{MESSAGE} \ttit{quotetexts}]
\vspace{-2mm} \ \\
  Send an email  via the mail server declared in the
  introduction by \texttt{SMTPSERVER}.  E.g. 
  \begin{verbatim}
  EMAIL FROM «UPSmon.py@example.com»
        TO   «sysadmin@bigbox.com»
        SUBJECT «Msg-1-min»
        MESSAGE «Msg-1-min»\end{verbatim}
  Where \texttt{Msg-1-min} has been previously declared in a \texttt{LET}.
  Note that the message must be in 7-bit ascii.  Any character more exotic
  will be converted to a ``\texttt{\~}''.

\item[\ttit{condition} \texttt{STARTTIMER} \ttit{timer-name
    number}] \hspace{7mm} Declare and start a timer with the given name, and
  the given value in seconds.  It is up to you to avoid name conflicts between
  timers and with other names.  E.g. \texttt{STARTTIMER final-delay 5}

\item[\ttit{condition} \texttt{EPRINT} \ttit{quotetexts}] \hspace{7mm}
  Send the \textit{quotetexts} to STDERR.  When UPSmon is daemonized,
  \texttt{EPRINT} is ignored.  Use \texttt{NUTLOG} instead.

\item[\ttit{condition} \texttt{NOTIFY} \ttit{quotetexts}] \hspace{7mm}
  Place the \textit{quotetexts} in an on-screen notification for all logged-in
  users.  If \UPSmon\ is run as a non-privileged user, which is usually the
  case, than that user, for example \texttt{nut}, must be given access to
  program \texttt{notify-send} in file \texttt{/etc/sudoers} .  See chapter
  \ref{section:notifysend.sudoer} for details of how to do this.  See also
  \LINman{sudo}{8} for lots and lots of brain-damaging detail.

\item[\ttit{condition} \texttt{NUTLOG} \ttit{quotetexts}] \hspace{7mm}
  Write the \textit{quotetexts} into the NUT log file specified by option
  \texttt{-\/-logfile}.  The \textit{quotetexts} will be prepended with a
  timestamp and a reminder of the source program and line number.  For example
  action \texttt{NUTLOG «Hello World»} might add the following line to the log
  file:
  \begin{verbatim}
  18:32:25 UPSmon.py[3498] Hello World\end{verbatim}
  See chapter \ref{section:logrotate} for an extension to \texttt{logrotate}
  to cover this file.

\item[\ttit{condition} \texttt{PRINT} \ttit{quotetexts}] \hspace{7mm}
  Send the \textit{quotetexts} to STDOUT.  When UPSmon is daemonized,
  \texttt{PRINT} is ignored.  Use \texttt{NUTLOG} instead.

\item[\ttit{condition} \texttt{SETFSD} \ttit{ups-name}] \hspace{7mm} This
  action sets the ``forced shutdown'' flag on each secondary (slave) UPS when
  the primary (master) plans to power it off. This is done so that secondary
  (slave) systems will know about the power loss and shut down before the UPS
  power disappears.  \UPSmon, like \upsmon, in primary (master) mode is the
  primary user of this function.

Setting this flag makes \status{FSD} appear for this UPS.  This \status{FSD}
should be treated just like a \status{OB LB}.  To use this action, you need
\texttt{upsmon primary} in \upsdusers, or ``FSD'' action granted in \upsdusers.
See \NUTman{upsd.users}. 

Note that \status{FSD} in \upsd\ is currently a latch - once set, there is no
way to clear it short of restarting \upsd.  This may cause issues when
\upsd\ is running on a system that is not shut down due to the UPS event.

See \href{https://networkupstools.org/docs/developer-guide.chunked/ar01s09.html}%
         {the Network UPS Tools Developer Guide, Network protocol information}

\item[\ttit{condition} \texttt{SHELLCMD} \ttit{quotetexts}] \hspace{7mm}
  Call on the shell defined by the option \texttt{-\/-shell} to execute the
  command given by the \textit{quotetexts}.  For example
  \begin{verbatim}
  SHELLCMD «echo "Today is $(date)" >> /var/log/NUT.log»\end{verbatim}
  might write ``\texttt{Today is Tue Oct 13 10:09:02 CEST 2020}'' into the log file.

\item[\ttit{condition} \texttt{SHUTDOWNCMD}
  \ttit{quotetexts}] \hspace{7mm} Call for a system shutdown using the
  command specified by the \textit{quotetexts}.  For example,
  \texttt{SHUTDOWNCMD «/sbin/shutdown -h 0»}. If \UPSmon\ is run as a
  non-privileged user, which is usually the case, than that user, for example
  \texttt{nut}, must be given access to program \texttt{shutdown} in file
  \texttt{/etc/sudoers} .  See chapter \ref{section:notifysend.sudoer} for
  details of how to do this.  See also \LINman{sudo}{8} for lots of detail.

\item[\ttit{condition} \texttt{SYSLOG} \ttit{quotetexts}] \hspace{7mm}
  Write the \textit{quotetexts} into the system log.  The system log provides
  8 levels of urgency. They are shown, in order of decreasing importance, in
  table \ref{fig:syslog}.
\begin{figure}[ht]
\begin{center}
\begin{tabular}{|r|l|}
\hline
\texttt{[emerg]}   & System is unusable \\ \hline
\texttt{[alert]}   & Action must be taken immediately \\ \hline
\texttt{[crit]}    & Critical conditions \\ \hline
\texttt{[err]}     & Error conditions \\ \hline
\texttt{[warning]} & Warning conditions \\ \hline
\texttt{[notice]}  & Normal, but significant, condition \\ \hline
\texttt{[info]}    & Informational message (default)\\ \hline
\texttt{[debug]}   & Debug-level message \\ \hline
\end{tabular}
\caption{System log urgency levels.\label{fig:syslog}}
\end{center}
\end{figure}
If your \textit{quotetexts} are prefixed with one of these urgency indicators,
your message will be logged at the required level e.g. \texttt{SYSLOG
  «[debug]» « UPS \%(u)s burning»}\ .  The default level is \texttt{[info]}.

\item[\ttit{condition} \texttt{WALL} \ttit{quotetexts}] \hspace{7mm} Place
  the \textit{quotetexts} in a console message for all logged-in users.  If
  \UPSmon\ is run as a non-privileged user, which is usually the case, than
  that user, for example \texttt{nut}, must be given access to program
  \texttt{wall} in file \texttt{/etc/sudoers} .  See chapter
  \ref{section:notifysend.sudoer} for details of how to do this.  See also
  \LINman{sudo}{8} for details.  Note that \texttt{wall} does not support
  UTF-8.

\end{description}

\end{description}

%\vspace*{\fill}
%\begin{center}
%   \epsfig{file=UPS-1.jpg, height=36mm}
%\end{center}
%\vspace*{\fill}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
%\newcolumn
\section{\Hsep\ Typing alternative text bracketing characters}\label{section:brackets}

Text in \UPSmonconf\ must be in brackets.  You are free to choose which style;
the following table may help you to type styles which are not on your keyboard.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|c|c|p{0.15\LinePrinterwidth}|p{0.17\LinePrinterwidth}|p{0.6\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{Unicode} & \multicolumn{1}{|c|}{Emacs}
                                 & \multicolumn{1}{|c|}{Vim} & \multicolumn{1}{|c|}{Full name} \\ \hline\hline
" & U+0022 & Keyboard "          & Keyboard "           & \textsc{quotation mark} (Used left and right) \\ \hline
' & U+0027 & Keyboard '          & Keyboard '           & \textsc{apostrophe} (Used left and right) \\ \hline
« & U+00AB & \texttt{AltGr\{} or & \texttt{AltGr\{} or  & \textsc{left-pointing double angle quotation} \\
  &        & \texttt{Ctl-q 00ab} & \texttt{Ctl-v u00ab} & \textsc{mark} \\ \hline
» & U+00BB & \texttt{AltGr\}} or & \texttt{AltGr\}} or  & \textsc{right-pointing double angle quotation} \\
  &        & \texttt{Ctl-q 00bb} & \texttt{Ctl-v u00bb} & \textsc{mark} \\ \hline
⎡ & U+23A1 & \texttt{Ctl-q 23a1} & \texttt{Ctl-v u23a1} & \textsc{left square bracket upper corner} \\ \hline
⎦ & U+23A6 & \texttt{Ctl-q 23a6} & \texttt{Ctl-v u23a6} & \textsc{right square bracket lower corner} \\ \hline
⸢ & U+2E22 & \texttt{Ctl-q 2e22} & \texttt{Ctl-v u2e22} & \textsc{top left half bracket} \\ \hline
⸥ & U+2E25 & \texttt{Ctl-q 2e25} & \texttt{Ctl-v u2e25} & \textsc{bottom right half bracket} \\ \hline
\end{tabular}
\caption{Alternative text bracketing characters.\label{fig:brackets}}
\end{center}
\end{figure}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-4.jpg, height=36mm}
\end{center}

\vspace*{\fill}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\input{ConfigExamples.Part-UPSmon}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage   % 
\newcolumn
\section{\Hsep\ Grammar for \UPSmonconf}\label{section:grammar}

The \UPSmonconf\ file is parsed using \PLY. This is a pure Python approach to
Lex and Yacc.  There are no separate Lex and Yacc files.  For background
reading see ``\textit{lex \&\ yacc}'' by John R. Irvine, Tony Mason and Doug
Brown, O'Reilly, first published 1990, ISBN: 1-56592-000-7.

The PLY's Lex and Yacc produce an abstract syntax tree known as \texttt{AST}.
This is then interpreted as instructions to create a new configuration.  If
there are no errors, the new configuration is passed to \UPSmon, otherwise
\UPSmon\ continues with the previous configuration.  You can see \texttt{AST}
in the log file if you run \UPSmon\ with option \texttt{-D}.

\subsection{\Hsep\ Lexical structure}\label{section:lexstruct}

The configuration file is assumed to be encoded in UTF-8, and contains
comments, tokens (keywords and symbols), numbers and quoted text interspersed
with white space.

\begin{description}

\item[Whitespace]

Whitespace is any combination of the characters space, tab and
newline.  Whitespace serves only to separate the other components of a
configuration file.

\item[Comments]

The character \texttt{\#} outside a quoted text begins a comment which
continues up to the end of the line.  The comment is ignored by the parser.  A
\texttt{\#} inside a quoted text does not begin a comment.  This is the same
comment style as \upsmonconf\ and many other configuration files.

\item[Names]

Names are labels which identify UPS units, timers, named messages, ...  They
are not quoted and are made up of the 67 characters
\texttt{a-zA-Z0-9.\_\%+-} .  The leading character must be one of the 53
characters \texttt{a-zA-z\_} .

\item[Numbers]

Numbers are non-negative and may be floating point.  They are not quoted.
E.g. \texttt{5.5} .

\item[Tokens]

The tokens are names given to every piece of input that is recognisable by the
lexer.  They are shown in figure \ref{fig:tokens}.  The tokens are presented
in the order in which they are tested by the lexer.

\item[Quoted text]

Text is always quoted.  The possible quotation marks are shown in figure
\ref{fig:brackets}.  E.g. \texttt{"text"}, \texttt{'text'}, \texttt{«text»},
\texttt{⎡text⎦} and \texttt{⸢text⸥}.  A quoted text may not contain a newline
or it's terminating quote character.  E.g.  \texttt{«te»xt»} is an error as is
\texttt{«te}\\
\texttt{xt»}.

\item[Statuses]

The lexer recognises the following UPS statuses: \texttt{None ALARM BOOST
  BYPASS CAL CHRG DEAD DISCHRG FSD LB COMM OB OFF OL OVER RB TEST TICK TOCK
  TRIM}

\item[Events]

An event is a transition from one status to another, and is seen by the lexer
as \texttt{STATUS RARR STATUS}, e.g. \texttt{None->LB} .

\end{description}

\clearpage
\twocolumn
\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|p{0.4\LinePrinterwidth}|}
\hline
\multicolumn{1}{|c|}{\textbf{Token}} & \multicolumn{1}{|c|}{\textbf{Use}} \\ \hline\hline
\texttt{APCUPSDUSER}     & Keyword                \\ \hline
\texttt{CANCELTIMER}     & Keyword                \\ \hline
\texttt{CERTFILE}        & Keyword                \\ \hline
\texttt{COLON}           & Symbol \texttt{:}      \\ \hline
\texttt{DEBUG}           & Keyword                \\ \hline
\texttt{EMAIL}           & Keyword                \\ \hline
\texttt{EPRINT}          & Keyword                \\ \hline
\texttt{EQ}              & Symbol \texttt{=}      \\ \hline
\texttt{FROM}            & Keyword                \\ \hline
\texttt{GROUP}           & Keyword                \\ \hline
\texttt{HOST}            & Keyword                \\ \hline
\texttt{IF}              & Keyword                \\ \hline
\texttt{LET}             & Keyword                \\ \hline
\texttt{MAXNOTIFY}       & Keyword                \\ \hline
\texttt{MESSAGE}         & Keyword                \\ \hline
\texttt{MINSUPPLIES}     & Keyword                \\ \hline
\texttt{MONITOR}         & Keyword                \\ \hline
\texttt{NAME}            & Start with \texttt{a-zA-z\_} \\
                         & then \texttt{a-zA-Z0-9.\_\%+-} \\ \hline
\texttt{NOTIFY}          & Keyword                \\ \hline
\texttt{NUMBER}          & \texttt{0} through \texttt{9} plus \texttt{.} \\ \hline
\texttt{NUTLOG}          & Keyword                \\ \hline
\texttt{PASSWORD}        & Keyword                \\ \hline
\texttt{POLLFREQALERT}   & Keyword                \\ \hline
\texttt{POLLFREQ}        & Keyword                \\ \hline
\texttt{PORT}            & Keyword                \\ \hline
\texttt{POWERVAL}        & Keyword                \\ \hline
\texttt{PRINT}           & Keyword                \\ \hline
\texttt{QUOTETEXT1}      & \texttt{'text'}        \\ \hline
\texttt{QUOTETEXT2}      & \texttt{"text"}        \\ \hline
\texttt{QUOTETEXT3}      & \texttt{«text»}        \\ \hline
\texttt{QUOTETEXT4}      & \texttt{⎡text⎦}        \\ \hline
\texttt{QUOTETEXT5}      & \texttt{⸢text⸥}        \\ \hline
\end{tabular}
\caption{\UPSmonconf\ lexer tokens.\label{fig:tokens1}}
\end{center}
\end{figure}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|l|l|p{0.4\LinePrinterwidth}|}
\hline
\multicolumn{1}{|c|}{\textbf{Token}} & \multicolumn{1}{|c|}{\textbf{Use}} \\ \hline\hline
\texttt{RARR}            & Symbol \texttt{->}     \\ \hline
\texttt{REPORTS}         & Keyword                \\ \hline
\texttt{SETFSD}          & Keyword                \\ \hline
\texttt{SHELLCMD}        & Keyword                \\ \hline
\texttt{SHUTDOWNCMD}     & Keyword                \\ \hline
\texttt{SMTPSERVER}      & Keyword                \\ \hline
\texttt{STARTTIMER}      & Keyword                \\ \hline
\texttt{STATUS}          & See status list        \\ \hline
\texttt{SUBJECT}         & Keyword                \\ \hline
\texttt{SYSLOG}          & Keyword                \\ \hline
\texttt{TIMEOUT}         & Keyword                \\ \hline
\texttt{TO}              & Keyword                \\ \hline
\texttt{TYPE}            & Keyword                \\ \hline
\texttt{UPSDUSER}        & Keyword                \\ \hline
\texttt{USER}            & Keyword                \\ \hline
\texttt{WALL}            & Keyword                \\ \hline
\texttt{WHEN}            & Keyword                \\ \hline
\texttt{ignore}          & Ignore spaces and tabs \\ \hline  
\texttt{ignore\_COMMENT} & Ignore \texttt{\#...}  \\ \hline  
\texttt{newline}         & Line counter           \\ \hline 
\end{tabular}
\caption{\UPSmonconf\ lexer tokens.\label{fig:tokens}}
\end{center}
\end{figure}

\vspace*{\fill}
\begin{center}
   \epsfig{file=UPS-4.jpg, height=36mm}
\end{center}

\clearpage
\onecolumn

\newcolumn
\subsection{\Hsep\ Yacc Grammar}\label{section:yacc}

The grammar shows the logical structure of the configuration file.  There is
no separate ``yacc'' grammar file.  The productions are represented by
functions such as the one shown in figure \ref{fig:grammar:configuration}.

\begin{figure}[ht]
\begin{LinePrinter}[1.0\LinePrinterwidth]
\Clunk[GR0001]  & \verb`def p_configuration (p) :` \\
\Clunk[GR0002]  & \verb`  'configuration : intros groups'` \\
\Clunk[GR0003]  & \verb`  tag = ('configuration', p.lineno(len(p)-1)//LN, p.lineno(len(p)-1)%LN)` \\
\Clunk[GR0004]  & \verb`  AST = (tag, p[1], p[2])` \\
\end{LinePrinter}
\vspace{-6mm}
\caption{Representation of grammar production\label{fig:grammar:configuration}}
\end{figure}

Line \ref{GR0001} declares the function providing the grammar production seen
in line \ref{GR0002} for the \texttt{configuration} production.  The result is
tagged with a 3-tuple seen in line \ref{GR0003} giving the identity, line
number and column number, and forms the basis for the abstract syntax tree
\texttt{AST}.  The values for \texttt{p[1]} and \texttt{p[2]} in line
\ref{GR0004} are provided by functions \texttt{p\_intros} and
\texttt{p\_groups}.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|rp{0.55\LinePrinterwidth}|p{0.35\LinePrinterwidth}|}
\hline
\multicolumn{2}{|c|}{\textbf{Production}} & \multicolumn{1}{|c|}{\textbf{Notes}} \\ \hline\hline
\texttt{configuration :}   & \texttt{intros groups} & Start here \\ \hline\hline
\texttt{intros :}          & \texttt{intro} & Start of introduction \\
       \texttt{|}          & \texttt{intros intro} & \\ \hline
\texttt{intro :}           & \texttt{smtp} & \\
      \texttt{|}           & \texttt{let} & \\
      \texttt{|}           & \texttt{pollfreqalert} & \\
      \texttt{|}           & \texttt{pollfreq} & \\ \hline
\texttt{smtp :}            & \texttt{SMTPSERVER quotetext PORT number} & \\
                           & \texttt{USER quotetext PASSWORD quotetext} & \\ \hline
\texttt{let :}             & \texttt{LET name EQ quotetexts} 
                           & \texttt{battery.charge.low.}$i$\hfill for $i=1..3$
                             the \texttt{name} is a special value. \\ \hline
\texttt{number :}          & \texttt{NUMBER} & \\ \hline
\texttt{pollfreqalert :}   & \texttt{POLLFREQALERT number} & \\ \hline
\texttt{pollfreq :}        & \texttt{POLLFREQ number} & End of the introduction \\ \hline\hline
\multicolumn{3}{|r|}{\small continued ...} \\ \hline
\end{tabular}
\caption{\UPSmonconf\ grammar.\label{fig:yacc}}
\end{center}
\end{figure}

\begin{figure}[ht]
\begin{center}
\begin{tabular}{|rp{0.65\LinePrinterwidth}|p{0.15\LinePrinterwidth}|}
\hline
\multicolumn{3}{|l|}{\small ... continued} \\ \hline\hline
\texttt{groups :}          & \texttt{group} & Start of \\
       \texttt{|}          & \texttt{groups group\_element} & group specs \\ \hline
\texttt{group\_element :}  & \texttt{group\_name} & \\
               \texttt{|}  & \texttt{group\_host} & \\
               \texttt{|}  & \texttt{group\_port} & \\
               \texttt{|}  & \texttt{certfile} & \\
               \texttt{|}  & \texttt{let} & \\
               \texttt{|}  & \texttt{monitors} & \\
               \texttt{|}  & \texttt{minsupplies} & \\
               \texttt{|}  & \texttt{action\_declarations} & \\ \hline
\texttt{group\_name :}     & \texttt{GROUP name} & \\ \hline
\texttt{name :}            & \texttt{NAME} & \\ \hline
\texttt{group\_host :}     & \texttt{HOST name} & \\ \hline
\texttt{group\_port :}     & \texttt{PORT number} & \\ \hline
\texttt{certfile :}        & \texttt{CERTFILE quotetext} & \\
         \texttt{|}        & \texttt{CERTFILE name} & \\ \hline
\texttt{monitors :}        & \texttt{monitor} & \\
         \texttt{|}        & \texttt{monitors monitor} & \\ \hline
\texttt{monitor :}         & \texttt{MONITOR name POWERVAL number user} & \\
                           & \texttt{PASSWORD quotetext TYPE name} & \\ \hline
\texttt{user :}            & \texttt{UPSDUSER name} & \\
     \texttt{|}            & \texttt{APCUPSDUSER name} & \\ \hline
\texttt{minsupplies :}     & \texttt{MINSUPPLIES number} & \\ \hline
\texttt{action\_declarations :}        & \texttt{action\_declaration} & \\
                     \texttt{|}        & \texttt{action\_declarations action\_declaration} & \\ \hline
\texttt{action\_declaration :}         & \texttt{event\_key actions} & \\ \hline
\texttt{event\_key :}      & \texttt{WHEN name TO      name COLON} & \texttt{TO} $\equiv$ \\
           \texttt{|}      & \texttt{WHEN name TIMEOUT name COLON} & \texttt{TIMEOUT} \\
           \texttt{|}      & \texttt{WHEN name REPORTS STATUS RARR STATUS COLON} & \\
\texttt{actions :}         & \texttt{action\_element} & \\
         \texttt{|}        & \texttt{actions action\_element} & \\ \hline\hline
\multicolumn{3}{|r|}{\small continued ...} \\ \hline
\end{tabular}
\caption{\UPSmonconf\ grammar, continued.\label{fig:yacc:c}}
\end{center}
\end{figure}


\begin{figure}[ht]
\begin{center}
\begin{tabular}{|rp{0.55\LinePrinterwidth}|p{0.3\LinePrinterwidth}|}
\hline
\multicolumn{3}{|l|}{\small ... continued} \\ \hline\hline
\texttt{action\_element :} & \texttt{condition cancel\_timer} & \\
                \texttt{|} & \texttt{condition debug\_level} & \\
                \texttt{|} & \texttt{condition email} & \\
                \texttt{|} & \texttt{condition start\_timer} & \\
                \texttt{|} & \texttt{condition EPRINT quotetexts} & \\
                \texttt{|} & \texttt{condition NOTIFY quotetexts} & \\
                \texttt{|} & \texttt{condition NUTLOG quotetexts} & \\
                \texttt{|} & \texttt{condition PRINT quotetexts} & \\
                \texttt{|} & \texttt{condition SETFSD name} & \\
                \texttt{|} & \texttt{condition SHELLCMD quotetexts} & \\
                \texttt{|} & \texttt{condition SHUTDOWNCMD quotetexts} & \\
                \texttt{|} & \texttt{condition SYSLOG quotetexts} & \\
                \texttt{|} & \texttt{condition WALL quotetexts} & \\ \hline
\texttt{condition :}       & \texttt{IF STATUS RARR STATUS} & \\
          \texttt{|}       & \texttt{empty} & \\ \hline
\texttt{quotetexts :}      & \texttt{quotetext} & \\
           \texttt{|}      & \texttt{name} & \\ 
           \texttt{|}      & \texttt{quotetexts quotetext} & \\ 
           \texttt{|}      & \texttt{quotetexts name} & \\ \hline 
\texttt{quotetext :}       & \texttt{QUOTETEXT1} & \\
          \texttt{|}       & \texttt{QUOTETEXT2} & \\
          \texttt{|}       & \texttt{QUOTETEXT3} & \\
          \texttt{|}       & \texttt{QUOTETEXT4} & \\
          \texttt{|}       & \texttt{QUOTETEXT5} & \\ \hline
\texttt{cancel\_timer :}   & \texttt{CANCELTIMER name} & \\ \hline
\texttt{debug\_level :}    & \texttt{DEBUG number} & 0, 1 or 2 \\ \hline
\texttt{start\_timer :}    & \texttt{STARTTIMER name number} & \\ \hline
\texttt{email :}           & \texttt{EMAIL from to subject content} & \\ \hline
\texttt{from :}            & \texttt{FROM quotetext} & \\ \hline
\texttt{to :}              & \texttt{TO quotetext} & \\ \hline
\texttt{subject :}         & \texttt{SUBJECT quotetext} & \\ \hline
\texttt{content :}         & \texttt{MESSAGE quotetexts} & \\ \hline
\texttt{empty :}           & & \\ \hline
\end{tabular}
\caption{\UPSmonconf\ grammar, final part.\label{fig:yacc:d}}
\end{center}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\newcolumn
\section{\Hsep\ \UPSmon\ configuration}\label{section:conf}

A configuration file \UPSmonconf\ must be created to tell \UPSmon\ how to
handle the status changes coming from \upsd.  As with \upsmonconf, this can be
done manually, but for simple cases, probably the majority, in which
\upsd\ and \UPSmon\ run in the same machine, \UPSmon\ provides a Python3 tool
\mkUPSmonconf, to create a complete fully functioning configuration file.  You
can either use the output of this tool or take it as the starting point for a
customised configuration.

\subsection{\Hsep\ Configuration tool \mkUPSmonconf\ version 1.3}\label{section:mkUPSmonconf}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[MK100]  & \verb`$ mkUPSmonconf.py --help` \\
\Clunk[MK101]  & \verb`usage: mkUPSmonconf.py [-h] [--configurationfile <filename>]` \\
\Clunk[MK102]  & \verb`  [--clientcertfile <filename>] [--emailfrom <string>] [--emailto <string>]` \\
\Clunk[MK103]  & \verb`  [--plan standard|timed] [--smtppass <string>] [--smtpport <integer>]` \\
\Clunk[MK104]  & \verb`  [--smtpserver <domain>] [--smtpuser <name>] [--ups <name>]` \\
\Clunk[MK105]  & \verb`  [--upsdname <name>] [--upsdpass <string>] [--upsdport <integer>]` \\
\Clunk[MK106]  & \verb`  [--upsduser <name>] [--version]` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Command \texttt{mkUPSmonconf.py -\/-help}}.\label{fig:mkUPSmonconf}
\end{figure}

\mkUPSmonconf\ is a Python3 script which will build a simple
configuration file \UPSmonconf\ for \UPSmon.  The script proposes a
possible configuration file based on it's built-in default values and
asks for your approval.  Here is a fanciful example.

\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[MK110]  & \verb`$ mkUPSmonconf.py` \\
\Clunk[MK111]  & \verb`Here are your chosen values:` \\
\Clunk[MK112]  & \verb`   --configurationfile /etc/nut/UPSmon.conf` \\
\Clunk[MK113]  & \verb`   --clientcertfile /etc/nut/titan-client.cert.pem` \\
\Clunk[MK114]  & \verb`   --emailfrom "<bigserver@BigU.edu>"` \\
\Clunk[MK115]  & \verb`   --emailto "Big Joe <jschmo@BigU.edu>"` \\
\Clunk[MK116]  & \verb`   --plan timed` \\
\Clunk[MK117]  & \verb`   --smtpserver "mailbox@mailserver,com"` \\
\Clunk[MK118]  & \verb`   --smtpport 465` \\
\Clunk[MK119]  & \verb`   --smtpuser jschmo` \\
\Clunk[MK120]  & \verb`   --smtppass qwertyuiop` \\
\Clunk[MK121]  & \verb`   --ups UPS-123` \\
\Clunk[MK122]  & \verb`   --upsdname localhost` \\
\Clunk[MK123]  & \verb`   --upsdport 401` \\
\Clunk[MK124]  & \verb`   --upsduser nut-admin` \\
\Clunk[MK125]  & \verb`   --upsdpass sekret` \\
\Clunk[MK126]  & \verb`If this configuration is correct, enter yes to proceed, anything else to exit:` \\
\end{LinePrinter}
\end{center}

If the proposed configuration values are satisfactory, you reply
\texttt{yes}, but if they are not right for you, you hit
\textsf{Enter} and rerun the script using the options to specify your
preferred values.

The status is ``experimental''. The script is intended for
demonstration and experiment.  The license is GPL v3 or later at your
choice, with support in the \mailinglist.

Let's look at these arguments in more detail.  

\begin{description}

\item[\texttt{-h, -\/-help}] \hspace{7mm} Show this help message and exit.

\item[\texttt{-\/-configurationfile} \ttit{<filename>}] \hspace{5mm}
  The file which holds \UPSmon's configuration.  E.g. A Debian
  sysadmin might use \texttt{/etc/nut/UPSmon.conf}

\item[\texttt{-\/-clientcertfile} \ttit{<filename>}] \hspace{5mm}
  The file which holds the client's public TLS certificate required to
  access the server \upsd, possibly with \upsdTLS.  E.g. A Debian
  sysadmin might use \texttt{/etc/nut/bigbox-client.cert.pem}

\item[\texttt{-\/-emailfrom} \ttit{<string>}] \hspace{7mm} The email
  address from which messages will be sent. \\ E.g.
  \texttt{"<bigserver@bigU.edu>"} Note the email convention of placing
  the address in angle brackets, and the double quotes needed to
  prevent Bash from interpreting the angle brackets.

\item[\texttt{-\/-emailto} \ttit{<string>}] \hspace{7mm} The email
  address of the person to whom messages will be sent. \\ E.g.
  \texttt{"Big Joe <jschmoe@bigU.edu>"} Note the email convention of
  placing the address in angle brackets, and the double quotes needed
  to prevent Bash from interpreting the angle brackets.

\item[\texttt{-\/-plan standard|timed}] \hspace{5mm} Specify standard
  or timed shutdown plan. Valid options are \texttt{standard} or
  \texttt{timed}.

\item[\texttt{-\/-smtppass} \ttit{<string>}] \hspace{7mm} The password
  for your account on the e-mail server. E.g. \texttt{qwertyuiop}
  . This definitely needs changing.

\item[\texttt{-\/-smtpport} \ttit{<integer>}] \hspace{7mm} Your e-mail
  server's TLS port. E.g. \texttt{465} . Communication with the mail
  server is always TLS encrypted.

\item[\texttt{-\/-smtpserver} \ttit{<domain>}] \hspace{7mm} Your
  e-mail server. \\ E.g. \texttt{mailbox.mailserver.com}

\item[\texttt{-\/-smtpuser} \ttit{<name>}] \hspace{6mm} Your sign-in
  account name on the e-mail server. \\ E.g.
  \texttt{mailbox@mydomain.{\allowbreak}com}

\item[\texttt{-\/-ups} \ttit{<name>}] \hspace{7mm} The name of your
  UPS, for example \texttt{UPS\_123}.  If you have more than one UPS
  unit then create a configuration file for the first, and then extend
  it using copy/paste of the actions for the second.

\item[\texttt{-\/-upsdname} \ttit{<name>}] \hspace{3mm} The name of
  the system on which \upsd\ runs. E.g. \texttt{localhost} if
  \UPSmon\ and \upsd\ run on the same machine.

\item[\texttt{-\/-upsdpass} \ttit{<string>}] \hspace{7mm} The password
  for this upsd user, as given in \upsdusers. \\ Do you remember the
  \texttt{password = sekret} on line \ref{LP121}?

\item[\texttt{-\/-upsdport} \ttit{<integer>}] \hspace{7mm} The TLS
  port used by \upsd\ possibly with shim \upsdTLS. E.g. \texttt{401}

\item[\texttt{-\/-upsduser} \ttit{<name>}] \hspace{7mm} User for this
  UPS, as given in \upsdusers. E.g.  \texttt{nut-admin} on line
  \ref{LP120}

\item[\texttt{-v}, \texttt{-\/-version}] \hspace{7mm} Show program and
  Python versions, then exit.

\end{description}

%\newcolumn
\subsection{\Hsep\ \UPSmonconf\ configuration examples}\label{section:confex}

Let's look at a shutdown plan generated by \mkUPSmonconf.

\subsubsection{\Hsep\ Timed shutdown plan, part 1 of 4, the introduction}\label{section:confex.1}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.12\LinePrinterwidth]
\Clunk[ST200]  & \verb`# UPSmon.conf timed shutdown plan generated by mkUPSmonconf.py version 1.3` \\
               & \verb`              on 2022-09-03 17:18:48.202107` \\
\Clunk[ST201]  & \verb`# Python version 3.9.2 (default, Feb 28 2021, 17:03:44)  [GCC 10.2.1 20210110]` \\
\Clunk[ST202]  & \verb`# Calling command:` \\
               & \verb`./mkUPSmonconf.py --plan timed --ups UPS-1 --upsdname localhost --upsdport 401` \\
               & \verb`  --clientcertfile /etc/nut/titan-client.cert.pem --upsduser nut-admin`\\
               & \verb`  --upsdpass sekret --smtpserver mail.gandi.net --smtpport 465 --smtppass qwerty`\\
               & \verb`  --smtpuser mailbox@rogerprice.org --configurationfile /etc/nut/UPSmon.conf` \\
               & \verb`  --emailfrom "<UPSmon@rogerprice.org>" --emailto "Price <roger@rogerprice.org>"` \\
\Clunk[ST204]  & \verb`# Documentation: http://rogerprice.org/NUT/ConfigExamples.A5.pdf` \\
\Clunk[ST203]  & \verb`# Support: nut-upsuser mailing list.` \\
               & \\
\Clunk[ST205]  & \verb`# All groups share the same POLLFREQ and POLLFREQALERT and e-mail relay` \\
\Clunk[ST206]  & \verb`POLLFREQ 5.0  POLLFREQALERT 5.0` \\
\Clunk[ST207]  & \verb`SMTPSERVER «mail.gandi.net» PORT 465` \\
\Clunk[ST237]  & \verb`     USER «mailbox@rogerprice.org» PASSWORD «qwertyuiop»` \\
               & \\
\Clunk[ST208]  & \verb`# Named messages  Let hostname = hostname is built in.` \\
\Clunk[ST209]  & \verb`LET banner        = ⸢[%(b)s] UPS=%(u)s charge=%(c)s event=%(e)s⸥` \\
\Clunk[ST213]  & \verb`LET Msg-COMM      = banner " I have re-established communication with this UPS."` \\
\Clunk[ST214]  & \verb`LET Msg-NOCOMM    = banner " I have lost communication with this UPS."` \\
\Clunk[ST215]  & \verb`LET Msg-OL        = banner " Power restored, shutdown cancelled."` \\
\Clunk[ST216]  & \verb`LET Msg-RB        = banner " Battery needs replacement."` \\
\Clunk[ST217]  & \verb`LET Msg-shutdown  = banner " On battery, shutting down now ..."` \\
\Clunk[ST218]  & \verb`LET Certfile      = «/etc/nut/titan-client.cert.pem»` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Timed shutdown plan, part 1 of 4, the introduction.}\label{fig:confex.1}
\end{figure}

Notes on figure \ref{fig:confex.1}

\ol

\li The command used to generate the file is repeated on line \ref{ST202}.

\li The \texttt{POLLFREQ} and \texttt{POLLFREQALERT} on line \ref{ST206} are
the same as \upsmon.  See chapter \ref{section:upsmonconf2}.

\li On line \ref{ST207} the \texttt{PORT} number corresponds to a TLS port.
Communication with the email service provider is always TLS encrypted.

\li On lines \ref{ST207}-\ref{ST237} the \texttt{«}...\texttt{»} is added
automatically by the \mkUPSmonconf\ script.  You do not have to do this.

\li Line \ref{ST218} corresponds to a Debian installation.  See table
\ref{fig:UD} for a list of possible directories.

\eol

\subsubsection{\Hsep\ Timed shutdown plan, part 2 of 4, the shutdown}\label{section:confex.2}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[ST300]  & \verb`# The local UPS units` \\
\Clunk[ST301]  & \verb`GROUP LOCAL HOST localhost PORT 401 CERTFILE Certfile` \\
\Clunk[ST302]  & \verb`MONITOR UPS-1 POWERVAL 1 UPSDUSER nut-admin PASSWORD «sekret» TYPE primary` \\
               & \\
\Clunk[ST303]  & \verb`# Timed plan additional messages and actions` \\
\Clunk[ST304]  & \verb`LET Msg-2-min = banner " On battery, shutdown in 2 mins, save your work ..."` \\
\Clunk[ST305]  & \verb`LET Msg-1-min = banner " On battery, shutdown in 1 min, save your work ..."` \\
\Clunk[ST306]  & \verb`WHEN UPS-1 REPORTS OL->OB :   NOTIFY Msg-2-min NUTLOG Msg-2-min` \\
\Clunk[ST307]  & \verb`                              STARTTIMER two-min 120 STARTTIMER one-min 60` \\
\Clunk[ST308]  & \verb`WHEN UPS-1 TIMEOUT one-min :  NOTIFY Msg-1-min NUTLOG Msg-1-min WALL Msg-1-min` \\
\Clunk[ST309]  & \verb`                              EMAIL FROM « <UPSmon@rogerprice.org> »` \\
\Clunk[ST310]  & \verb`                                    TO   « Roger Price <roger@rogerprice.org> »` \\
\Clunk[ST311]  & \verb`                                    SUBJECT «Msg-1-min»` \\
\Clunk[ST312]  & \verb`                                    MESSAGE «Msg-1-min»` \\
\Clunk[ST313]  & \verb`WHEN UPS-1 TIMEOUT two-min :  NOTIFY Msg-shutdown NUTLOG Msg-shutdown` \\
\Clunk[ST314]  & \verb`                              WALL Msg-shutdown STARTTIMER final-delay 5` \\
\Clunk[ST315]  & \verb`WHEN UPS-1 REPORTS OB->OL :   NOTIFY Msg-OL NUTLOG Msg-OL WALL Msg-OL` \\
\Clunk[ST316]  & \verb`                              CANCELTIMER two-min CANCELTIMER one-min`\\
               & \verb`                              CANCELTIMER final-delay` \\
\Clunk[ST317]  & \verb`# End of timed plan additional actions` \\
               & \\
\Clunk[ST318]  & \verb`# Shutdown on low battery` \\
\Clunk[ST319]  & \verb`WHEN UPS-1 REPORTS None->LB : NOTIFY Msg-shutdown NUTLOG Msg-shutdown` \\
\Clunk[ST320]  & \verb`                              WALL MSG-shutdown STARTTIMER final-delay 5` \\
\Clunk[ST321]  & \verb`WHEN UPS-1 TIMEOUT final-delay : SHUTDOWNCMD "/sbin/shutdown -h 0"` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Timed shutdown plan, part 2 of 4, the shutdown.}\label{fig:confex.2}
\end{figure}

Notes on figure \ref{fig:confex.2}

\ol

\li Line \ref{ST301} introduces the notion of ``\texttt{GROUP}''.  In general
a group is a set of UPS units which are attached to the same \upsd\ server.
In NUT's \upsmonconf\ the \texttt{MONITOR} \textit{system} declaration
identifies the \upsd\ host system and the port. See \NUTman{upsmon.conf}.
\UPSmonconf\ transfers the host system and port identification to a named
group, and adds the \texttt{CERTFILE} declaration.

\li Line \ref{ST302} resembles the \upsmonconf\ declaration, but with the
inclusion of additional keywords for clarification. ``\texttt{UPS-1}''
declares the UPS name, the \texttt{HOST} and \texttt{PORT} have already been
declared.  The UPS name should correspond to the name specified in \upsconf.
See line \ref{LP100}.

\li Since this is the timed plan rather than the standard plan, we need
additional messages which are declared on lines \ref{ST304}-\ref{ST305}.

\li When event \EVENT{\OL}{\OB} arrives, lines \ref{ST306}-\ref{ST307} call for
the ``on battery'' message to be put on-screen and in the NUT log file. The
actions also declare the timers \texttt{two-min} and \texttt{one-min} and
start them.

\li When timer \texttt{one-min} runs out, lines \ref{ST308}-\ref{ST312} place
warnings on screen, in the NUT log file and on all logged in terminals.  The
actions also send an email to the administrator.

\li When timer \texttt{two-min} runs out, lines \ref{ST313}-\ref{ST314} place
warnings on-screen, in terminals and in the NUT log file.  A short
\texttt{final-delay} timer is declared and started.  This timer corresponds to
\texttt{FINALDELAY} in \upsmonconf.

\li What happens if power returns before the shutdown?  If event
\EVENT{\OB}{\OL} arrives, lines \ref{ST315}-\ref{ST316} notify the user, place a
message in the NUT log file and turn off all the timers.

\li Whether the plan is ``standard'' or ``timed'' the local system must be
shutdown on event \EVENT{\None}{\LB}.  This happens on lines
\ref{ST319}-\ref{ST320}.  Users receive a final on-screen warning, a message
goes into the NUT log file and the action declares and starts a short
\texttt{final-delay} timer.

\li When the \texttt{final-delay} timer runs out, line \ref{ST321} calls for a
system shutdown.

\eol

\subsubsection{\Hsep\ Timed shutdown plan, part 3 of 4, warnings}\label{section:confex.3}

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[ST400]  & \verb`# Warning for battery replacement` \\
\Clunk[ST401]  & \verb`WHEN UPS-1 REPORTS None->RB : STARTTIMER rbwarntime 43200` \\
\Clunk[ST4a1]  & \verb`                              NUTLOG Msg-RB NOTIFY Msg-RB` \\
\Clunk[ST402]  & \verb`                              EMAIL FROM « <UPSmon@rogerprice.org> »` \\
\Clunk[ST403]  & \verb`                                    TO   « Roger Price <roger@rogerprice.org> »` \\
\Clunk[ST404]  & \verb`                                    SUBJECT «Msg-RB»` \\
\Clunk[ST405]  & \verb`                                    MESSAGE «Msg-RB»` \\
\Clunk[ST406]  & \verb`WHEN UPS-1 TIMEOUT rbwarntime : STARTTIMER rbwarntime 43200` \\
               & \verb`                                NUTLOG Msg-RB NOTIFY Msg-RB` \\
\Clunk[ST407]  & \verb`WHEN UPS-1 REPORTS RB->None : CANCELTIMER rbwarntime` \\
               & \\
\Clunk[ST408]  & \verb`# Warning that UPSmon has lost UPS UPS-1.  Shut down on NOCOMM when OB.` \\
\Clunk[ST409]  & \verb`WHEN UPS-1 REPORTS COMM->NOCOMM : STARTTIMER nocommwarntime 300` \\
\Clunk[ST410]  & \verb`                                  IF OL->OB NOTIFY Msg-shutdown` \\
\Clunk[ST411]  & \verb`                                  IF OL->OB NUTLOG Msg-shutdown` \\
\Clunk[ST412]  & \verb`                                  IF OL->OB WALL Msg-shutdown` \\
\Clunk[ST413]  & \verb`                                  IF OL->OB STARTTIMER final-delay 5` \\
\Clunk[ST414]  & \verb`WHEN UPS-1 TIMEOUT nocommwarntime : NUTLOG Msg-NOCOMM NOTIFY Msg-NOCOMM` \\
\Clunk[ST415]  & \verb`WHEN UPS-1 REPORTS NOCOMM->COMM : CANCELTIMER nocommwarntime` \\
               & \verb`                                  NUTLOG Msg-COMM NOTIFY Msg-COMM` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Timed shutdown plan, part 3 of 4, warnings,}\label{fig:confex.3}
\end{figure}

Notes on figure \ref{fig:confex.3}

\ol

\li Some UPS units are capable of reporting that the battery needs
replacement.  On line \ref{ST401}, when event \EVENT{\None}{\RB} arrives,
messages are placed on-screen and in the NUT log file.  Line \ref{ST402} sends
an email to the sysadmin.  The \upsmon\ \texttt{RBWARNTIME} behaviour is
reproduced by defining and starting an \texttt{rbwarntime} timer.

\li Line \ref{ST406} specifies that when the \texttt{rbwarntime} timer runs
out, an on-screen message appears\footnote{Do the users have to be told about
  this?} and also goes into the NUT log file.  The action also restarts the
timer.  It will continue to loop until the status \status{\RB} disappears with
event \EVENT{\RB}{\None} on line \ref{ST407}

\li The statuses \status{\COMM} and \status{\NOCOMM} are not due to \upsd.
They are generated internally by \UPSmon\ when it has problems talking to
\upsd.  The \texttt{standard} and \texttt{timed} configurations discussed here
have been tested with \upsd\ and \UPSmon\ running in the same machine, but in
general this is not the case, and network problems become more apparent when
\upsd\ and \UPSmon\ are separated.

The event \EVENT{\COMM}{\NOCOMM} starts a timer which will later place a
warning message in front of users and in the NUT log file.  This follows the
\upsmon\ logic.  Additionally, and again following \upsmon\ logic, a shutdown
procedure will begin if the system is currently running on battery.  See lines
\ref{ST410}-\ref{ST413}.  Note that the condition must be attached to each of
the actions.

Note the subtle difference between \upsmon\ and \UPSmon. See figure
\ref{fig:upsmonconf5}.  On line \ref{LP231} daemon \upsmon\ will trigger a
\NOTev{\NOCOMM}\ NOTIFY event after \texttt{NOCOMMWARNTIME} seconds if it
can't reach \textbf{any} of the UPS entries in configuration file \upsmonconf.
\UPSmon\ does this for each UPS individually.  The difference is slight if
there is only one UPS :-)

\li On line \ref{ST415} the timer \texttt{nocommwarntime} is cancelled and
suitable messages send to the users\footnote{Is it really necessary to notify
  the users of this technical matter?} and the NUT log file.

\eol

\newcolumn
\subsubsection{\Hsep\ Timed shutdown plan, part 4 of 4, heartbeat}\label{section:confex.4}

\begin{wrapfigure}{l}{0.39\LinePrinterwidth}
\vspace{-5mm}
\begin{center}
\begin{LinePrinter}[0.29\LinePrinterwidth]
\Clunk         & \verb`# heartbeat.conf`  \\
\Clunk         & \verb`# 20 minute heartbeat`  \\
\Clunk[ST450]  & \verb`ups.status: TICK`  \\
\Clunk[ST451]  & \verb`TIMER 600`  \\
\Clunk[ST452]  & \verb`ups.status: TOCK`  \\
\Clunk[ST453]  & \verb`TIMER 600`  \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Configuration file \heartbeatconf}\label{fig:heartbeatconf6}
\vspace{-3mm}
\end{wrapfigure}

\textsl{The NUT software runs in the background for weeks, months without
  difficulty and with no messages going the system administrator.  ``All is
  well!'', but is it?}  

\textsl{NUT is a collection of pieces and interconnecting protocols.  What if
  one of these pieces has stopped or the protocol blocked?  We need something
  that will check regularly that all is indeed well.  The proposed heartbeat
  does this job.}

Heartbeat definitions are not provided by NUT, you have to create them
for yourself.  Create the new file \heartbeatconf\ as shown in figure
\ref{fig:heartbeatconf6} in the same directory as \upsconf.  As called
for by line \ref{LP464a}, the heartbeat will cycle continuously
through this script.

For good security, only users upsd/nut and root should have write
access to this file.

\begin{wrapfigure}{l}{0.45\LinePrinterwidth}
\vspace{-9mm}
\begin{center}
\begin{LinePrinter}[0.35\LinePrinterwidth]
\Clunk[ST462]  & \verb`[heartbeat]` \\
\Clunk[ST463]  & \verb`  driver = dummy-ups` \\
\Clunk[ST464]  & \verb`  port = heartbeat.conf` \\
\Clunk[LP464a] & \verb`  mode = dummy-loop` \\
\Clunk[ST465]  & \verb`  desc = "Watch over NUT"` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Addition to the file \upsconf\ for \heartbeatconf}\label{fig:heartbeatconf5}
\vspace{-3mm}
\end{wrapfigure}

Lines \ref{ST450} and \ref{ST452} flip the \texttt{ups.status} value between
\status{\TICK} and \status{\TOCK}.

Lines \ref{ST451} and \ref{ST453} place a 10 minute time interval between each
status change. $2\times 600 sec = 20 min$, the heartbeat period.

You must also declare to \upsd\ that it is to generate the heartbeat.  Add the
declaration shown in figure \ref{fig:heartbeatconf5} to file \upsconf.  In
line \ref{ST463} we see the driver used to generate the heartbeat.  This
driver is also used for debugging.  You can amuse yourself by adding further
status changes and observing their effect.

\vspace{6mm}
Notes on figure \ref{fig:confex.4}:
\vspace{3mm}

\ol

\li On line \ref{ST503} a group ``\texttt{HB}'' is declared to contain the
heartbeat UPS.  The \texttt{HOST}, \texttt{PORT} and \texttt{CERTFILE} are the
same as for the physical UPS.

\li Lines \ref{ST504}-\ref{ST505} declare messages specific to the heartbeat.

\li Other than the \texttt{POWERVAL} of 0, the \texttt{MONITOR} declaration on
line \ref{ST506} is the same as for the physical UPS.

\li Line \ref{ST507} says that the heartbeat does not require electrical
energy.  This zero declaration also circumvents certain sanity checks that
real UPS's must pass.

\li Lines \ref{ST508} and \ref{ST510} manage the timers which watch over the
\status{\TICK} and \status{\TOCK} coming from \upsd.  The timer is longer
than the expected interval between status arrivals.  If this timer expires we
assume that the heartbeat has failed.

\li If you uncomment the logging of the \EVENT{\None}{\TICK} on line
\ref{ST509} then your log will grow rapidly with a message every 20
minutes.

\li Line \ref{ST512} is a form of ``goto'' so all the heartbeart error logging
is in one place.

\li Lines \ref{ST513}-\ref{ST517} send heartbeat failure messages to the
system administrator and to the NUT log file.

\eol

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[ST500]  & \verb`# Heartbeat operation, requires file heartbeat.conf in the upsd server,` \\
\Clunk[ST501]  & \verb`# and definition of UPS [heartbeat] in ups.conf.  Note that the timer` \\
\Clunk[ST502]  & \verb`# specified here must be longer than the timer in heartbeat.conf.` \\
\Clunk[ST503]  & \verb`GROUP HB HOST localhost PORT 401 CERTFILE Certfile` \\
\Clunk[ST504]  & \verb`LET Msg-HB-start = banner " Event %(e)s Start HB-timer"` \\
\Clunk[ST505]  & \verb`LET MSG-HB-fails = banner " %(u)s FAILURE."` \\
               & \verb`                   " I have not received expected TICK/TOCK status change."` \\
\Clunk[ST506]  & \verb`MONITOR heartbeat POWERVAL 0 UPSDUSER nut-admin PASSWORD «sekret» TYPE primary` \\
\Clunk[ST507]  & \verb`MINSUPPLIES 0` \\
\Clunk[ST508]  & \verb`WHEN heartbeat REPORTS None->TICK : CANCELTIMER tock-timer` \\
\Clunk         & \verb`                                    STARTTIMER tick-timer 660` \\
\Clunk[ST509]  & \verb`#                                    NUTLOG Msg-HB-start` \\
\Clunk[ST510]  & \verb`WHEN heartbeat REPORTS None->TOCK : CANCELTIMER tick-timer` \\
               & \verb`                                    STARTTIMER tock-timer 660` \\
               & \\
\Clunk[ST511]  & \verb`# What to do if the heartbeat fails` \\
\Clunk[ST512]  & \verb`WHEN heartbeat TIMEOUT tick-timer : STARTTIMER tock-timer 0.5` \\
\Clunk[ST513]  & \verb`WHEN heartbeat TIMEOUT tock-timer : NUTLOG MSG-HB-fails  NOTIFY MSG-HB-fails` \\
\Clunk[ST514]  & \verb`                                    EMAIL FROM « <UPSmon@rogerprice.org> »` \\
\Clunk[ST515]  & \verb`                                          TO   « Price <roger@rogerprice.org> »` \\
\Clunk[ST516]  & \verb`                                          SUBJECT «Msg-HB-fails»` \\
\Clunk[ST517]  & \verb`                                          MESSAGE «Msg-HB-fails»` \\
\Clunk[ST518]  & \verb`# End of file` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Timed shutdown plan, part 4 of 4, heartbeat.}\label{fig:confex.4}
\end{figure}

\subsubsection{\Hsep\ Standard shutdown plan}\label{section:confex.5}

The only differences between the standard plan and the timed shutdown plan are
that the standard plan removes lines \ref{ST303}-\ref{ST317} and replaces then
with lines \ref{ST602}-\ref{ST603}.  These actions send a warning message to
the users and to the NUT log file.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[ST601]  & \verb`# Standard plan specific actions` \\
\Clunk[ST602]  & \verb`LET Msg-OB = banner " Power failure, possible shutdown, save your work ..."` \\
\Clunk[ST603]  & \verb`WHEN UPS-1 REPORTS OL->OB :   NOTIFY Msg-OB NUTLOG Msg-OB WALL Msg-OB` \\
\Clunk[ST604]  & \verb`# End of standard plan specific actions` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Standard shutdown plan differences}\label{fig:confex.5}
\end{figure}

\subsection{\Hsep\ Redundant power supplies}\label{section:redundant}

\textit{Please see section \ref{section:dual} and sections ``Power values''
  and ``Redundant power supplies'' in \NUTman{upsmon}.  The \upsmon\ logic is
  built into the code rather than the configuration file and follows the
  spirit of the standard shutdown plan preferred by \upsmon.}

\UPSmon\ allows the system administrator to customise the logic using the
configuration file.

\subsubsection{\Hsep\ \texttt{MINSUPPLIES} failure: Timed shutdown plan}\label{section:redundant.timed}

The configuration for a timed shutdown plan for redundant power supplies is
very similar to a \EVENT{\None}{\OB} timed shutdown : the status \status{\LS}
meaning ``Low Supplies'' replaces the status \status{\OB}.  \status{\LS} says
that within a given group, the total powervalue of the UPS units with status
\status{\OL} is not sufficient to meet the \texttt{MINSUPPLIES} criterion.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[LS601]  & \verb`# Timed shutdown on MINSUPPLIES failure` \\
\Clunk[LS602]  & \verb`LET Msg-LS = banner " Powervalue failure.  MINSUPPLIES not satisfied."` \\
\Clunk[LS603]  & \verb`WHEN UPS-1 REPORTS None->LS : NOTIFY Msg-LS    NUTLOG Msg-LS    WALL Msg-LS` \\
\Clunk[LS604]  & \verb`                              EMAIL FROM « <UPSmon@rogerprice.org> »` \\
\Clunk[LS605]  & \verb`                                    TO   « Roger Price <roger@rogerprice.org> »` \\
\Clunk[LS606]  & \verb`                                    SUBJECT «Msg-LS»` \\
\Clunk[LS607]  & \verb`                                    MESSAGE «Msg-LS»` \\
\Clunk[LS608]  & \verb`                              NOTIFY Msg-2-min NUTLOG Msg-2-min WALL Msg-2-min` \\
\Clunk[LS609]  & \verb`                              STARTTIMER two-min 120 STARTTIMER one-min 60` \\
\Clunk[LS610]  & \verb`WHEN UPS-1 REPORTS LS->None : NOTIFY Msg-OL    NUTLOG Msg-OL    WALL Msg-OL` \\
\Clunk[LS611]  & \verb`                              CANCELTIMER two-min CANCELTIMER one-min` \\
\Clunk[LS612]  & \verb`                              CANCELTIMER final-delay` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{Timed shutdown on \texttt{MINSUPPLIES} failure}\label{fig:redundant.timed}
\end{figure}

\subsubsection{\Hsep\ \texttt{MINSUPPLIES} failure: Standard shutdown plan}\label{section:redundant.standard}

Shutting down a redundant system using the \upsmon\ logic of waiting for
\status{\LB} is left as as exercise for the reader.  \textit{If that's what
  you really want, why not go on using \upsmon?}

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-4.jpg, height=36mm}
\end{center}

\vspace*{\fill}

\newcolumn
\section{\Hsep\ \UPSmon\ installation checklist}\label{section:checklist}

Here is the editor's checklist of the things to do to install and run
\UPSmon.

\ol

\li Check that you have Python 3.6, or more recent, running.  No? You
will need to install it.

\li Check that you have OpenSSL 1.1.1d or better.

\li Download \UPSmon, \upsdTLS, \mkNUTcert\ and \mkUPSmonconf\ from
\href{http://rogerprice.org/NUT}{rogerprice.{\allowbreak}org/NUT} to
wherever you put Python3 scripts.

\li Review the shebangs at the top of the Python3 scripts.  Modify if
needed to meet the local situation.  The shebangs that come with the
scripts are those used by the editor.  Yours may well be different.

\li Create symlink from \texttt{/usr/sbin/UPSmon.py} to wherever you
put the Python3 scripts.  Create similar links for \upsdTLS,
\mkNUTcert\ and \mkUPSmonconf.

\li Install the systemd service unit
\texttt{/etc/systemd/system/nut-py-server-shim.service} and the
\texttt{/etc/{\allowbreak}systemd/{\allowbreak}system/nut-py-monitor.service}
service unit. See section \ref{section:UPrun}.

\li Add programs \texttt{shutdown}, \texttt{wall} and
\texttt{notify-send} to \texttt{/etc/sudoers} for users
\texttt{nut}/\texttt{upsd}.  See section
\ref{section:notifysend.sudoer}.

\li Run \mkNUTcert\ to make TLS certificates. See chapter \ref{section:TLS}.

\li Run \mkUPSmonconf\ to create the \UPSmon\ configuration file.  See
section \ref{section:mkUPSmonconf}.

\li Install \texttt{/etc/logrotate.d/NUT} . See appendix
\ref{section:logrotate},

\li Check that \heartbeatconf\ is installed in the \upsd\ machine and
that \upsconf\ contains a \texttt{[heartbeat]} declaration.

\li Stop and disable the \texttt{nut-monitor} service unit.

\li Run \texttt{systemctl daemon-reload} and enable the
\texttt{nut-py-server-shim} service unit and the
\texttt{nut-py-monitor} service unit. Start the
\texttt{nut-py-server-shim} and then the \texttt{nut-py-monitor}
service units.

\li Check output of command \texttt{ps -elf | grep -E "nut|upsd"}
which on an openSUSE machine gives the output shown in figure
\ref{fig:runtime}.

\begin{figure}[ht]
\begin{center}
\begin{LinePrinter}[1.1\LinePrinterwidth]
\Clunk[ST700]  & \verb`1 S upsd 2873 1  9447 -       /usr/lib/ups/driver/usbhid-ups -a Eaton` \\
\Clunk[ST701]  & \verb`1 S upsd 2878 1  5019 -       /usr/lib/ups/driver/dummy-ups -a heartbeat` \\
\Clunk[ST702]  & \verb`1 S upsd 2882 1  5017 -       /usr/sbin/upsd` \\
\Clunk[ST703]  & \verb`5 S upsd 2887 1 17189 core_s  /usr/local/bin/python3.8 -u /usr/sbin/upsdTLS.py` \\
\Clunk[ST704]  & \verb`5 S upsd 2892 1 58813 -       /usr/local/bin/python3.8 -u /usr/sbin/UPSmon.py` \\
\end{LinePrinter}
\end{center}
\vspace{-6mm}
\caption{\upsd\ and \UPSmon\ runtime processes}\label{fig:runtime}
\end{figure}

\eol

\vspace*{\fill}
\hfill Questions? Try the \mailinglist.\hfill
\vspace*{\fill}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                        %
%                            P A R T  4                                  %
%                                                                        %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage

% Layout for the body.  See the LaTeX Companion, p.96.
%   Even numbered page           Centre fold        Odd numbered page
% ,-------------------------------------------------------------------,
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% |-----------------------------------|-------------------------------|
% |             Text area             |           Text area           |
% |-----------------------------------|-------------------------------|
% | left-even  centre-even right-even | left-odd centre-odd right-odd | 
% '-------------------------------------------------------------------'
\lhead[The End]{The End}                                       % \lhead[left-header-even]{left-header-odd}
%\chead[ConfigExamples \Version]%
%      {ConfigExamples \Version}                               % \chead[centre-header-even]{centre-header-odd}
%\rhead[Build \isodate]{Build \isodate}                        % \rhead[right-header-even]{right-header-odd}
%\lfoot[]{}                                                    % \lfoot[left-footer-even]{left-footer-odd}
%\cfoot[\fancyplain{}{Page \thepage\ of \pageref{LastPage}}]%
%      {\fancyplain{}{Page \thepage\ of \pageref{LastPage}}}   % \cfoot[centre-footer-even]{centre-footer-odd}
%\rfoot[]{}                                                    % \rfoot[right-footer-even]{right-footer-odd}

\begin{center}
\addtocontents{toc}{\protect\vspace{3mm}}
\part[\hspace{\fill}\textsf{The End}\hspace{\fill}]{}\label{part:End}
\addtocontents{toc}{\protect\vspace{3mm}}
\vspace{5mm}
\textsf{\huge{The End}}
\vspace{7mm}
\end{center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\clearpage    
%\newcolumn
\section{\Hsep\ Acknowledgments}\label{acks}

Editor: As one of the many who have used the work of the NUT project as part
of their system setup, I would like to express my gratitude and my
appreciation for the software that the NUT project has made available to
system administrators through contributions by Charles Lepple, Arjen de Korte,
Arnaud Quette, Jim Klimov, Russell Kroll, and many others in the nut-upsuser
mailing list.

I would also like to thank those who commented on earlier versions of this
text: M.B.M.

\vspace*{\fill}

\begin{center}
   \epsfig{file=UPS-2.jpg, height=36mm}
\end{center}

\vspace*{\fill}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{\Hsep\ Errors, omissions, obscurities, confusions, typpos...}\label{bugs}

\begin{wrapfigure}[6]{r}{72mm}
\vspace{-3.5mm}
\fbox{\begin{minipage}{69mm}{\small
      \textsl{Joe's server will still be allright} \\
      \textsl{if power drops off in the night.} \\
      \textsl{\hspace*{5mm}That 8 year old pack} \\
      \textsl{\hspace*{5mm}of battery back-} \\
      \textsl{up will easily handle th} \texttt{connection lost}}
      \end{minipage}}
\end{wrapfigure}

Please signal errors, omissions, typso and all the other problems you find in
this document in the \mailinglist.  Thank you.

\vspace{10mm}
\hspace{30mm}\epsfig{file=UPS-3.jpg, height=36mm}

\vspace*{\fill}

\label{LastPage}

\end{document}