forked from NUT-RogerPrice/ConfigExamples
-
Notifications
You must be signed in to change notification settings - Fork 4
/
ConfigExamples.tex
8692 lines (7093 loc) · 388 KB
/
ConfigExamples.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
%% 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]