====== vzlogger Installation (en) ======

=== Repository ===
Our repository: https://github.com/volkszaehler/vzlogger\\

Actually vzlogger and sometimes the libraries are only provided by sourcecode. They have to be compiled before use.
Select a working directory your user has writing permissions. For example the home directory:
<code>
cd ~
</code>
The most experience is collected from Debian and other Distributions close (Ubuntu, Raspian). The following guide is based on Debian "Bullseye" in April of 2022. Specific instructions for older Versions can be found in the history of this site.

===== Prerequisites for compiling vzlogger =====

Please note that a full configured vzlogger requires besides gcc (4.7 or higher) and glibc, these libraries to compile successfully:

=== Tools ===
  * git
  * cmake
  * pkg-config
  * subversion (for tests using googlemock)
 
=== Required Libraries ===
  * libjson >= 0.11 (>= 0.9 before [[https://github.com/volkszaehler/vzlogger/pull/106]])
  * libcurl3 >= 7.19
  * libgnutls-dev
  * libgcrypt
  * libsasl2-dev
  * libuuid1
  * libsml (for 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 (due to problem Ubuntu 18.04)

=== Debian packages ===
On Debian based distributions, most of these dependencies can easily be installed with:
(as root, consider running "apt-get update" first)
<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>

===== Build by script =====
Vzlogger provides a shell script for download, build and install of the modules issued only as sourcecode.
<code>
git clone https://github.com/volkszaehler/vzlogger.git
cd vzlogger
./install.sh
</code>

The script supports also build of one single module. See the comments in the script for details.

=== Daemon ===
At this point a daemon-service should be prepared to run vzlogger in backgroung. Details [[/software/controller/vzlogger/installation_en#systemd_start_script|down below]].

=== Update ===
If a update is necessary follow these steps:
<code>
sudo systemctl stop vzlogger 
cd vzlogger
git pull
./install.sh vzlogger
sudo systemctl start vzlogger
</code>

The based SML Library may (before) updated by:
<code>
cd vzlogger/libs/libsml
git pull
cd ../..
./install.sh libsml
</code>

===== Build by hand =====
In cases the script does not fit the conditions.
<note warning>​Only for experienced users! Follow [[/software/controller/vzlogger/installation_en#build_by_script|build by script]] instead.</note>​

=== Building libsml ===
Debian provides a paket libsml-dev, but it's not well maintained and too old for our needs.
<code>
git clone https://github.com/volkszaehler/libsml.git
cd libsml
sudo make
</code>
Note that libsml does not include a 'make install' target.

You can manually install it into your system by copying the following files and directories
<code>
sudo cp sml/lib/libsml.* /usr/lib/
sudo cp -R sml/include/* /usr/include/
sudo cp sml.pc /usr/lib/pkgconfig/
</code>

Go back to your starting directory: <code>cd ..</code>

=== Building vzlogger ===

<code>
git clone https://github.com/volkszaehler/vzlogger.git
cd vzlogger
mkdir build
cd build
cmake -DBUILD_TEST=off ..
make
sudo make install
</code>

Go back to your starting directory: <code>cd ../..</code>

== Build as Debian-paket == 
The vzlogger repository contains code to build a "clean" paket for Debian.
<code>
git clone https://github.com/volkszaehler/vzlogger.git 
cd vzlogger 
apt build-dep ./ 
apt install devscripts 
debuild
</code>

=== Building OMS ===

OMS requires openssl and libmbus >=0.8.0 from e.g. https://github.com/rscada/libmbus.git
(installation is easy:)
<code>
git clone https://github.com/rscada/libmbus.git
cd libmbus
sudo ./build.sh
sudo make install
</code>

Go back to your starting directory: <code>cd ..</code>

=== Daemon ===
At this point a daemon-service should be prepared to run vzlogger in backgroung. Details [[/software/controller/vzlogger/installation_en#systemd_start_script|down below]].

=== Update vzlogger ===
If a update is necessary follow these steps:
<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 start script ======
Systemd is used to install and execute services in background (daemon).

The installscript asks you for installing the systemd unit file for you. If your computer uses systemd (since Debian-Jessie) you may answer yes.

If you want to copy and edit it by yourself you find a template under: [[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>
Please make sure that both paths to the binary (vzlogger) and its configuration file (vzlogger.conf) are correct.
</note>

You can start, stop or verify vzloggers status using the common systemctl command:

<code>
sudo systemctl start vzlogger
systemctl status vzlogger
sudo systemctl stop vzlogger
</code>
<note>You need a working configuration at this point! Else vzlogger will be closed and systemd generates failures.</note>

If you are satisfied and want to have vzlogger permanently startet as a service everytime your machine boots, just enable it:

<code>
sudo systemctl enable vzlogger
</code>

====== Run vzlogger with different user ======

=== Elevated privileges for vzlogger binary ===

<code>
sudo setcap 'cap_sys_nice=eip' /usr/local/bin/vzlogger
</code>

<note>On Raspberry might still be problems with configuration of GPIOs. Earlier export in ''/etc/rc.local'' solves the problem.</note>

=== Add Daemon-User ===

Add a user without home-directory and generate password. 
<code>
sudo useradd -M vzlogger
sudo passwd vzlogger
</code>

Add the user to the follwing groups:
<code>
sudo usermod -aG gpio vzlogger
sudo usermod -aG dialout vzlogger
sudo usermod -aG staff vzlogger
</code>

For the logfile generate a sub-directory with adequate rights.
<code>
sudo mkdir /var/log/vzlogger
sudo chgrp staff /var/log/vzlogger
sudo chmod g+w /var/log/vzlogger
</code> 

=== adapt vzlogger.conf ===

The new location oft logfile has to be configured accordingly. ''/etc/vzlogger.conf'':
<code>
"log" : "/var/log/vzlogger/vzlogger.log",
</code>


=== adapt Systemd startscript ===

Last change is to promote the new user in systemd startscript (see chapter above).

Under [Service] add the following line:
<code>
User=vzlogger
</code>

Systemd need to be restartet to activate the change:

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

=== Use-sase===

This adaption is of particular interest in combination with meter-protocol "exec". Vzlogger doesn't have to be recompiled and the actions started by "exec" run with lower user-privilges.

====== Special hints ======

=== debian package ===
a debian package can be generated using:
<code>
cpack -G DEB
</code>

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