====== vzlogger Installation ======

This manual is also available in [[/software/controller/vzlogger/installation_en|english]].

=== Repository ===
Unser Repository: https://github.com/volkszaehler/vzlogger\\

Derzeit ist vzlogger und (auf manchen Plattformen) ein paar der Bibliotheken (Libraries) nur als Quellcode verfügbar. Diese müssen vor gebrauch kompiliert (übersetzt) werden. 

Dies macht man praktischerweise in einem Verzeichnis, in dem dein "normaler" Nutzer Schreibrechte hat. Zum Beispiel dein Home-Verzeichnis:

<code>
cd ~
</code>

Die meisten Erfahrungen mit dem Bau des vzloggers bestehen mit Debian und verwandten Distributionen (Ubuntu, Raspbian). Die folgenden Anleitungen wurden im April 2022 mit Debian 11 "Bullseye" verifiziert; Informationen für ältere Versionen finden sich in der Historie dieser Seite.

===== Systemvoraussetzungen zur Kompilierung des vzlogger =====

Für eine erfolgreiche Kompilierung des vzlogger werden, neben gcc und glibc, auch diese Libraries benötigt:

=== Tools ===
  * git
  * cmake
  * pkg-config
  * subversion (für Tests mit googlemock)
 
=== Erforderliche Libraries ===
  * libjson-c-dev
  * libcurl4-openssl-dev
  * libgnutls28-dev
  * libgcrypt
  * libsasl2-dev
  * libuuid1
  * libsml (für sml meters)
  * libmicrohttpd-dev >= 0.4.6 (for builtin "local" webserver)
  * libltdl >=0.8.0 (for OMS)
  * libleptonica-dev (for OCR)
  * libmosquitto-dev (for MQTT)
  * libunistring-dev (wegen Problem mit Ubuntu 18.04)


=== Debian Pakete ===

Für auf Debian basierende Distributionen können die meisten dieser Abhängigkeiten mit:

<code>sudo apt-get install build-essential git cmake pkg-config subversion libcurl4-openssl-dev libgnutls28-dev libsasl2-dev uuid-dev libtool libssl-dev libgcrypt20-dev libmicrohttpd-dev libltdl-dev libjson-c-dev libleptonica-dev libmosquitto-dev libunistring-dev dh-autoreconf</code>
installiert werden. Eventuell erstmal <code>sudo apt-get update</code> ausführen.

===== Build per Script =====
Vzlogger bietet ein Shellscript für Download, Übersetzung und Installation der Module die nur als Quellen verfügbar sind.
<code>
git clone https://github.com/volkszaehler/vzlogger.git
cd vzlogger
./install.sh
</code>

Das Script bietet auch die Möglichkeit, nur einzelne Module zu übersetzen. Details dazu findet man als Kommentar im Script.

Möchte man den vzlogger mit optionaler Funktionalität MQTT bauen lautet der Aufruf für das Script:
<code>
./install.sh vzlogger libjson libsml mqtt
</code>

=== Hintergrunddienst ===
Nun sollte vzlogger vollends als Systemdienst eingerichtet werden. Details dazu [[software/controller/vzlogger/installation_cpp-version#systemd_startscript|weiter unten]].

=== Aktualisierung ===

Ist in der Regel aber nicht nötig, aber die zugrundeliegende SML Bibliothek kann (vorher) für sich aktualisiert werden, indem:
<code>
cd vzlogger/libs/libsml
git pull
cd ../..
./install.sh libsml
</code>

Zum Aktualisieren des vzlogger dient diese Prozedur:
<code>
sudo systemctl stop vzlogger
cd vzlogger
git pull
./install.sh vzlogger
sudo systemctl start vzlogger
</code>

Mit optionaler Funktionalität MQTT lautet hier der Aufruf für das Script:
<code>
./install.sh mqtt vzlogger
</code>

===== Build von Hand =====

Falls das Script nicht zu den Gegenheiten passt nachfolgend die einzelnen Schritte.
<note warning>Nur für geübte User! Wer wenig Erfahrung hat sollte den [[software:controller:vzlogger:installation_cpp-version#build_per_script|Build per Script]] machen.</note>

=== Building libsml ===
Debian bietet zwar ein Paket libsml-dev, das basiert aber leider auf veraltetem, nicht mehr gepflegtem Code.
<code>
git clone https://github.com/volkszaehler/libsml.git
cd libsml
sudo make
</code>
Libsml bietet kein 'make install' Vorgabe.

Man macht das manuell in dem man die folgenden Dateien und Verzeichnisse kopiert:
<code>
sudo cp sml/lib/libsml.* /usr/lib/
sudo cp -R sml/include/* /usr/include/
sudo cp sml.pc /usr/lib/pkgconfig/
</code>

Zurück zum Ausgangsverzeichnis: <code>cd ..</code>

=== Building vzlogger ===
<note>Hier können bei Bedarf weitere Funktionen dazu kompiliert werden z.B. MQTT, dazu den cmake-Befehl anpassen:\\ ''cmake -DBUILD_TEST=off -DENABLE_MQTT=on ..''</note>
<code>
git clone https://github.com/volkszaehler/vzlogger.git
cd vzlogger
mkdir build
cd build
cmake -DBUILD_TEST=off ..
make
sudo make install
</code>

Zurück zum Ausgangsverzeichnis: <code>cd ../..</code>

== Bau als Debian-Paket ==

Das vzlogger Repository enthält ebenfalls Code, um ein "sauber" installier- und deinstallierbares Debian-Paket zu bauen. 

<code>
git clone https://github.com/volkszaehler/vzlogger.git
cd vzlogger
apt build-dep ./
apt install devscripts
debuild
</code>


=== Building OMS ===

OMS erfordert openssl und libmbus >=0.8.0 z.B. von https://github.com/rscada/libmbus.git
<code>
git clone https://github.com/rscada/libmbus.git
cd libmbus
./build.sh
sudo make install
</code>

Zurück zum Ausgangsverzeichnis: <code>cd ..</code>

=== Hintergrunddienst ===
Nun sollte vzlogger als Systemdienst eingerichtet werden. Details dazu [[software/controller/vzlogger/installation_cpp-version#systemd_startscript|weiter unten]].

=== vzlogger aktualisieren ===
Falls der vzlogger aktualisiert werden soll ist wie folgt vorzugehen:
<code>
cd vzlogger
git pull
cd build
cmake -DBUILD_TEST=off ..
make
sudo systemctl stop vzlogger
sudo make install
sudo systemctl start vzlogger
</code>


====== Systemd Startscript ======
Systemd dient dazu Hintergrunddienste einzurichten und zu verwalten.

Das Installationsscript fragt ob es ein "systemd unit file" für dich installieren soll. Falls dein System systemd nutzt (ab Debian "Jessie") solltest du mit yes (ja) bestätigen.

Falls du es selbst kopieren oder editieren willst findest du ein Beispiel unter:
[[https://github.com/volkszaehler/vzlogger/blob/master/etc/vzlogger.service|./etc/vzlogger.service]]
<code>sudo cp ./etc/vzlogger.service /etc/systemd/system/vzlogger.service</code>

<note important>
Bitte stelle sicher das die Pfade zur Binary (vzlogger) und der Konfigurationsdatei (vzlogger.conf) korrekt sind.
</note>

Den vzlogger kann man dann mit dem üblichen systemctl Kommando starten, stoppen und prüfen:

<code>
sudo systemctl start vzlogger
systemctl status vzlogger
sudo systemctl stop vzlogger
</code>
<note>Eine lauffähige Konfiguration ist dafür zwingend! Ansonsten wird vzlogger beendet und systemd meldet Fehler.</note>

Wenn der vzlogger zufriedenstellend läuft und bei jedem boot als Hintergrunddienst gestartet werden soll:

<code>
sudo systemctl enable vzlogger
</code>


====== vzlogger als anderer Benutzer ausführen ======

=== Elevated privileges für vzlogger binary setzen ===

Als User führt man folgenden Befehl aus, um ausreichend Rechte zum Ausführen des Programms zu erhalten:
<code>
sudo setcap 'cap_sys_nice=eip' /usr/local/bin/vzlogger
</code>

<note>Auf Raspberry können dennoch Zugriffsprobleme beim Konfigurieren der GPIO auftreten. Frühzeitiger export in ''/etc/rc.local'' umgeht das Problem.</note>

=== Dienst-User anlegen ===

Man kann für den Dienst einen separaten User (z.B. ''vzlogger'') ohne Homeverzeichnis anlegen und Passwort vergeben.
<code>
sudo useradd -M vzlogger
sudo passwd vzlogger
</code>

Auf einem Raspberry den neuen User diversen Gruppen hinzufügen.
<code>
sudo usermod -aG gpio vzlogger
sudo usermod -aG dialout vzlogger
sudo usermod -aG staff vzlogger
</code>

Für das Logfile ein Unterverzeichnis mit passenden Schreibrechten anlegen.
<code>
sudo mkdir /var/log/vzlogger
sudo chgrp staff /var/log/vzlogger
sudo chmod g+w /var/log/vzlogger
</code> 

=== vzlogger.conf anpassen ===

Der neue Ort fürs Logfile muss natürlich auch vzlogger bekannt gemacht werden. ''/etc/vzlogger.conf'':
<code>
"log" : "/var/log/vzlogger/vzlogger.log",
</code>


=== Systemd Startscript anpassen ===

Nun muss nur noch im Systemd Startscript (siehe anderer Paragraph) der User, mit welchem vzlogger ausgeführt werden soll, hinzugefügt bzw. geändert werden.

Unter der Kategorie [Service] fügt man eine weitere Zeile hinzu. Für den User vzlogger lautet es zum Beispiel:

<code>
User=vzlogger
</code>

Nun muss der Service nur neu gestartet werden und vzlogger läuft unter dem angegebenen Benutzer:

<code>
sudo systemctl daemon-reload
</code>

=== Verwendung ===

Das Betreiben von vzlogger unter einem anderen Benutzer als root ist vor allem bei der Verwendung vom Protokol "exec" von Bedeutung. vzlogger muss nicht für die Verwendung neu kompiliert werden. Aufrufe von "exec" werden nicht von root sondern vom verwendeten User gemacht.


====== Spezielle Hinweise ======

=== Debian Paket ===

Um ein Debian Paket zu erzeugen:
<code>
cpack -G DEB
</code>

=== Cross Kompilierung===

<code>
cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchainfile /path/to/vzlogger_sources
</code>