Commit 2308fe53 authored by Karim El Aammari's avatar Karim El Aammari
Browse files

README

parent 56d4d0e4
......@@ -12,7 +12,7 @@ Mithilfe dieses Workflows können Sie mit Vagrant eine vollständige Monitoring-
Für das Bereitstellen der Metriken, ist auf jeder virtuellem Maschine (VM) der Prometheus-node-exporter installiert.
![Infrastruktur](./docu/inkscape/infrastruktur_s.png)
![Infrastruktur](./docu/inkscape/infrastruktur.pdf)
## Voraussetzungen
......@@ -36,7 +36,7 @@ Um direkt zu starten, kopieren Sie mit folgendem Befehl das Projekt auf ihren Re
git clone git@git.gsi.de:dc/common/vagrant-prometheus.git
```
Bevor die VMs gestartet werden, müssen die benötigten TLS-Zertifikate erzeugt werden. Hierfür führen Sie folgenden Befehl aus.
Bevor die VMs gestartet werden, muss eine CA und durch sie signierte TLS-Zertifikate für Influx, Grafana und Chronograf erzeugt werden. Hierfür führen Sie folgenden Befehl aus.
```shell
./scripts/openssl_generate.sh
......@@ -54,81 +54,45 @@ Anschließen starten nacheinander Influx, Prometheus, Grafana und Chronograf. Di
vagrant up {node-1 node-2 ... node-10 | /node-.*/}
```
## Überwachen der Maschinen
## Funktionsprüfung
Nachdem die Maschinen gestartet sind und die Provisionierung erfolgreich ausgeführt wurde, können wir über die von Vagrant weitergeleiteten Ports direkt auf die Dienste zugreifen.
* <https://127.0.0.1:3000> (Grafana)
* <https://127.0.0.1:8888> (Chronograf)
* <http://127.0.0.1:9090> (Prometheus)
Wenn auf ihrem Betriebssystem diese Ports schon in Verwendung sind, können Sie in der Vagrantfile eine andere Zuordnung konfigurieren.
Da die Dienste Grafana und Chronograf ein signiertes TLS-Zertifikat besitzen, können Sie ihrem Browser das unter ```./openssl/data/certificates/cacert.pem``` gespeicherte Root-Zertifikat als Zertifizierungsstelle eintragen, um Warnungen beim Aufruf der Seiten zu vermeiden. Wenn Sie das Zertifikat hinzufügen, können Sie mit folgendem Befehl die Fingerprints der erzeugten Zertifikate anzeigen lassen, um diese zu verifizieren.
Um Zertifikat-Warnungen zu vermeiden, können Sie das CA-Zertifikat ```./openssl/data/certificates/cacert.pem``` als vertrauenswürdig in Ihrem Browser eintragen. Wenn Sie das Zertifikat hinzufügen, sollten Sie sicherstellen, dass die durch den Browser angezeigten Fingerprints denen der Ausgabe des folgenden Befehls entsprechen.
```shell
./scripts/openssl_fingerprint.sh
openssl x509 -noout -fingerprint -sha256 -inform pem -in cacert.pem
openssl x509 -noout -fingerprint -sha1 -inform pem -in cacert.pem
```
## Vagrant Kommandos
: ```vagrant up <vm>```
Startet und erstellt falls nötig die Maschine. Wird die Maschine zum ersten Mal gestartet, wird auch die Provision ausgeführt, andernfalls muss mit der Option "--provision" die Provisionierung explizit gefordert werden.
* ```vagrant up <vm>```
Startet und erstellt falls nötig die Maschine. Wird die Maschine zum ersten Mal gestartet, wird auch die Provisionierung ausgeführt, andernfalls muss mit der Option "--provision" die Provisionierung explizit gefordert werden.
: ```vagrant destroy <vm>```
Zerstört die Maschine unwiderruflich.
* ```vagrant destroy <vm>```
Löscht die Maschine.
: ```vagrant provision <vm>```
Mit diesem Befehl führen Sie bei einer laufenden Maschine die Provisionierung neu aus. Dabei werden die Befehle aus der Vagrantfile (%vm_name%.vm.provision) in absteigender Reihenfolge nacheinander ausgeführt. Das bedeutet, als erstes werden mit dem File-Provisionierer die aktuellen Dateien aus dem Projektverzeichnis erneut auf die VM kopiert und anschließend die Inline-Skripte ausgeführt.
: ```vagrant ssh <vm>```
Baut eine SSH Verbindung mit dem von Vagrant hinzugefügten Key auf.
* ```vagrant provision <vm>```
Mit diesem Befehl führen Sie bei einer laufenden Maschine die Provisionierung neu aus. Dabei werden die Befehle aus der Vagrantfile (%vm_name%.vm.provision) in der dort angegebenen Reihenfolge nacheinander ausgeführt.
* ```vagrant ssh <vm>```
Baut eine SSH-Verbindung zu der angegebenen VM auf.
## Klassifizierung von Dateien
Um eine überschaubare Umgebung zu schaffen, werden die hier verwendeten Daten und Dateien in drei Kategorien zu unterteilt.
### 1. Executable
In die Kategorie Executable fallen alle binären oder ausführbaren Dateien. In diesem Projekt werden alle Programme von den jeweiligen Paketmanagern installiert, lediglich Skripte, wie z.B. die für den Backup- und Restore-Workflow werden mit dem File-Provisionierer kopiert. Zusätzlich gehören Unit- und Timer-Dateien in diesem Projekt auch in die Kategorie Executable, die auch je nach VM mit dem File-Provisionierer kopiert werden.
Um eine überschaubare Umgebung zu schaffen, werden die hier verwendeten Dateien in drei Kategorien zu unterteilt.
```shell
.vagrant-prometheus/
./provision
./chronograf
./config
./chronograf.service
./grafana
./setup_grafana.sh
./influx
./backup
./backup_call.sh
./backup.sh
./restore.sh
./config
./backup.service
./backup.timer
./setup_influx.sh
./node
./config
./stress.service
./prometheus
./config
./prom.service
./scripts
./influx_backup.sh
./influx_restore.sh
./node_start_stress.sh
./node_stop_stress.sh
./openssl_fingerprint.sh
./openssl_generate.sh
./openssl_node.sh
```
### 1. Konfigurations-Daten
### 2. Konfigurations-Daten
Konfigurationsdateien enthalten von Benutzer angegebene Parameter für den Betrieb einer Software gebraucht werden. Hierrunter fallen z.B. Ini- oder Conf-Dateien.
Konfigurationsdateien werden beim Start der Executables gebraucht. Hierrunter fallen z.B. Ini- oder Conf-Dateien. Einen Sonderfall stellen in diesem Projekt die Text- und JSON-Dateien dar, Diese enthalten Daten, die nicht direkt von den Executables interpretiert werden, sondern z.B. die JSON-Dateien mittels CURL an die HTTP-API von Grafana gesendet werden, um einen Zustand zu erzeugen. Da der Workflow für Openssl bzw. Zertifikate in einer anderen Sektion beschrieben wird, übergehen wir hier diese Dateien.
Einen Sonderfall stellen in diesem Projekt die Text- und JSON-Dateien dar, Diese enthalten Daten, die nicht direkt von den Executables interpretiert werden, sondern z.B. die JSON-Dateien mittels CURL an die HTTP-API von Grafana gesendet werden, um einen Zustand zu erzeugen. Da der Workflow für Openssl bzw. Zertifikate in einer anderen Sektion beschrieben wird, übergehen wir hier diese Dateien.
```shell
.vagrant-prometheus/
......@@ -152,17 +116,9 @@ Konfigurationsdateien werden beim Start der Executables gebraucht. Hierrunter fa
./prom.yml # Konfigurationsdatei
```
### 3. Benutzer-Daten
Hiermit sind alle Daten gemeint, die bei Inbetriebnahme und während dem Betrieb entstehen. Im Projektverzeichnis enthalten folgende Ordner Benutzerdaten:
### 2. Benutzer-Daten
```shell
.vagrant-prometheus/
./backup
./openssl/data
```
Weiter Benutzerdaten befinden sich auf den VMs.
Hiermit sind alle Daten gemeint, die während des Betriebs entstehen. In diesem Projekt sind dies vorwiegend die von den Exportern erhobenen Daten in der Influx-Datenbank.
* Chronograf
......@@ -193,12 +149,48 @@ Weiter Benutzerdaten befinden sich auf den VMs.
/var/lib/prometheus/data
```
### 3. Executable
In die Kategorie Executable fallen alle Dateien, die weder Konfig- noch Bentuzer-Daten sind.
```shell
.vagrant-prometheus/
./provision
./chronograf
./config
./chronograf.service
./grafana
./setup_grafana.sh
./influx
./backup
./backup_call.sh
./backup.sh
./restore.sh
./config
./backup.service
./backup.timer
./setup_influx.sh
./node
./config
./stress.service
./prometheus
./config
./prom.service
./scripts
./influx_backup.sh
./influx_restore.sh
./node_start_stress.sh
./node_stop_stress.sh
./openssl_fingerprint.sh
./openssl_generate.sh
./openssl_node.sh
```
## Backup- und Restore-Workflow
### Backup
Die InfluxDB ist durch einen Backup- und Restore-Mechanismus ausgestattet, mit dem wir die gesammelten Daten des Monitoringsystems extern speichern und zurück spielen können. In diesem Workflow wird standardmäßig um 1 Uhr täglich ein Vollbackup ausgelöst, das separat zu den vorherigen Backups in einem Ordner mit Zeitstempel abgelegt wird. Konfigurieren können Sie den Timer in der Datei: ```./provision/influx/config/backup.timer```. Wichtig zu beachten ist, dass das Backup in einem von VirtualBox geteilten Ordner zwischen VM ```/vagrant/backup``` und Projektverzeichnis ```./backup``` gespeichert wird! Wenn Ihr Hypervisor diese Funktion nicht unterstützt, müssen Sie die Backups von Hand aus der Influx-VM kopieren. Vagrant bietet hier alternativ Rsync oder SMB an.
Die InfluxDB ist durch einen Backup- und Restore-Mechanismus ausgestattet, mit dem wir die gesammelten Daten des Monitoringsystems exportiern und wiederherstellen können. In diesem Workflow wird standardmäßig täglich um 1 Uhr ein Vollbackup ausgelöst, das separat zu den vorherigen Backups in einem Ordner mit Zeitstempel abgelegt wird. Konfigurieren können Sie den Timer in der Datei ```./provision/influx/config/backup.timer```.
Um ein manuelles Backup zu starten, führen Sie folgendes Skript aus.
......@@ -210,19 +202,23 @@ Mit der %PFAD% Variable geben Sie den Ausgabepfad des Backups an. Dabei beschrei
### Restore
Um ein Backup in die InfluxDB wieder zurück zuspielen, benutzen Sie folgendes Skript.
Um ein Backup in die InfluxDB wiederherzustellen, benutzen Sie folgendes Skript.
```shell
./scripts/influx_restore.sh <PFAD>
```
Die %PFAD% Variable ist hierbei der Ordner indem sich die Backupdateien befinden. Sollte in Ihrer Influx-Instanz schon die Datenbank "prom" existieren, werden Sie gefragt ob Sie diese löschen wollen, um die "prom"-Datenbank aus dem Backup laden zu können. Diese Operation ist notwendig, da hier bei jedem Backup die vollständige Datenbank gesichert wird und dementsprechend eine vollständige Datenbank zurück gespielt wird.
Die %PFAD% Variable ist hierbei der Ordner indem sich die Backupdateien befinden. Sollte in Ihrer Influx-Instanz schon die Datenbank "prom" existieren, werden Sie gefragt ob Sie diese löschen wollen, um die "prom"-Datenbank aus dem Backup laden zu können. Diese Operation ist notwendig, da hier bei jedem Backup die vollständige Datenbank gesichert wird und dementsprechend eine vollständige Datenbank wiederhergestellt wird.
### Backupmechanismus überprüfen
## Authentifizierung
TODO
## Passwort-Änderungs-Workflows
### Grafana
Für Grafana werden zwei Benutzer angelegt, ein Administrator und ein optionaler View-Benutzer mit der Berechtigung Dashboards anzuzeigen. Angelegt werden die Benutzer mit dem ```./provision/grafana/setup_grafana.sh```-Skript. Die Standardpasswörter für die beiden Benutzer können in folgenden JSON-Dateien bearbeiten werden. Nachdem die Benutzer erzeugt wurden, wird zusätzlich ein API-Token erstellt, mit dem anschließend alle Änderungen gemacht werden. Gespeichert wird dieser Token innerhalb der VM im ```/var/lib/grafana/token```-Verzeichnis. Anhand der Existenz dieses Tokens innerhalb der VM entscheidet das Skript, ob Grafana initial konfiguriert werden muss.
Für Grafana werden zwei Benutzer angelegt, ein Administrator und ein optionaler View-Benutzer mit der Berechtigung, Dashboards anzuzeigen. Angelegt werden die Benutzer mit dem Skript ```./provision/grafana/setup_grafana.sh```. Die Standardpasswörter für die beiden Benutzer können in folgenden JSON-Dateien bearbeiten werden. Nachdem die Benutzer erzeugt wurden, wird zusätzlich ein API-Token erstellt, mit dem anschließend alle Änderungen gemacht werden. Gespeichert wird dieser Token innerhalb der VM im Verzeichnis ```/var/lib/grafana/token```. Anhand der Existenz dieses Tokens innerhalb der VM entscheidet das Skript, ob Grafana initial konfiguriert werden muss.
```shell
./provision/grafana/config/users
......@@ -232,7 +228,7 @@ Für Grafana werden zwei Benutzer angelegt, ein Administrator und ein optionaler
#### Passwörter ändern
Das Ändern von Benutzer Passwörter sollte nach Möglichkeit über das Grafna-UI erfolgen, entweder als Admin oder vom Benutzer selbst. Daneben besteht noch die Option die HTTP-API zu benutzen. Hierfür können Sie sich am ```setup_grafana.sh```-Skript von Grafana orientieren und den CURL Befehl entweder mit BasicAuth oder mit dem API-Token bauen.
Das Ändern von Benutzer Passwörter sollte nach Möglichkeit über das Grafana-UI erfolgen, entweder als Admin oder vom Benutzer selbst. Daneben besteht noch die Option, die HTTP-API zu benutzen. Hierfür können Sie sich am ```setup_grafana.sh```-Skript von Grafana orientieren und den CURL Befehl entweder mit BasicAuth oder mit dem API-Token bauen.
#### Admin Passwort zurücksetzen
......@@ -245,23 +241,23 @@ sudo grafana-cli --homepath /usr/share/grafana admin reset-admin-password "newpa
### Influx
In der Influx-Datenbank werden drei Benutzer angelegt, ein Administrator und anschließend zwei weitere Benutzer für Grafana und Prometheus. Dabei ist festgelegt, dass der Prometheus Benutzer nur Schreib-Rechte und Grafana nur Lese-Rechte bekommt. Ausgeführt werden die Queries mit dem ```./provision/influx/setup_influx.sh```-Skript indem mit CURL die Queries an die HTTP-API von Influx gesendet werden. Beim ersten Start von Influxdb wird keine Authentifizierung für das Erzeugen eines Administrators verlang. Anschließend schaltet sich die Authentifizierung automatisch für die folgende Queries ein. Die Standardpasswörter für die Benutzer sind in folgenden Dateien gespeichert.
In der Influx-Datenbank werden drei Benutzer angelegt, ein Administrator und anschließend zwei weitere Benutzer für Grafana und Prometheus. Dabei ist festgelegt, dass der Prometheus-Benutzer nur Schreib-Rechte und Grafana nur Lese-Rechte bekommt. Ausgeführt werden die Queries mit dem Skript ```./provision/influx/setup_influx.sh``` indem mit CURL die Queries an die HTTP-API von Influx gesendet werden. Beim ersten Start von Influxdb wird keine Authentifizierung für das Erzeugen eines Administrators verlangt. Anschließend schaltet sich die Authentifizierung automatisch für die nachfolgenden Queries ein. Die Standardpasswörter für die Benutzer sind in folgenden Dateien gespeichert.
```shell
./provision/influx/
./setup_influx.sh # Admin-Benutzer
./config/setup.queries # Prometheus- und Grafana-Benutzer
./config/setup.queries # Prometheus- und Grafana-Benutzer
```
#### Passwörter ändern
Passwörter können Sie nur als Admin-Benutzer ändern. Die einfachste Möglichkeit wäre es im UI vom Chronografen in der Sektion 'InfluxDB Admin' diese zu ändern. Die andere Möglichkeit wäre mit dem Influx-CLI Tool sich auf der Influx-Datenbank anzumelden. Da das Tool die HTTP-API benutzt, kann auch von einer anderen VM die Anmeldung erfolgen, da das Tool aber im Moment nur auf der flux-VM liegt, wird hier eine Verbindung auf die flux-VM per SSH aufgebaut.
Passwörter können Sie nur als Admin-Benutzer ändern. Die einfachste Möglichkeit wäre es, im UI von Chronograf in der Sektion 'InfluxDB Admin' diese zu ändern. Die andere Möglichkeit wäre, sich mit dem Influx-CLI Tool auf der Influx-Datenbank anzumelden. Da das Tool die HTTP-API benutzt, kann auch von einer anderen VM die Anmeldung erfolgen. Für den Moment ist nur auf der flux-VM das Tool installiert, darum müssen wir und mit der flux-VM verbinden.
```shell
vagrant ssh flux
influx -ssl -unsafeSsl
influx -ssl -unsafeSsl
>auth
username:
username:
password:
>SET PASSWORD FOR "name" = 'newpass'
result message...
......@@ -273,11 +269,11 @@ Wenn Sie das Passwort von Prometheus oder Grafana ändern, müssen Sie auch die
Tragen Sie die neuen Benutzerdaten in folgende Datei ein, führen Sie die Provisionierung neu aus und laden Sie die Konfiguration neu.
```shell
nano ./provision/prometheus/config/prom.yml
nano ./provision/prometheus/config/prom.yml
vagrant provision prom
vagrant ssh prom
sudo curl -X POST http://localhost:9090/-/reload
sudo systemctl reload prometheus
```
##### Grafana
......@@ -307,7 +303,7 @@ sudo nano /etc/influxdb/influxdb.conf
systemctl restart influx
```
## Openssl
## Zertifikat-Änderungs-Workflows
Um den Datenverkehr zu verschlüsseln und die Dienste authentifizieren zu können, benötigen wir TLS-Zertifikat die wir mit dem Openssl-Toolkit erzeugen (<https://www.openssl.org/>). Hierfür wird zuerst ein Root-Zertifikat (cacert.pem) erzeugt und anschließend die Zertifikate für die Dienste Grafana, Influx und Chronograf. Diese werden von dem Root-Zertifikat signiert, sodass mit dem Root-Zertifikat die Authentifizierung erfolgen kann. Wichtig ist zu beachten, dass zu jedem Zertifikat auch ein Private-Key existiert, so z.B. cacert.pem und cakey.pem oder influxcert.pem und influxkey.pem.
......@@ -329,7 +325,7 @@ Im Config-Verzeichnis befinden sich die Konfigurationsdateien für die Zertifika
### Zertifikat-Seriennummer
Zertifikate enthalten nach dem X.509 Standard eine Seriennummer, die bei der Signierung bestimmt wird. Die mit dem ```./scripts/openssl_generate.sh``` erstellten und signierten Zertifikate werden standartmäßig mit der Seriennummer 0x2 aufwärts signiert. Manche Browser, wie z.B. der Firefox, melden aber einen Fehler, wenn vom Selben "Issuer: C, ST, L, O, OU, CN" eine vergebene Seriennummer nochmal an ein anderes Zertifikat vergeben wird. In diesem Fall können sie mit einem CLI-Argument die Anfangsseriennummer auf einen andere Wert setzen. Die Seriennummer wird als Hex-Zahl angegeben und die Anzahl der Ziffern muss gerade sein. So würde z.B. 0F1 zu einem Fehler führen und sollte als F1 oder 00F1 eingegeben werden.
Zertifikate enthalten nach dem X.509 Standard eine Seriennummer, die bei der Signierung bestimmt wird. Die mit dem ```./scripts/openssl_generate.sh``` erstellten und signierten Zertifikate werden standardmäßig mit der Seriennummer 0x2 aufwärts signiert. Manche Browser, wie z.B. der Firefox, melden aber einen Fehler, wenn vom Selben "Issuer: C, ST, L, O, OU, CN" eine vergebene Seriennummer nochmal an ein anderes Zertifikat vergeben wird. In diesem Fall können sie mit einem CLI-Argument die Anfangsseriennummer auf einen andere Wert setzen. Die Seriennummer wird als Hex-Zahl angegeben und die Anzahl der Ziffern muss gerade sein. So würde z.B. 0F1 zu einem Fehler führen und sollte als F1 oder 00F1 eingegeben werden.
```shell
#./scripts/openssl_generate.sh 01
......@@ -346,13 +342,17 @@ Zertifikate enthalten nach dem X.509 Standard eine Seriennummer, die bei der Sig
Wenn ein Private-Key auf irgendeine Art an Dritte verloren gegangen ist, müssen Sie reagieren. In diesem Fall ist zu unterscheiden, ob es sich um den cakey.pem, also der Root-Key oder den Key eines Dienstes wie grafanakey.pem handelt. Sollten Sie ihren Root-Key verlieren, ist ihre Kommunikation zwischen den Diensten auch für 3.te weiterhin sicher verschlüsselt, aber mit dem Root-Key könnten fremde Zertifikate signiert werden, welche dann von Ihrem installierten Root-Zertifikat als gültig anerkannt werden würden. Im zweiten Fall, wenn Sie den Privat-Key eines Dienstes verloren haben, könnten zwar keine Zertifikate signiert werden, aber mit dem aktuellen Privat-Key, kann sich ein 3.ter als der Dienst ausgeben, für den das Zertifikat ausgestellt wurde. Des Weiteren sind die mit dem Zertifikat aufgebauten verschlüsselten Verbindungen auch nur noch bedingt sicher vor dem Mitlesen Dritter.
* Root-Key verloren, bedeutet, dass alle Zertifikate neu erzeugt werden müssen. Zusätzlich müssen sie jeden informieren, dem aktuellen Root-Zertifikat cacert.pem das Vertrauen zu entziehen. Führen Sie ```./scripts/openssl_generate.sh``` neu aus und verteilen die Zertifikate mit dem Vagrant File-Provisionierer neu auf die Maschinen. Beachten Sie die Zertifikat-Seriennummer.
### cakey.pem
Root-Key verloren bedeutet, dass alle Zertifikate neu erzeugt werden müssen. Zusätzlich müssen sie jeden informieren, dem aktuellen Root-Zertifikat cacert.pem das Vertrauen zu entziehen. Führen Sie ```./scripts/openssl_generate.sh``` neu aus und verteilen die Zertifikate mit dem Vagrant File-Provisionierer neu auf die Maschinen. Beachten Sie die Zertifikat-Seriennummer.
```shell
./scripts/openssl_generate.sh
./scripts/openssl_generate.sh
vagrant provision --all
```
### Dienst-key.pem
* Dienst-Key verloren, bedeutet, dass Sie nur das jeweilige Zertifikat ersetzen müssen.
```shell
......@@ -360,6 +360,8 @@ vagrant provision --all
vagrant provision (flux | graf | chron)
```
TODO split, cakey und dienstkey
### Eigene Zertifikate
Wenn Sie eigene Zertifikate erzeugen und diese in diesem Workflow benutzen möchten, müssen Sie diese an die entsprechenden Pfade kopieren oder verlinken. Standardmäßig werden die erzeugten Zertifikate aus ```./openssl/data/certificates``` mit dem jeweiligen Provision-Verzeichnis der VMs verlinkt. Sie können an dieselben Stellen ````./provision/*/https``` Ihre Zertifikate kopieren und mit dem Provisionierer diese übertragen lassen. Sollten ihre Zertifikate nicht wie unten benannt werden können, müssen Sie zusätzlich in den Konfigurationen die geänderten Dateinamen eintragen.
......@@ -384,4 +386,4 @@ Wenn Sie eigene Zertifikate erzeugen und diese in diesem Workflow benutzen möch
./cacert.pem
./influxcert.pem
./influxkey.pem
```
\ No newline at end of file
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment