20171120 README.ubuntu.md (Überarbeitung nach Erfahrungen mit Debian 9)

README.ubuntu.md

@@ -1,19 +1,14 @@
 # ffdo Status Setup unter Linux
 
-Hier wird beschrieben wie das ffdo status System unter linux aufgesetzt werden kann. Dabei werden vorwiegend die Schritte beschrieben die notwendig sind um das System zu installieren und sich von der Installation von anderen Betriebssystemen unterscheiden.
-Also Basis dient ein [Ubuntu](https://ubuntu.com) System. Andere debian basierte Systeme sind sehr ähnlich und Distributionen mit rpm Nutzung sind ähnlich.
+Hier wird beschrieben wie ein ffdo Status System mit [nodes2grafana](README.md) auf GNU/Linux aufgesetzt werden kann. Im Folgenden werden vorwiegend die Schritte beschrieben, die sich von der Installation auf anderen Betriebssystemen unterscheiden.
 
-### Installation benötigter Programme
+Als Basis dient ein [Ubuntu](https://ubuntu.com) System. Andere [Debian](https://www.debian.org/) basierte Systeme sind sehr ähnlich und Distributionen mit rpm Nutzung sind ähnlich.
 
-#### Werkzeuge zum Erstellen von nodes2grafana
-nodes2grafana wird lokal gebaut.
-Die Basis der Entwicklung ist das Meta Paket **build-essential**:
+## Installation benötigter Programme
 
-    sudo apt-get -y install build-essential
+### Werkzeuge zum Erstellen von nodes2grafana
 
-Zusätzlich wird noch **smlnj** benötigt:
-
-    sudo apt-get -y install smlnj ml-lpt
+nodes2grafana wird lokal gebaut.
 
 Mit dem Programm git kann man den Quellcode von nodes2grafana kopieren.
 
@@ -21,20 +16,23 @@ Installieren von git:
 
     sudo apt-get -y install git
 
+Die Basis der Entwicklung ist das Meta Paket **build-essential**:
 
+    sudo apt-get -y install build-essential
 
-#### Werkzeuge zum Erstellen von nodes2grafana
-
-Installation weiterer notwendiger Services
+(Es darf ggf. auch etwas weniger sein: `sudo apt-get -y install make xz-utils` reicht.)
 
-    sudo apt -y install prometheus prometheus-node-exporter grafana
+Zum Kompilieren wird schließlich noch **smlnj** benötigt:
 
+    sudo apt-get -y install smlnj ml-lpt
 
+### Services für den Betrieb von nodes2grafana
 
-### Erstellen von nodes2grafana
+Installation der für einen Status-Dienst nötigen Services:
 
+    sudo apt -y install prometheus prometheus-node-exporter grafana
 
-#### nodes2grafana Erzeugen
+## nodes2grafana bauen
 
 nodes2grafana wird lokal gebaut. Dazu muss der Quellcode geladen und übersetzt werden.
 
@@ -42,91 +40,99 @@ Laden des nodes2grafana Quellcodes mit **git**:
 
     git clone https://git.ffdo.de/altlast/nodes2grafana.git
 
+Alternativ kann man auch das bereits vorhandene **wget** oder **curl** verwenden um den Quellcode von [nodes2grafana](https://git.ffdo.de/altlast/nodes2grafana/archive/master.tar.gz) als Paket zu laden. Das Paket muss anschließend entpackt werden.
 
-Alternativ kann man auch das bereits vorhandene **wget** oder **curl** verwenden um den Quellcode von [nodes2grafana](https://git.ffdo.de/altlast/nodes2grafana/archive/master.tar.gz) als Paket  zu laden. Das Paket muss dann an geeigneter Stelle entpackt werden.
-
-Übersetzen des Programms:
+Konfigurieren und Übersetzen des Programms:
 
     cd nodes2grafana
-    make -C conf && make
+    make -C conf
     cp conf/substitutions.conf.default conf/substitutions.conf.local
     vi conf/substitutions.conf.local
+    make -C conf && make
 
+## nodes2grafana installieren
 
-## Betrieb
-
-Nach der Übersetzung nodes2grafana kann nun das System in Betrieb genommen werden.
-
-### Installation von nodes2grafana 
-
-Installation von nodes2grafana
+Installation von nodes2grafana:
 
      sudo mv conf/substitutions.conf.local /etc/nodes2grafana.conf
      sudo make install
 
+## Betrieb
 
+Nach der Installation von nodes2grafana kann nun der Status-Dienst in Betrieb genommen werden.
 
 ### prometheus-node-exporter anpassen
 
-prometheus-node-exporter Überprüfen:
+Zuerst prüfen, ob schon ein node_exporter läuft:
 
-    sudo prometheus-node-exporter -web.listen-address=localhost:9100 -collector.textfile.directory=/var/tmp/node_exporter -collectors.enabled=textfile
+    netstat -l -n | grep :9100
 
-Das kann folgende Ausgaben liebern, wenn schon ein prometheus-node-exporter service läuft:
+und/oder
 
-    INFO[0000] Enabled collectors:                           file=node_exporter.go line=142
-    INFO[0000]  - textfile                                   file=node_exporter.go line=144
-    INFO[0000] Starting node_exporter v0.0.0.dev at localhost:9100  file=node_exporter.go line=176
-    FATA[0000] listen tcp 127.0.0.1:9100: bind: address already in use  file=node_exporter.go line=179
+    systemctl status prometheus-node-exporter.service
 
-In diesem Fall sollte man den Service prometheus-node-exporter stoppen:
-    sudo systemctl stop prometheus-node-exporter.service
+Die default Startparameter in `/etc/default/prometheus-node-exporter` sind ausreichend. Eine angepasste, minimalistische Start-Konfiguration sähe zB so aus:
 
-prometheus-node-exporter testen:
-    sudo prometheus-node-exporter -web.listen-address=localhost:9100 -collector.textfile.directory=/var/tmp/node_exporter -collectors.enabled=textfile
+    # Set the command-line arguments to pass to the server.
+    ARGS="-web.listen-address=localhost:9100 \
+          -collectors.enabled=textfile \
+          -collector.textfile.directory=/var/lib/prometheus/node-exporter"
 
-Das muss man dann mit Cntrl-C abbrechen.
-Anschließend werden die default Start Parameter von prometheus-node-exporter angepasst:
+Also ggf.
 
-    sudo vi  /etc/default/prometheus-node-exporter
+    sudo vi /etc/default/prometheus-node-exporter
 
-Die ersten Zeilen sollten etwa so aussehen:
+sowie anschließend
 
-    # Set the command-line arguments to pass to the server.
-    ARGS='-web.listen-address=localhost:9100 -collector.textfile.directory=/var/tmp/node_exporter -collectors.enabled=textfile'
-
-Jetzt ist der prometheus-node-exporter Service neu zu starten:
     sudo systemctl restart prometheus-node-exporter.service
 
+Einen kleinen Test, ob der node_export soweit gut aussieht, bekommt man dann auf der Seite <http://localhost:9100/metric>.
 
 ### prometheus Installation anpassen
 
-Zuerst werden die Standard Startparameter angepasst:
+Zunächst kann man bei Bedarf die Standard Startparameter anpassen:
 
      sudo vi /etc/default/prometheus
 
+Das ist zB dann nötig, wenn die eingesammelten Zeitreihen länger oder kürzer gespeichert werden sollen als der default von 15 Tagen (s. -storage.local.retention). Oder wenn der `hostname` des OS nicht zu einer IP-Adresse aufgelöst werden kann, zB weil er keinen A record im DNS hat, dann die IP Adresse bei -web.external-url setzen. Beispiel:
+
      # Set the command-line arguments to pass to the server.
-     ARGS="-config.file=/etc/prometheus/prometheus.yml -storage.local.retention 336h0m0s"
+     ARGS="-storage.local.retention 24h0m0s \
+           -web.external-url http://31.172.33.14:9090/"
 
+Wenn man etwas geändert hat:
 
-Die Konfigurationsdatei <big>/etc/prometheus/prometheus.yml</big> passt soweit.
+    sudo systemctl restart prometheus.service
+
+Die Konfigurationsdatei <big>/etc/prometheus/prometheus.yml</big> passt soweit. Denn sie enthält bereits einen Eintrag, um den lokalen node_exporter zu scrapen:
+
+    - job_name: node
+      # If prometheus-node-exporter is installed, grab stats about the local
+      # machine by default.
+        static_configs:
+          - targets: ['localhost:9100']
+
+Wenn man doch noch etwas an der Konfiguration ändern möchte:
 
     sudo vi /etc/prometheus/prometheus.yml
 
+sowie anschließend die Konfiguration (neu) laden:
 
-Also direkt den Service (neu) starten:
-    sudo systemctl restart prometheus.service
+    sudo systemctl reload prometheus.service
 
-Ein kleiner Test, ob prometheus soweit gut aussieht, bekommt man dann auf der Seite bekommen: [http://localhost:9100/metric]
+Einen kleinen Test, ob prometheus soweit gut aussieht, bekommt man dann auf den Seiten:
 
+- <http://localhost:9090/metric>,
+- <http://localhost:9090/targets>,
+- <http://localhost:9090/graph?g0.range_input=1h&g0.expr=ffdo_nodes_summary&g0.tab=0>.
 
-### grafana Installtion anpassen
+### grafana Installation anpassen
 
-Abschließend ist die grafana anzupassen:
+Abschließend ist die grafana Konfiguration anzupassen:
 
     sudo vi /etc/grafana/grafana.ini
 
-Hiermit wird er anonyme Ledezugriff ermöglicht:
+Hiermit wird der anonyme Lesezugriff ermöglicht:
 
     #################################### Anonymous Auth ##########################
     [auth.anonymous]
@@ -149,28 +155,26 @@ So ziemlich am Ende sind zwei Zeilen anzupassen um de vordefinierten Übersichte
     ;#################################### Dashboard JSON files ##########################
     [dashboards.json]
     enabled = true
-    path group: '= /var/lib/grafana/dashboards
-
+    path = /var/lib/grafana/dashboards
 
 Das Verzeichnis **/var/lib/grafana/dashboards** sollte bei der Installation von nodes2grafana bereits angelegt und gefüllt worden sein. Ansonsten muss man das per Hand machen:
 
     sudo mkdir /var/lib/grafana/dashboards
-    sudo cp /var/db/grafana/dashboards/FF-DO-status* /var/lib/grafana/dashboards/
+    sudo cp -p dashboards/FF-DO-status*.json /var/lib/grafana/dashboards/
     sudo chown -R grafana:grafana /var/lib/grafana/dashboards
 
 Jetzt ist der grafana Service neu zu starten:
-    sudo systemctl restart grafana.service
-
 
+    sudo systemctl restart grafana.service
 
-Jetzt muss man noch in grafana als Datenquelle der lokale prometheus Service eintragen werden.
-Eine detaillierte Anleitung gibt es auch unter [prometheus](http://docs.grafana.org/features/datasources/prometheus/)
+Nun muss noch in grafana als Datenquelle der lokale prometheus Service eintragen werden.
+Eine detaillierte Anleitung gibt es auch unter [prometheus](http://docs.grafana.org/features/datasources/prometheus/).
 
-Grafana aufrufen:
-  (http://localhost:3000')
+Grafana aufrufen: <http://localhost:3000/>.
 
 Dann als 'admin' einloggen, Password 'admin'.
-Anschließend unter [http://localhost:3000/datasources] eine neue Datenquelle hinzufügen:
+
+Anschließend unter <http://localhost:3000/datasources> eine neue Datenquelle hinzufügen:
 
     Name:       prometheus-local (beliebig)
     Default:    aktiviert
@@ -178,5 +182,9 @@ Anschließend unter [http://localhost:3000/datasources] eine neue Datenquelle hi
     
     Url:        http://localhost:9090
     Access:     direct
-    
+
+(Falls nur grafana, nicht aber prometheus auf einer öffentlich erreichbaren IP-Adresse lauscht, dann darf hier nicht `direct` gewählt werden, sondern `proxy`.)
+
 Auf 'Add' klicken.
+
+Dabei auf Fehlermeldungen achten, und bei grünem Licht (Datasource OK) die FF-DO-Dashboards ausprobieren.