Commit 0e6936df authored by k.elaammari's avatar k.elaammari
Browse files

readme

parent 5e495c0c
# Dokumentation
# Dokumentation 'vagrant-prometheus'
## Openssl
Um den Datenverkehr zu verschlüsseln und die Dienste authentifizieren zu können, benötigen wir TLS-Zertifikat die wir 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 zu beachten ist, dass zu jedem Zertifikat auch ein Private-Key existiert, z.B. cacert.pem und cakey.pem oder influxcert.pem und influxkey.pem.
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 zu beachten ist, dass zu jedem Zertifikat auch ein Private-Key existiert, wie z.B. cacert.pem und cakey.pem oder influxcert.pem und influxkey.pem.
### Struktur
......@@ -18,11 +18,11 @@ Um den Datenverkehr zu verschlüsseln und die Dienste authentifizieren zu könne
./csrdb
```
Im Config Verzeichnis befinden sich die Konfigurationsdateien für die Zertifikate. Mit diesen können Sie den Standardwerten wie: organizationName, commonName, emailAddress andere Werte zuweisen, die dann beim Erzeugen der Zertifikate übernommen werden. Das Data Verzeichnis wird erst nachdem ausführen von ```./scripts/openssl_generate.sh``` erstellt und enthält die Zertifikate im Ordner "certificates", sowie den Zustand der Openssl-Textdatenbank im Ordner "csrdb". Diese wird für das Signieren der Zertifikate gebraucht und enthält unteranderem die aktuelle Seriennummer.
Im Config Verzeichnis befinden sich die Konfigurationsdateien für die Zertifikate. In diesen können Sie die Standardwerte für organizationName, commonName, emailAddress, usw. ändern, die bei der Erzeugen in die Zertifikate übernommen werden. Das Data Verzeichnis wird erst nachdem ausführen von ```./scripts/openssl_generate.sh``` erstellt und enthält die Zertifikate im Ordner "certificates", sowie den Zustand der Openssl-Textdatenbank im Ordner "csrdb". Csrdb wird für das Signieren der Zertifikate gebraucht und enthält unteranderem die aktuelle Seriennummer.
### Zertifikat-Seriennummer
Zertifikate enthalten nach dem X.509 Standard eine Seriennummer, die bei der Signierung bestimmt wird. Die mit dem ```./scripts/openssl_generate.sh``` 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 bereits vergebene Seriennummer nochmal an ein anderes Zertifikat vergeben wird. In diesem Fall können sie mit einem CLI-Argument die anfangs Seriennummer setzen. Die Seriennummer wird als Hex-Zahl angegeben und die Anzahl der Ziffern muss grade 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 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 anfangs Seriennummer auf eine andere Wert setzen. Die Seriennummer wird als Hex-Zahl angegeben und die Anzahl der Ziffern muss grade 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
......@@ -80,34 +80,65 @@ Wenn Sie eigene Zertifikate erzeugen und diese in diesem Workflow benutzen möch
## Authentifizierung
In diesem Abschnitt wird auf die erstellten Zugangsdaten in diesem Projekt eingeganeg.
In diesem Abschnitt wird gezeigt wie die Benutzer für Influx und Grafana erstellt werden.
### Grafana
Für Grafana werden zwei Benutzer angelegt. Ein Administrator und ein optionaler View-Bentuezr, der nur die Berechtigung hat Dashboards anzuzeigen. Angelegt werden die Benutzer mit dem ```./provision/grafana/config/setup_grafana.sh```-Skript. Die Standardwerte für diese beiden Benutzer können im ```./provision/grafana/users```-Verzechnis bearbeitet werden.
Für Grafana werden zwei Benutzer angelegt. Ein Administrator und ein optionaler View-Bentuezr, der nur die Berechtigung hat Dashboards anzuzeigen. Angelegt werden die Benutzer mit dem ```./provision/grafana/config/setup_grafana.sh```-Skript. Die Standardpasswörter für die beiden Benutzer können in folgenden JSON-Dateien bearbeiten werden.
```shell
./provision/grafana/config/users
./admin_password.json
./view_user.json
```
#### Passwort ändern
Das ändern von Benutzer Passwörter sollten nach Möglichkeit über das Web-Interface 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
Sollten Sie keinen ZUgriff mehr haben, müssen Sie das Passwort über die Grafana-CLI zurücksetzen.
Sollten keine Zugriff mehr auf den Admin-Benutzer bestehen, kann mit der Grafana-CLI das Passwort zurückgesetzen werden. Hierfür muss local auf der VM folgender Befehl ausgeführt werden.
```shell
TODO funktioniert aber nicht wie in der Grafana Doku beschrieben.
vagrant ssh graf # verbinden mit der VM
sudo grafana-cli --homepath /usr/share/grafana admin reset-admin-password newpass
```
### Influx
In der InfluxDB wir ein Admin-Benutzer mit allen Berechtigungen erzeugt und anschließend werden mit diesem zwei weitere Benutzer für Grafana und Prometheus erstellt. Die Standardwete hierfür sind in folgenden Dateien. Dabei ist festgelegt, dass der Prometheus Bentutzer nur Schreib-Rechte und Grafana nur Lese-Rechte bekommt.
```shell
./provision/influx/config
./admin.pw
./setup.queries
```
Sollten Sie an diesen Werten etwas ändern, müssen Sie auch in den Konfigurationen von Prometheus und Grafana dies vornehmen. Für Prometheus öffnen Sie die ```./provision/prometheus/config/prom.yml``` und tragen unten in der Sektion "remote_write:" die aktualisierten Benutzerdaten ein. Bei Grafana müssen Sie in ````./provision/grafana/config/datasources/ds_influx.json``` die neuen Benutzerdaten eintragen. Dieser Option setzt aber voraus, dass Sie die Maschinen neu provisionieren müssen.
#### Passwörter ändern (live)
Wenn Sie das Passwort für den Grafana nutzer ändern möchten, können Sie dies im Chronograf Web-Interface in der Sektion "InfluxDB Admin" tun. Sobald Sie die Änderung bei der InfluxDB vorgenommen haben, müssen Sie auch in Grafana dies aktualisieren. Hierfür wechseln Sie in das Grafana Web-Interface und von hier nach "Configurationen" > "Data Sources" > "InfluxDB" und tragen hier die neuen Benutzerdaten ein.
## Provisionierung
Um den Influx-Benutzer in Prometheus zu ändern ohne die Provisionierung neu auszuführen und ohne Restart des Services, müssen Sie die Lokale Konfiguration bearbeiten.
``` Shell
vagrant ssh prom # mit VM verbinden
sudo nano /etc/prometheus/prometheus.yml # Lokale Konfiguration
sudo curl -X POST http://localhost:9090/-/reload # Konfiguration neu laden
```
Denken Sie daran auch in der Konfiguration im Projektverzeichnis diese Änderung vorzunehmen, da ansonsten beim nächsten Durchlauf der Provisionierung die Konfiguration mit den alten Werten überschriben werden würde.
#### Admin Passwort zurücksetzen
Sollte ein 2.ter Adminnutzer existieren, kann dieser sich mit dem Chronograf anmelden und das Passwort über das Web-Interface ändern. Existiert nur ein Admin, muss lokal auf der VM das Passwort zurückgestzt werden, indem die Authentifizierung kurzfristig ausgeschaltet wird.
TODO
## Dateistruktur des Projekts
### Klassifizierung von Dateien
Um eine überschaubare Umgebung zu schaffen wird versucht die hier verwendeten Daten und Dateien in drei Kategorien zu unterteilt.
Um eine überschaubare Umgebung zu schaffen, wird versucht die hier verwendeten Daten und Dateien in drei Kategorien zu unterteilt.
#### 1. Executable
......@@ -147,7 +178,7 @@ In die Kategorie Executable fallen alle Binären oder Ausführbaren Dateien. In
#### 2. Konfigurations-Daten
Konfigurationsdateien werden beim Start der Executables gebraucht. Hierrunter fallen z.B. Ini- oder Conf-Dateien. Einen Sonderfall in diesem Projekt haben die Text- und JSON-Dateien, diese enthalten Daten, die nicht direkt von den Executables interpretiert werden. So werden z.B. die JSON-Dateien mittels CURL an die HTTP-API von Grafana gesendet, um einen Zustand zu erzeugen. Da der Workflow für Openssl bzw. Zertifikate oben schon beschrieben wurde, wird hier kein Bezug darauf genommen.
Konfigurationsdateien werden beim Start der Executables gebraucht. Hierrunter fallen z.B. Ini- oder Conf-Dateien. Einen Sonderfall in diesem Projekt haben die Text- und JSON-Dateien, diese enthalten Daten, die nicht direkt von den Executables interpretiert werden. So werden z.B. die JSON-Dateien mittels CURL an die HTTP-API von Grafana gesendet, um einen Zustand zu erzeugen. Da der Workflow für Openssl bzw. Zertifikate oben schon beschrieben wurde, wird hier kein Bezug mehr darauf genommen.
```shell
.vagrant-prometheus/
......@@ -189,8 +220,6 @@ Weiter Benutzerdaten befinden sich auf den VMs.
/var/lib/chronograf/chronograf-v1.db
```
Chronograf speichert hier in einer Datenbank die übers das Web-Interface eingegebenen Daten.
* Grafana
```shell
......@@ -199,7 +228,6 @@ Weiter Benutzerdaten befinden sich auf den VMs.
./token/apitoken.json
```
Grafana speichert auch seinen Zustand in einer sqlite3 Datenbank. Und der aktuellen Bearer Token für die HTTP-API wird hier abgelegt.
* Influxdb
```shell
......@@ -209,16 +237,12 @@ Weiter Benutzerdaten befinden sich auf den VMs.
./wal
```
Im Data- und Wal-Verzeichnis speichert Influx die Datenbanken, '_internal' und 'prom'. WAL steht für Write-ahead-log und enthält somit Daten, die nachträglich in das Data-Verzeichnis übertragen werden.
* Prometheus
```shell
/var/lib/prometheus/data
```
Prometheus speichert hier die gesammelten Daten zwischen, da die Daten aber direkt in die Influx-Datenbank weitergeleitet werden, gibt es hier keinen Backup- und Restore-Workflow.
## Vagrant Kommandos
* ```vagrant up <vm>```
......@@ -232,9 +256,4 @@ Weiter Benutzerdaten befinden sich auf den VMs.
* ```vagrant ssh <vm>```
Baut eine SSH Verbindung mit dem von Vagrant hinzugefügten Key auf.
## Sicherheitsaspekte
### Schließen von Ports
### Listen port
\ 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