feat: documented how to export telegraf data

docs/administrator-manual/advanced-cli/telegraf_prometheus.md

@@ -0,0 +1,189 @@
+---
+title: "Telegraf Prometheus exporter"
+sidebar_position: 13
+---
+
+# Telegraf Prometheus exporter {#telegraf-prometheus-exporter}
+
+Telegraf collects the system and service metrics of the firewall and writes them
+to the local VictoriaMetrics instance. Starting from NethSecurity 8.8, Telegraf
+can also expose the very same metrics in Prometheus format, so an external
+Prometheus server, Grafana Agent or any other compatible collector can scrape
+them directly from the firewall.
+
+The exporter is **disabled by default**.
+
+## Enabling the exporter {#enabling-the-exporter}
+
+Always pick a listening port other than the default `9273`: that port is
+reserved for the controller, which scrapes the unit through the VPN tunnel.
+Port `9274` is a safe choice.
+
+1. Open a terminal window on the firewall.
+2. Enable the Prometheus output on port `9274` and apply the change:
+
+``` bash
+uci set telegraf.output_prometheus.enabled='1'
+uci set telegraf.output_prometheus.listen_addr=':9274'
+uci commit telegraf
+reload_config
+```
+
+3. Check that the metrics are served:
+
+``` bash
+curl -s http://127.0.0.1:9274/metrics | head
+```
+
+The exporter now listens on port `9274` and publishes the metrics on the
+`/metrics` path. Continue with [Accessing the exporter
+remotely](#accessing-the-exporter-remotely) to reach it from the collector.
+
+:::danger
+
+The exporter binds every address of the firewall, so the port is reachable from
+every zone whose input policy is `ACCEPT`. With the default configuration this
+means the whole LAN; if the input policy of a WAN or guest zone has been changed
+to `ACCEPT`, the metrics are exposed there too. Never leave the port open like
+that: restrict it as described in [Restricting access to the
+metrics](#restricting-access-to-the-metrics).
+
+:::
+
+:::warning
+
+If the exporter is left on the default port `9273` while the firewall is
+connected to a controller, two Prometheus outputs compete for the same port and
+one of them fails to bind. See [Units connected to a
+controller](#telegraf-prometheus-controller).
+
+:::
+
+## Accessing the exporter remotely {#accessing-the-exporter-remotely}
+
+Two options are available. Both of them restrict who can read the metrics, so
+pick the one that fits the collector.
+
+### Reverse proxy path {#reverse-proxy-path}
+
+Recommended: the metrics travel over HTTPS on port 443 and no extra port is
+opened on the firewall. Go to the [Certificates and reverse
+proxy](../network/reverse_proxy.md) page, click **Add reverse proxy** and fill
+in:
+
+- `Type`: **Path**, for example `/telegraf-metrics`
+- `Destination URL`: `http://127.0.0.1:9274/metrics`
+- `Allowed networks`: the address of the collector in CIDR format, for example
+  `203.0.113.5/32`
+
+The metrics are then available at `https://<firewall-ip>/telegraf-metrics`.
+
+### Firewall input rule {#firewall-input-rule}
+
+Use this option when the collector must reach port `9274` directly. Go to the
+[Rules](../firewall/firewall_rules.md) page, `Input rules` tab, and add a rule
+with:
+
+- `Source address`: the address of the collector
+- `Source zone`: the zone the collector belongs to
+- `Destination service`: **Custom**, protocol `TCP`, port `9274`
+- `Action`: **Accept**
+
+The metrics are then available at `http://<firewall-ip>:9274/metrics`. This rule
+alone does not close the port to the other zones: complete the configuration as
+described in [Restricting access to the
+metrics](#restricting-access-to-the-metrics). The exporter is exposed in clear
+text, so also protect it with a password.
+
+## Restricting access to the metrics {#restricting-access-to-the-metrics}
+
+Choose one of the two following approaches, depending on how the collector
+reaches the exporter.
+
+**With the reverse proxy path**, bind the exporter to the loopback address only:
+nothing is published on the network interfaces and the reverse proxy remains the
+single entry point, filtered by its `Allowed networks` field.
+
+``` bash
+uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274'
+uci commit telegraf
+reload_config
+```
+
+**With a firewall input rule**, close the port to everyone else. On the
+[Rules](../firewall/firewall_rules.md) page, `Input rules` tab, add a second
+rule *below* the one that accepts the collector:
+
+- `Source address`: any source address
+- `Source zone`: Any
+- `Destination service`: **Custom**, protocol `TCP`, port `9274`
+- `Action`: **Drop**
+
+The first matching rule wins, so the collector is accepted and every other host
+is dropped, whatever the input policy of its zone is.
+
+## Protecting the exporter with a password {#protecting-the-exporter-with-a-password}
+
+The exporter can require HTTP basic authentication. Both the user name and the
+password must be set, otherwise authentication is not configured at all:
+
+``` bash
+uci set telegraf.output_prometheus.basic_auth_username='prometheus'
+uci set telegraf.output_prometheus.basic_auth_password='<password>'
+uci commit telegraf
+reload_config
+```
+
+Verify the credentials with:
+
+``` bash
+curl -s -u prometheus:'<password>' http://127.0.0.1:9274/metrics | head
+```
+
+:::warning
+
+The exporter serves plain HTTP and has no authentication until the two options
+above are set. Do not expose it outside a trusted network without a password.
+
+:::
+
+## Changing the listening address {#changing-the-listening-address}
+
+The `listen_addr` option accepts the `address:port` syntax; when the address is
+omitted, Telegraf binds all the available IPv4 and IPv6 addresses.
+
+To restrict the exporter to a single address:
+
+``` bash
+# only reachable from the firewall itself, enough for the reverse proxy path
+uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274'
+
+# only reachable on a specific LAN address
+uci set telegraf.output_prometheus.listen_addr='192.168.1.1:9274'
+
+uci commit telegraf
+reload_config
+```
+
+## Units connected to a controller {#telegraf-prometheus-controller}
+
+When the firewall is connected to a controller, the controller already scrapes
+Telegraf through the VPN tunnel: at every connection the unit binds port `9273`
+on its own VPN address.
+
+That endpoint is managed by the system and must be left alone. Keep the
+`listen_addr` of the exporter on a different port, as described in [Enabling the
+exporter](#enabling-the-exporter), and both endpoints coexist without
+interfering with each other.
+
+## Disabling the exporter {#disabling-the-exporter}
+
+``` bash
+uci set telegraf.output_prometheus.enabled='0'
+uci commit telegraf
+reload_config
+```
+
+Local monitoring and the metrics stored in VictoriaMetrics are not affected: the
+exporter is an additional output, and disabling it only stops the Prometheus
+endpoint.

i18n/it/docusaurus-plugin-content-docs/current/administrator-manual/advanced-cli/telegraf_prometheus.md

@@ -0,0 +1,195 @@
+---
+title: "Esportatore Prometheus di Telegraf"
+sidebar_position: 13
+---
+
+# Esportatore Prometheus di Telegraf {#telegraf-prometheus-exporter}
+
+Telegraf raccoglie le metriche di sistema e dei servizi del firewall e le scrive
+nell'istanza locale di VictoriaMetrics. A partire da NethSecurity 8.8, Telegraf
+può esporre le stesse metriche anche in formato Prometheus, così un server
+Prometheus esterno, Grafana Agent o qualsiasi altro collettore compatibile può
+leggerle direttamente dal firewall.
+
+L'esportatore è **disabilitato per impostazione predefinita**.
+
+## Abilitare l'esportatore {#enabling-the-exporter}
+
+Scegliere sempre una porta di ascolto diversa da quella predefinita `9273`:
+quella porta è riservata al controller, che legge le metriche dell'unità
+attraverso il tunnel VPN. La porta `9274` è una scelta sicura.
+
+1. Aprire un terminale sul firewall.
+2. Abilitare l'output Prometheus sulla porta `9274` e applicare la modifica:
+
+``` bash
+uci set telegraf.output_prometheus.enabled='1'
+uci set telegraf.output_prometheus.listen_addr=':9274'
+uci commit telegraf
+reload_config
+```
+
+3. Verificare che le metriche vengano servite:
+
+``` bash
+curl -s http://127.0.0.1:9274/metrics | head
+```
+
+L'esportatore ora ascolta sulla porta `9274` e pubblica le metriche sul percorso
+`/metrics`. Proseguire con [Accedere all'esportatore da
+remoto](#accessing-the-exporter-remotely) per raggiungerlo dal collettore.
+
+:::danger
+
+L'esportatore si lega a tutti gli indirizzi del firewall, quindi la porta è
+raggiungibile da ogni zona la cui politica di ingresso è `ACCEPT`. Con la
+configurazione predefinita questo significa tutta la LAN; se la politica di
+ingresso di una zona WAN o guest è stata modificata in `ACCEPT`, le metriche
+sono esposte anche lì. Non lasciare mai la porta aperta in questo modo:
+limitarla come descritto in [Limitare l'accesso alle
+metriche](#restricting-access-to-the-metrics).
+
+:::
+
+:::warning
+
+Se l'esportatore viene lasciato sulla porta predefinita `9273` mentre il
+firewall è collegato a un controller, due output Prometheus entrano in
+competizione sulla stessa porta e uno dei due non riesce ad aprirla. Vedere
+[Unità collegate a un controller](#telegraf-prometheus-controller).
+
+:::
+
+## Accedere all'esportatore da remoto {#accessing-the-exporter-remotely}
+
+Sono disponibili due opzioni. Entrambe limitano chi può leggere le metriche,
+quindi scegliere quella più adatta al collettore.
+
+### Percorso su reverse proxy {#reverse-proxy-path}
+
+Consigliata: le metriche transitano su HTTPS sulla porta 443 e non viene aperta
+nessuna porta aggiuntiva sul firewall. Accedere alla pagina [Certificati e
+reverse proxy](../network/reverse_proxy.md), fare clic su **Aggiungi reverse
+proxy** e compilare:
+
+- `Type`: **Path**, per esempio `/telegraf-metrics`
+- `Destination URL`: `http://127.0.0.1:9274/metrics`
+- `Allowed networks`: l'indirizzo del collettore in formato CIDR, per esempio
+  `203.0.113.5/32`
+
+Le metriche sono poi disponibili all'indirizzo
+`https://<firewall-ip>/telegraf-metrics`.
+
+### Regola di firewall in ingresso {#firewall-input-rule}
+
+Usare questa opzione quando il collettore deve raggiungere direttamente la porta
+`9274`. Accedere alla pagina [Regole](../firewall/firewall_rules.md), scheda
+`Regole di ingresso`, e aggiungere una regola con:
+
+- `Indirizzo sorgente`: l'indirizzo del collettore
+- `Zona sorgente`: la zona a cui appartiene il collettore
+- `Servizio di destinazione`: **Personalizzato**, protocollo `TCP`, porta `9274`
+- `Azione`: **Accetta**
+
+Le metriche sono poi disponibili all'indirizzo
+`http://<firewall-ip>:9274/metrics`. Questa regola da sola non chiude la porta
+alle altre zone: completare la configurazione come descritto in [Limitare
+l'accesso alle metriche](#restricting-access-to-the-metrics). L'esportatore è
+esposto in chiaro, quindi proteggerlo anche con una password.
+
+## Limitare l'accesso alle metriche {#restricting-access-to-the-metrics}
+
+Scegliere uno dei due approcci seguenti, in base a come il collettore raggiunge
+l'esportatore.
+
+**Con il percorso su reverse proxy**, legare l'esportatore solo all'indirizzo di
+loopback: nulla viene pubblicato sulle interfacce di rete e il reverse proxy
+resta l'unico punto di accesso, filtrato dal suo campo `Allowed networks`.
+
+``` bash
+uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274'
+uci commit telegraf
+reload_config
+```
+
+**Con una regola di firewall in ingresso**, chiudere la porta a tutti gli altri.
+Nella pagina [Regole](../firewall/firewall_rules.md), scheda `Regole di
+ingresso`, aggiungere una seconda regola *sotto* quella che accetta il
+collettore:
+
+- `Indirizzo sorgente`: qualsiasi indirizzo sorgente
+- `Zona sorgente`: Qualsiasi
+- `Servizio di destinazione`: **Personalizzato**, protocollo `TCP`, porta `9274`
+- `Azione`: **Scarta**
+
+Vince la prima regola che corrisponde, quindi il collettore viene accettato e
+ogni altro host viene scartato, qualunque sia la politica di ingresso della sua
+zona.
+
+## Proteggere l'esportatore con una password {#protecting-the-exporter-with-a-password}
+
+L'esportatore può richiedere l'autenticazione HTTP basic. Devono essere
+impostati sia il nome utente sia la password, altrimenti l'autenticazione non
+viene configurata:
+
+``` bash
+uci set telegraf.output_prometheus.basic_auth_username='prometheus'
+uci set telegraf.output_prometheus.basic_auth_password='<password>'
+uci commit telegraf
+reload_config
+```
+
+Verificare le credenziali con:
+
+``` bash
+curl -s -u prometheus:'<password>' http://127.0.0.1:9274/metrics | head
+```
+
+:::warning
+
+L'esportatore serve HTTP in chiaro e non richiede alcuna autenticazione fino a
+quando le due opzioni sopra non vengono impostate. Non esporlo al di fuori di
+una rete fidata senza una password.
+
+:::
+
+## Modificare l'indirizzo di ascolto {#changing-the-listening-address}
+
+L'opzione `listen_addr` accetta la sintassi `indirizzo:porta`; se l'indirizzo
+viene omesso, Telegraf si lega a tutti gli indirizzi IPv4 e IPv6 disponibili.
+
+Per limitare l'esportatore a un solo indirizzo:
+
+``` bash
+# raggiungibile solo dal firewall stesso, sufficiente per il reverse proxy
+uci set telegraf.output_prometheus.listen_addr='127.0.0.1:9274'
+
+# raggiungibile solo su un indirizzo LAN specifico
+uci set telegraf.output_prometheus.listen_addr='192.168.1.1:9274'
+
+uci commit telegraf
+reload_config
+```
+
+## Unità collegate a un controller {#telegraf-prometheus-controller}
+
+Quando il firewall è collegato a un controller, il controller legge già le
+metriche di Telegraf attraverso il tunnel VPN: a ogni connessione l'unità apre
+la porta `9273` sul proprio indirizzo VPN.
+
+Quell'endpoint è gestito dal sistema e non va modificato. Mantenendo il
+`listen_addr` dell'esportatore su una porta differente, come descritto in
+[Abilitare l'esportatore](#enabling-the-exporter), i due endpoint convivono
+senza interferire tra loro.
+
+## Disabilitare l'esportatore {#disabling-the-exporter}
+
+``` bash
+uci set telegraf.output_prometheus.enabled='0'
+uci commit telegraf
+reload_config
+```
+
+Il monitoraggio locale e le metriche salvate in VictoriaMetrics non vengono
+influenzati: l'esportatore è un output aggiuntivo e disabilitarlo interrompe
+solo l'endpoint Prometheus.