[[Vorlage(getestet, focal)]]
[[Vorlage(Fortgeschritten)]]

{{{#!vorlage Wissen
[:Pakete installieren: Installation von Programmen]
[:Packprogramme: Archive entpacken]
[:Terminal: Ein Terminal öffnen]
[:Editor: Einen Editor öffnen]
[:Rechte: Rechte für Dateien und Ordner ändern]
}}}

[[Inhaltsverzeichnis(1)]]

[[Bild(./nut_logo.png, 48, align=left)]]
[https://networkupstools.org/ NUT] {en} steht für Network UPS Tools und ist ein Client/Server-Framework zur Ansteuerung und Verwaltung einer [:USV:] (unterbrechungsfreie Stromversorgung, englisch: UPS). Unterstützt werden [https://networkupstools.org/stable-hcl.html über 100 verschiedene Hersteller und Modelle] {en}. Die Kernprogrammkomponenten arbeiten als [:Dienste:Systemdienst] (Daemon), d.h. diese werden automatisch beim Einschalten des Rechners gestartet und arbeiten im Hintergrund. NUT kann dabei beim heimischen PC ebenso eingesetzt werden, wie bei einzelnen Servern oder bis zu umfangreichen Konstellationen, welche aus mehreren Servern und mehreren USVs bestehen.

Zunächst sollte geklärt werden, ob man ein zur USV passendes (serielles oder USB-) Kabel hat. Bauanleitungen für evtl. fehlende Kabel findet man auf der [https://networkupstools.org/cables.html Projektseite] {en}.

Das Konfigurieren und Testen der USV sollte anfangs nur passiv geschehen. Das heißt, dass die USV nur über das Datenkabel angeschlossen ist. Diese Anleitung behandelt beispielhaft eine Konstellation mit zwei Servern, die durch eine USV geschützt werden sollen.

NUT besteht aus diesen Kernprogrammen:

 * '''upsd''' - ist das Serverprogramm und läuft auf dem Rechner, der direkt (z.B. über USB) mit der USV verbunden ist. Alle Kommunikation mit der USV läuft hierüber
 * '''upsmon''' - ist der Client (mon steht für engl. monitoring). Dieser verbindet sich mit upsd und reagiert auf Statusänderungen der USV in Form von Benachrichtigungen oder  Aktionen (z.B. gezieltes Herunterfahren des Rechners)
 * '''upssched''' - Scheduler (Zeitplaner) für den upsmon

= Vorüberlegungen =
Die Struktur der USV-Absicherung sollte überlegt sein. In einer solchen Struktur gibt es vier Arten von Geräten / Rechnern:

(A) – Die Stromversorgung es Rechners ist durch die USV abgesichert (zumindests solange der Akku durchhält).

(B) – Der Rechner ist durch die USV abgesichert – wie (A) – ist aber gleichzeitig kommunikationstechnisch (z.B. per USB) direkt mit der USV (oder in komplexeren Strukturen vielleicht sogar mit mehreren) verbunden.

(C) – Der Rechner ist weder durch die USV geschützt noch mit ihr verbunden.

(D) – Die Stromversorgung des Rechners ist unabhängig von der USV. Er ist aber kommunikationstechnisch mit ihr verbunden. Ein sehr ungewöhnlicher Fall.

Das einfachste Szenario ist: Es gibt einen einzigen Rechner, der mit der USV abgesichtert werden sollt. Dieser Rechner fällt in Kategorie B.

Ein typisches Szenario ist: Es gibt ein B und viele A und möglicherweise noch C-Geräte.

Für komplexere Strukturen gibt es ausführliche Anleitungen und Beispiele auf der Projektseite. In so einem Fall sollte man sich zunächst einen Plan machen.

Folgendes muss bzw. kann nun auf diesen Geräten installiert, bzw. konfiguriert werden:

(A) – upsmon, optional: upssched

(B) – upsd, upsmon, optional: upssched

(C) – optional: upsmon, upssched

(D) – upsd, optional: upsmon

= Installation =
Folgendes Paket wird für die Installation in allen Fällen verwendet [1]:

{{{#!vorlage Paketinstallation
nut
}}}

Optional können weitere Zusatzpakete installiert werden:

{{{#!vorlage Paketinstallation
nut-cgi, Weboberfläche, [#Administrative-Werkzeuge siehe unten]
nut-snmp, [wikipedia:Simple_Network_Management_Protocol:SNMP]-Überwachung
nut-xml, universe, für spezielle Modelle von Eaton oder MGE
nut-ipmi, universe, für [wikipedia:Intelligent_Platform_Management_Interface:IPMI], ab [:Trusty:Ubuntu 14.04]
}}}

Üblicherweise befinden sich dann die Konfigurationsdateien im Ordner '''/etc/nut''':
 * '''nut.conf'''
 * '''ups.conf'''
 * '''upsd.conf'''
 * '''upsd.users'''
 * '''upsmon.conf'''
 * '''upssched.conf'''

Diese Dateien beinhalten sinnvolle Voreinstellungen und Erklärungen.

Sollten ein oder mehrere Dateien nicht vorhanden sein, kann man die Beispieldateien aus '''/usr/share/doc/nut/examples/''' nach '''/etc/nut/''' kopieren. Damit die Dateien auch genutzt werden können, müssen sie nur noch umbenannt werden: '''.sample''' im Dateinamen löschen. Das Konfigurationsbeispiel von '''upsmon''' muss gegebenenfalls noch entpackt [2] werden. Dies geschieht z.B. mit [3]:

{{{#!vorlage Befehl
gzip -d upsmon.conf.sample.gz 
}}}

Damit ist die Installation abgeschlossen und es kann mit der Konfiguration begonnen werden.

= upsd Server (Typ B oder D) =

Der Serverdienst wird an einem Rechner Typ B oder D installiert.

== Modus konfigurieren ==

Dazu editiert [4] man '''/etc/nut/nut.conf''' wie folgt:

{{{
MODE=netserver
}}}

== Anschluss an USV konfigurieren ==

Dazu editiert man die '''/etc/nut/ups.conf''':

{{{
[ups1]
  driver = "apcsmart"		# Treiber der verwendet werden soll
  port = "/dev/ttyS0"		# Port, an dem die USV angeschlossen ist (hier COM1)
  desc = "Meine USV"		# Beschreibung der USV
}}}

Es gibt noch weitere Parameter, die man hier angeben kann. Diese kann man in der [:man:]-Page von '''ups.conf''' nachlesen. Eine Liste unterstützter USVs und Infos zu den Treibern findet man unter [http://www.networkupstools.org/stable-hcl.html Hardware compatibility list] {en}. (Bei manchen Treibern,z.B. blazer_usb, kann der Port auf "auto" gestellt werden, in diesem Fall, weil USB hier Standard ist).

== Serverdienst upsd konfigurieren ==

Dazu editiert man die '''/etc/nut/upsd.conf'''.

Mit der Option `LISTEN` konfiguriert man, auf welchen IP-Adressbereich der Server hört. In der aktuellen Version von NUT darf hier nur noch ein LISTEN-Eintrag gemacht werden. Im Grunde gibt es zwei Szenarien:

 * Es gibt nur einen Rechner vom Typ B und sonst keine. Auf dem Rechner laufen dann alle Dienste von NUT und upsd muss nur auf den „local host“ hören:
{{{
LISTEN 127.0.0.1
}}}
 * Es gibt neben dem Rechner vom Typ B auch Rechner vom Typ A oder C (auf denen upsmon laufen soll)
{{{
LISTEN 0.0.0.0
}}}

== Benutzer einrichten ==
Dazu editiert man '''/etc/nut/upsd.users'''. Es bietet sich hier an, drei Benutzer anzulegen, und zwar einen '''upsmaster''' (der auf dem Server die Überwachung übernimmt), einen '''upsslave''' (der von den Clients die Überwachung übernimmt) und einen '''upsadmin''' (der Verwaltungsaufgaben übernehmen darf).

{{{
[upsmaster]				# Benutzername
  password = upsmasterpw    		# Passwort für den Benutzer
  upsmon master		         	# Art des Zugriffs*

[upsslave]
  password = upsslavepw
  upsmon slave

[upsadmin]
  password = upsadminpw
  actions = SET
  instcmds = ALL
}}}

Alternativ lassen sich "master" und "admin" auch kombinieren zu:

{{{
[upsmaster]
  password = upsmasterpw
  actions = SET
  instcmds = ALL
  upsmon master

[upsslave]
  password = upsslavepw
  upsmon slave
}}}

{{{#!vorlage Hinweis
Die Benutzer in dieser Datei haben nichts mit den Linux-Benutzern zu tun. Sie regeln nur die Zugriffsrechte von upsmon auf upsd.

Art des Zugriffs - '''master''' oder '''slave''': Müssen die Rechner gezielt heruntergefahren werden, so werden alle upsmon-Instanzen benachrichtigt. Der master wartet zunächst ab, dass alle slave-Rechner das Herunterfahren eingeleitet haben, bevor er selbst damit beginnt. Darum ist typischerweise der Rechner vom Typ B der master und alle Rechner vom Typ A oder C laufen als slave.

(Diese Bezeichnungen gelten nach heutigem Stand als politisch inkorrekt, sind in NUT aber so programmiert)
}}}

== upsmon einrichten ==
Im Fall (B) richten wir auch den Client ein. Im seltenen Fall (D) ist dies optional. Dazu editiert man die '''/etc/nut/upsmon.conf''':

{{{
RUN_AS_USER nut
}}}

Hier wird eingestellt unter welchem User weitere Aktionen ausgeführt werden.

Als nächstes konfiguriert man die Verbindung zum upsd:

{{{
MONITOR ups1@localhost 1 upsmaster upsmasterpw master
}}}

Dies sagt dem upsmon, dass die USV "ups1" am lokalen Rechner (Typ B) mit den Benutzer "upsmaster" und dem Passwort "upsmasterpw" an upsd angemeldet wird.

{{{
MINSUPPLIES 1
}}}

Gibt an, wie viele USVs mindestens verfügbar sein müssen. In den meisten Fällen `1`.

{{{
SHUTDOWNCMD “/sbin/shutdown -h +0“
}}}

Der Befehl zum Herunterfahren des Systems.

{{{
NOTIFYCMD /sbin/upssched
}}}

Gibt an welches Programm gestartet werden soll, wenn ein bestimmtes Ereignis eintritt. Hier kann ein eigenes Skript eingestellt werden oder (wie im Beispiel) upssched. Zu '''upssched''' später mehr. 
	
{{{
POLLFREQ 5
}}}

Ist das Intervall in Sekunden, in dem der Monitor die USV abfragt.

{{{
POLLFREQALERT 5
}}}

Ist das Intervall in Sekunden, in dem der Monitor die USV abfragt, wenn die USV auf Alarm steht (bspw. die USV auf Batterie läuft).

{{{
HOSTSYNC 15
}}}

Ist die Zeit, die der Server wartet, dass die Clients ihre Verbindung trennen können, wenn FSD gesetzt worden ist (FSD wird gesetzt wenn z.B. die Batterie fast leer ist).

{{{
DEADTIME 15
}}}

Die Zeit die gewartet wird, wenn die USV nicht erreichbar ist (bevor sie als nicht verfügbar gilt). Sollte das 3-fache von ``POLLFREQ`` und ``POLLFREQALERT`` sein.

{{{
POWERDOWNFLAG /etc/killpower
}}}

Diese Datei wird vom Monitor erstellt, wenn der Rechner herunterfahren soll.

{{{
NOTIFYMSG ONLINE "USV-ONLINE"
NOTIFYMSG ONBATT "USV-AUF-BATTERIE"
# und so weiter ...
}}}

Hier werden die Nachrichtentexte für bestimmte Ereignisse deklariert. Ereignisse können sein:

 * ONLINE	- USV bekommt wieder externen Strom
 * ONBATT	- USV läuft auf Batteriebetrieb
 * LOWBATT	- USV hat niedrigen Batteriestand erreicht
 * FSD		- Herunterfahren eingeleitet (Forced Shutdown)
 * COMMOK	- Kommunikation mit USV aufgebaut
 * COMMBAD	- Kommunikation mit USV verloren
 * SHUTDOWN	- Das System wird heruntergefahren
 * REPLBATT	- USV-Batterie muss getauscht werden
 * NOCOMM	- USV ist nicht erreichbar
 * NOPARENT	- upsmon Elternprozess beendet, Herunterfahren unmöglich

{{{
NOTIFYFLAG ONLINE SYSLOG+WALL+EXEC
NOTIFYFLAG ONBATT SYSLOG+WALL+EXEC
# und so weiter ...
}}}

Dies sind die Aktionen, die durchgeführt werden, wenn ein Ereignis eintritt. ``SYSLOG`` gibt an, das das Ereignis ins Systemprotokoll geschrieben wird. ``WALL`` sendet Nachrichten an alle angemeldeten Benutzer am lokalen PC (siehe auch [:wall:]). ``EXEC`` gibt den Status an das Programm von ``NOTIFYCMD`` weiter. Wenn z.B. nur Nachrichten gesendet werden sollen, reicht ``WALL`` aus. Hier werden die selben Ereignisse verwendet wie bei ``NOTIFYMSG``.

{{{
RBWARNTIME 43200
}}}

Ist die Zeit in Sekunden bevor die Meldung für den Batteriewechsel kommt.

{{{
NOCOMMWARNTIME 300
}}}

Ist die Zeit in Sekunden bis die Meldung kommt, dass die USV nicht erreichbar ist. Diese Meldung wiederholt sich so lange bis die USV wieder erreichbar ist.

{{{
FINALDELAY 5
}}}

Ist die Zeit die gewartet wird, nachdem der `SHUTDOWNCMD` aufgerufen wird bevor er ausgeführt wird.

=== upssched verwenden ===
Dazu editiert man die Datei '''/etc/nut/upssched.conf''' oder legt sie neu an.

{{{
CMDSCRIPT /etc/nut/upssched/upsscript
}}}

Ist der Pfad zu dem Skript, was ausgeführt werden soll, wenn die Trigger (Schalter) gesetzt werden.

{{{
PIPEFN /etc/nut/upssched/upssched.pipe
LOCKFN /etc/nut/upssched/upssched.lock
}}}

Diese Dateien werden genutzt, um mit den Prozessen zu agieren. Sie werden automatisch erzeugt und gelöscht.

{{{
AT ONBATT * START-TIMER onbatt 90
AT ONLINE * CANCEL-TIMER onbatt
AT LOWBATT * EXECUTE battleer
}}}

In diesem Fall wird ein Timer gestartet, wenn die USV auf Batterie umschaltet. Dieser wartet 90 Sekunden, bevor er den Parameter ``onbatt`` an das ``CMDSCRIPT`` weiter gibt. Schaltet die USV wieder ONLINE, so wird der Timer abgebrochen. Wenn die USV Batterie niedrig ist, wird sofort das Skript mit dem Parameter ``battleer`` ausgeführt.

== Beispiel-Skript für upssched ==
Das Skript ist ein einfaches Beispiel für die Konfiguration:

{{{#!code bash
#!/bin/sh
case $1 in
  onbatt)
    /sbin/shutdown -h +0;;
  battleer)
    /sbin/upssched fsd;;
  *)
    echo "Falscher Parameter";;
esac
}}}

== Rechte ändern ==
Da die Dateien wichtige Konfigurationen und Passwörter enthalten müssen sie gut durch Einschränkung von Rechten geschützt werden. Im Ordner '''/etc/nut''' sollten alle Dateien ''root'' gehören und die Gruppe ''nut'' Leserechte [5] haben. Dies geschieht mit 

{{{#!vorlage Befehl
cd /etc/nut
chown -R root:nut /etc/nut/*
chmod -R 640 /etc/nut/*
}}}

Sollte man ein eigenes Skript erstellt und in '''/etc/nut''' gespeichert haben, muss dies zusätzlich ausführbar gemacht werden:

{{{#!vorlage Befehl
chmod -R 750 /etc/nut/myscript.sh
}}}

Wenn man mit upssched Befehle über "sudo" ausführen will, z.B. "sudo systemctl hibernate -i", dann muss man dafür sorgen, dass der Benutzer "nut" diese Befehle per sudo aufrufen kann, ohne dass ein Password nötig ist. Dazu legt man eine sudoers-Datei an:
{{{#!vorlage Befehl
sudo visudo -f /etc/sudoers.d/hibernate
}}}
und füllt sie mit dieser Policy:
{{{
%nut    ALL=NOPASSWD: /bin/systemctl hibernate *, /usr/bin/systemctl hibernate *, /lib/systemd/systemd-sleep hibernate *, /usr/bin/systemctl suspend *
}}}

== Testen der Einstellungen ==
Wenn man alles nach seinen Wünschen eingestellt hat, kann man nun den Rechner neu starten. Dann kann man mit

{{{#!vorlage Befehl
upsc ups1
}}}

den Status seiner USV auslesen. Als nächstes zieht man die Stromversorgung der USV ab, um zu sehen ob alles so funktioniert wie gewünscht. Wenn alles funktioniert, kann man nun die USV richtig an den Rechner anschließen.

= Konfiguration reiner Client-Betrieb =
Auf allen Rechnern vom Typ A wird nur der Client '''upsmon''' aktiviert. Es gibt auch Anwendungsfälle dies auf Rechnern vom Typ C zu installieren, wenn diese einfach Statusinformationen verarbeiten sollen, z.B. Statusdaten der USV sammeln und graphisch darstellen oder Mails bei kritischem Status versenden oder einfach eine Benachrichtigung auf dem Arbeits-PC. Das könnte natürlich auch auf den anderen Rechnern (Typ A oder B) erledigt werden.

== Modus einrichten ==
Dazu editiert man die '''/etc/nut/nut.conf''':

{{{
MODE=netclient
}}}

== upsmon konfigurieren ==
Im Prinzip genau wie oben beim Server-Betrieb, nur dass die Zeile von Monitor anders lautet.
Dazu editiert man die /etc/nut/upsmon.conf:

{{{
# MONITOR upsname@adress_of_upsd_pc 1 ups_user password master/slave
MONITOR ups1@192.168.156.54 1 upsslave upsslavepw slave
}}}

Dabei ist die IP-Adresse Anstatt der IP-Adresse kann hier auch der Hostname angegeben werden, falls er aufgelöst werden kann.

== upssched oder Skripte einrichten ==
Kann hier genau so genutzt werden wie beim Server.

== Testen der Einstellungen ==
Rechner neu starten und mit:

{{{#!vorlage Befehl
upsc ups1@192.168.156.54 
}}}

testen, ob die Daten ausgelesen werden können.

= Firewall =
Zu beachten ist, dass die Kommunikation zwischen upsd und upsmon standardmäßig über Port 3493 läuft. Dies lässt sich auch in den Konfigurationsdateien ändern, indem bei den LISTEN- und MONITOR-Anweisungen jeweils der Port ergänzt wird:

{{{
# upsd.conf:
LISTEN 0.0.0.0 1508
# upsmon.conf:
MONITOR ups1@192.168.156.54:1508 1 upsslave upsslavepw slave
}}}

Wichtig ist jedoch, dass diese Kommunikation auf Port 3493 (oder dem selbstgewählten Port) zwischen verschiedenen Rechnern auch durch die Firewall beider Rechner erlaubt ist. Im Fall eines Proxmox-Servers mit aktivierter Firewall, muss der Eingang und Ausgang für den Port ausdrücklich freigegeben werden. Ebenso wenn z.B. die Ubuntu-Standardfirewall [:ufw:] aktiviert wurde oder wird.

= Beispiel-Skript =
Dieses Beispiel gilt für einen Rechner vom Typ C. Ich verwende es auf meinem Laptop. Dieser ist von der USV und durch den Akku auch vom Strom unabhängig. Die USV versorgt zwei Server (Typ A als slave und B als master). Ich möchte aber gerne eine schnelle Meldung bekommen, wenn etwas passiert und ich am Laptop sitzen sollte. Installiert ist also nur der Monitorbetrieb upsmon als weiterer slave.

'''nut.conf''':
{{{
MODE=netclient
}}}

'''upsmon.conf''':
{{{
RUN_AS_USER nut
MONITOR ups1@192.168.156.54 1 upsslave upsslavepw slave
MINSUPPLIES 1
NOTIFYCMD /etc/nut/notify.sh
POLLFREQ 5
POLLFREQALERT 5
HOSTSYNC 15
DEADTIME 15
POWERDOWNFLAG /etc/killpower
NOTIFYMSG ONLINE        "UPS %s back on line power"
NOTIFYMSG ONBATT        "UPS %s is on battery"
NOTIFYMSG LOWBATT       "UPS %s battery is low"
NOTIFYMSG FSD           "UPS %s: forced shutdown in progress"
NOTIFYMSG COMMOK        "Communications with UPS %s established"
NOTIFYMSG COMMBAD       "Communications with UPS %s lost"
NOTIFYMSG SHUTDOWN      "Auto logout and shutdown proceeding"
NOTIFYMSG REPLBATT      "UPS %s battery needs to be replaced"
NOTIFYMSG NOCOMM        "UPS %s is unavailable"
NOTIFYMSG NOPARENT      "upsmon parent process died - shutdown impossible"
NOTIFYFLAG ONLINE       WALL+EXEC
NOTIFYFLAG ONBATT       WALL+EXEC
NOTIFYFLAG LOWBATT      WALL+EXEC
NOTIFYFLAG FSD          WALL+EXEC
NOTIFYFLAG COMMOK       WALL+EXEC
NOTIFYFLAG COMMBAD      WALL+EXEC
NOTIFYFLAG SHUTDOWN     WALL+EXEC
NOTIFYFLAG REPLBATT     WALL+EXEC
NOTIFYFLAG NOCOMM       WALL+EXEC
NOTIFYFLAG NOPARENT     WALL+EXEC
RBWARNTIME 43200
NOCOMMWARNTIME 300
FINALDELAY 5
}}}

Wichtig:
 * Der SHUTDOWNCMD ist entfernt, weil das Laptop nicht automatisch mit heruntergefahren werden soll.
 * notify.sh muss wie folgt in '''/etc/nut''' erstellt und mit den Rechten '''750''' (siehe oben) ausgestattet werden.
 * [:Zenity:] muss installiert sein (eigentlich Standard in Ubuntu)

'''notify.sh''':
{{{#!code bash
!bin/bash
# send a message to user screen
zenity --info --title "Meldung von der USV" --text "$1"
}}}

Andere Aktionen, die ein Server ausführen könnte, wäre die Benachrichtigung des Admins über eine Email. Dazu findet sich unten ein Link.

= Administrative Werkzeuge =
Man kann eine Web-Oberfläche für Nut installieren, um diese von einen beliebigen Ort im Netzwerk zu kontrollieren und Testläufe zu starten. Voraussetzung ist ein laufender Webserver.

Folgendes Paket wird für die Installation benötigt:

{{{#!vorlage Paketinstallation
nut-cgi
}}}

Ist dies installiert, so kann man mit einem Webbrowser auf die gerade erstellte Seite von NUT zugreifen. Zum Beispiel:

{{{
http://localhost/nut
}}}

Für die Anmeldung gelten die Benutzernamen, die in '''ups.users''' eingerichtet wurden.

{{{#!vorlage Hinweis
Der Webserver sollte so eingerichtet werden, dass der Zugriff auf die Web-Oberfläche nur vom lokalen Netz erlaubt ist.
}}}

= Links =
 * [https://networkupstools.org/ Projektseite] {en}
  * [https://networkupstools.org/stable-hcl.html Liste unterstützter USVs] {en}
 * [https://nguvu.org/proxmox/proxmox-install/#ProxmoxNUTinstall] {en} - Artikel mit einem Beispiel einer Email-Benachrichtigung
 * [https://zefanjas.de/server-bei-stromausfall-herunterfahren-ups-nut-co/] {de} - deutschsprachiger Artikel
 * [https://www.linux-user.de/ausgabe/2007/10/088-revolt-usv/index.html 250W-USV für zuhause] {de} - Artikel LinuxUser 10/2007
 * [:USV:] {Übersicht} Übersichtsartikel

#tag: Netzwerk, Sicherheit, Server