{
"meta": {
"title": "Integrazioni Proxmox — Homepage, Home Assistant, Grafana, Prometheus | ProxMenux Monitor",
"description": "Esempi da copiare per collegare ProxMenux Monitor a Homepage, Home Assistant, Grafana tramite Prometheus e Uptime Kuma, con configurazione richiesta, endpoint API e intestazione di autenticazione.",
"ogTitle": "Integrazioni Proxmox — Homepage, Home Assistant, Grafana, Prometheus",
"ogDescription": "Guida per collegare ProxMenux Monitor a Homepage, Home Assistant, Grafana, Prometheus e Uptime Kuma.",
"twitterTitle": "Integrazioni Proxmox | ProxMenux Monitor",
"twitterDescription": "Ricette per Homepage, Home Assistant, Grafana, Prometheus e Uptime Kuma."
},
"header": {
"title": "Integrazioni",
"description": "Esempi da copiare per gli strumenti del tuo homelab: Homepage, Home Assistant, Grafana tramite Prometheus e Uptime Kuma. Ogni esempio mostra la configurazione richiesta, l’endpoint del Monitor utilizzato e l’intestazione di autenticazione necessaria.",
"section": "Monitor di ProxMenux"
},
"intro": {
"title": "Cosa puoi costruire da questa pagina",
"body": "Copia ogni esempio nello strumento scelto. Gli endpoint sono descritti nel Riferimento API; questa pagina spiega come usarli in Homepage, Home Assistant e Grafana. Le immagini mostrano il risultato delle configurazioni."
},
"auth": {
"heading": "Autenticazione: l'unica cosa che ogni ricetta ha bisogno",
"intro": "La maggior parte degli endpoint utilizzati da queste integrazioni sono autenticati. Hai due modi per soddisfare questo requisito.",
"optAtitle": "Opzione A — Token API (consigliato per le integrazioni)",
"optAbody1": "Apri Impostazioni → Sicurezza → Token API. Premi Genera token, assegna un nome come homepage, home-assistant o prometheus e copialo: appare una sola volta. Scade dopo un anno per impostazione predefinita ed è revocabile singolarmente. Usalo per i client esterni al browser.",
"optAbody2": "Da quel punto ogni richiesta è solo:",
"optBtitle": "Opzione B — flusso di login (username + password)",
"optBbody": "Utile per script che si autenticano come un utente. Il token restituito dura poco; per la maggior parte delle integrazioni scegli l’opzione A.",
"outro": "Il campo TOTP è obbligatorio solo se sull’account è attiva la 2FA. Rotazione e revoca dei token, criteri delle password e registro di controllo sono descritti in Accesso e autenticazione.",
"httpsTitle": "Utilizzando HTTPS invece di HTTP",
"httpsIntro": "Gli esempi usano http:// per brevità. Se hai attivato TLS sul Monitor (Impostazioni → Sicurezza → SSL/HTTPS), sostituisci http:// con https:// in ogni URL. Due note per alcuni strumenti:",
"httpsItems": [
"Certificati autofirmati. L’integrazione Home Assistant rest: verifica TLS per impostazione predefinita. Per un certificato autofirmato del Monitor aggiungi verify_ssl: false a ogni blocco REST accanto a scan_interval:, oppure importa la CA del Monitor tra i certificati attendibili. Lo stesso vale per altri strumenti che verificano i certificati.",
"Prometheus include già scheme: https nell’esempio sotto. Attiva o mantieni https se TLS è attivo sul Monitor."
]
},
"homepage": {
"heading": "Homepage",
"headingHref": "https://gethomepage.dev",
"intro": "Homepage è una dashboard di applicazioni statica e personalizzabile. ProxMenux Monitor si collega con il widget integrato customapi: aggiungi un servizio a services.yaml, riavvia Homepage e la scheda mostra i valori aggiornati.",
"iconCalloutTitle": "Il logo ufficiale ProxMenux è su dashboardicons.com",
"iconCalloutBody": "Gli esempi usano icon: proxmenux.png. Homepage cerca automaticamente i nomi semplici su dashboardicons.com, una raccolta di icone per dashboard autogestite. La voce ProxMenux è su dashboardicons.com/icons/external/proxmenux e viene caricata alla prima visualizzazione. Funziona anche per migliaia di strumenti come Telegram, Discord, Grafana e Tailscale: indica icon: <name>.png nel servizio.",
"imageAlt": "Homepage cruscotto che mostra tre schede ProxMenux Monitor (EDGE, VOID, DREAM) con uptime, CPU, RAM e temperatura per ogni host Proxmox",
"imageCaption": "Tre istanze ProxMenux Monitor come schede Homepage: uptime, CPU, RAM e temperatura CPU letti da /api/system di ogni host ogni 10 s.",
"basicTitle": "widget di base — nessuna autenticazione",
"basicIntro": "Utilizzare questo quando ProxMenux Monitor è su una rete di fiducia e non hai ancora abilitato l'autenticazione sul lato Monitor. La voce services.yaml più semplice:",
"authedTitle": "widget autenticato",
"authedIntro": "Generare un token API in Impostazioni → Sicurezza → Token API sul Monitor, copiarlo e incollarlo nell'intestazione Authorization di seguito — sostituire il token di esempio mostrato dopo Bearer con quello appena copiato:",
"authedOutro": "Riavvia Homepage per visualizzare i valori aggiornati. Riutilizza lo stesso token nei widget che interrogano la stessa istanza del Monitor.",
"multiTitle": "Configurazione multi-widget — sistema, archiviazione, rete",
"multiIntro": "Per più dettagli crea tre schede con endpoint diversi: sistema, archiviazione e rete. Usa lo stesso token per questa istanza del Monitor.",
"multiCalloutTitle": "Più host Proxmox",
"multiCalloutBody": "Ripeti il blocco per ogni host per ottenere le schede mostrate. Ogni voce usa http://<host>:8008 della propria istanza. Genera e conserva un token per host: le installazioni separate hanno chiavi di firma proprie, quindi non presumere che un token valga anche altrove."
},
"homeAssistant": {
"heading": "Home Assistant",
"headingHref": "https://www.home-assistant.io",
"intro": "Gli esempi usano l’integrazione rest di Home Assistant senza richiedere un componente HACS dedicato. Legge gli endpoint nel Riferimento API e crea sensori e attributi per le automazioni. La configurazione offre circa 25 sensori per risorse, stato, VM/CT, archiviazione, rete e aggiornamenti. Aggiungila a configuration.yaml e ricarica o riavvia HA.",
"imageAlt": "Dashboard Home Assistant con stato, indicatori CPU/RAM/temperatura, numero di VM, spazio occupato ed errori attivi",
"imageCaption": "ProxMenux Monitor come integrazione Home Assistant di prima classe — sensori costruiti dalla ricetta YAML qui sotto.",
"step1Title": "1 · Conservare il token API",
"step1Body": "Salva il token in secrets.yaml per separarlo dalla configurazione principale. Includi prefisso Bearer e token in un unico valore da usare come intestazione. Il file non è cifrato e deve restare privato. La posizione dipende dall’installazione, in genere /config/secrets.yaml su HA OS o Container.",
"step2Title": "2 · Aggiungere la configurazione REST",
"step2Body": "Sei blocchi REST coprono le aree principali. Il loro scan_interval segue la frequenza delle modifiche: risorse ogni 30 s, stato ogni 60 s, inventari ogni 5–10 minuti. Incolla in configuration.yaml:",
"step3Title": "3 · Aggiungi sensori binari e helper per modelli",
"step3Body": "Due sensori binari e due sensori basati su modello completano l’integrazione, semplificando automazioni e schede condizionali Lovelace senza ripetere espressioni Jinja ovunque.",
"step4Title": "4 · Ricarica e verifica",
"step4Body": "Verifica prima la sintassi in Strumenti per sviluppatori → YAML → Controlla configurazione. Ricarica poi Tutta la configurazione YAML o riavvia HA. In Impostazioni → Dispositivi e servizi → Entità filtra per proxmenux. Le circa 25 entità dovrebbero ricevere valori entro un intervallo di lettura.",
"replaceTitle": "Sostituzione di una versione precedente di questa ricetta?",
"replaceBody": "Dopo una versione precedente, il registro può conservare ID obsoleti e le schede mostrare Entità non trovata. Rimuovi i vecchi blocchi rest: e template: da configuration.yaml e ricarica. In Impostazioni → Dispositivi e servizi → Entità filtra per proxmenux ed elimina le vecchie voci ripristinate o non disponibili. Aggiungi il nuovo YAML e ricarica per registrare le nuove.",
"step5Title": "5 · Dashboard Lovelace",
"step5Body": "Il YAML crea una scheda vertical-stack con logo, indicatori, sistema, VM, archiviazione, rete e problemi condizionali. Apri la dashboard, premi la matita, Aggiungi scheda, poi Manuale in fondo e incolla:",
"viewTipTitle": "Lo vuoi come una vista completa del cruscotto invece di una singola carta?",
"viewTipBody": "Apri il menu a tre punti → Editor di configurazione grezza e aggiungi una vista con questa intestazione sopra l’elenco cards::",
"viewTipOutro": "Questo ti dà una scheda/vista dedicata nel tuo cruscotto con la sua icona e titolo, invece di una lunga scheda su una vista esistente.",
"altViewTitle": "Alternativa — una vista dedicata del cruscotto",
"altViewIntro": "Per creare una scheda in una dashboard esistente, aggiungi una vista con il YAML sotto. Una vista è una scheda della dashboard e non crea una voce nella barra laterale. Passaggi:",
"altViewSteps": [
"Apri il cruscotto dove vuoi la nuova scheda.",
"Premi la matita (modifica dashboard) in alto a destra.",
"Fare clic sulla scheda + alla fine delle schede esistenti per creare una nuova vista.",
"Nella finestra scegli Editor di codice in alto a destra per passare dall’editor visivo a YAML.",
"Incolla la YAML qui sotto.",
"Salva. La vista ProxMenux Monitor appare come scheda nella dashboard con le sue carte."
],
"twoEditorsTitle": "Due editor YAML in HA — scegli quello giusto",
"twoEditorsIntro": "Home Assistant ha due editor YAML simili nell’aspetto ma con formati di input diversi:",
"twoEditorsItems": [
"Editor della singola vista — da + o Modifica vista → Editor di codice. Richiede una vista con title:, path: e cards: al livello principale, senza trattino iniziale.",
"Editor grezzo dell’intera dashboard — dal menu a tre punti. Richiede l’intero elenco views:, con ogni vista come elemento preceduto da -."
],
"twoEditorsOutro": "Il formato sbagliato può produrre una Vista senza nome e cards: []. Il YAML sotto è per l’editor di una singola vista: copialo esattamente.",
"viewImageAlt": "Vista Home Assistant per ProxMenux Monitor: intestazione picture-entity, indicatori glance e schede sistema, VM, archiviazione e rete su più colonne",
"viewImageCaption": "La vista ProxMenux Monitor su schermo ampio. Il layout Masonry distribuisce le schede in colonne; il risultato dipende dal tipo di vista configurato.",
"twoColTipTitle": "Vuoi un layout fisso a due colonne invece del layout auto?",
"twoColTipBody": "Raggruppa due schede, come Sistema + VM o Archiviazione + Rete, in un horizontal-stack per mostrarle affiancate a qualsiasi larghezza:",
"twoColTipOutro": "Sul telefono la riga resta compressa. Il layout automatico HA senza horizontal-stack si adatta meglio agli schermi stretti.",
"step6Title": "6 · Automazioni",
"step6Body": "Tre automazioni per gli scenari reattivi più comuni: sostituisci notify.mobile_app_<your_phone> con il servizio di notifica che usi.",
"logoTitle": "Informazioni sul logo ProxMenux",
"logoBody": "La scheda picture-entity carica il logo ufficiale da dashboardicons.com, una raccolta gratuita per dashboard autogestite. La voce è su dashboardicons.com/icons/external/proxmenux. Home Assistant scarica lo SVG via HTTPS alla prima visualizzazione e lo memorizza nella cache.",
"logoBrokenTitle": "Se la scheda logo mostra un'immagine rotta",
"logoBrokenIntro": "Alcune installazioni, reti filtrate o blocchi dei contenuti impediscono l’accesso a jsdelivr.net durante la visualizzazione. Usa una copia locale:",
"logoBrokenSteps": [
"Scarica la SVG da cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/proxmenux.svg.",
"Salvalo in /config/www/icons/proxmenux.svg sull’host HA.",
"Nel Lovelace YAML, sostituire l'URL image: con /local/icons/proxmenux.svg. Salvare e ricaricare — l'immagine rende dal file locale, nessun Internet necessario."
],
"scanTipTitle": "Regola pratica per scan_interval",
"scanTipBody": "Inizia leggendo /api/system ogni 30 s. /api/health/full usa normalmente un risultato valido fino a sei minuti; leggerlo ogni 60 s non aggira la cache. Prova cinque minuti per /api/storage/summary e un’ora per /api/proxmenux/update-status. Adatta gli intervalli all’hardware e al numero di host."
},
"grafana": {
"heading": "Prometheus + Grafana",
"promHref": "https://prometheus.io",
"grafanaHref": "https://grafana.com",
"intro": "ProxMenux Monitor espone GET /api/prometheus nel formato testuale Prometheus 0.0.4. Con autenticazione attiva serve un token Bearer. Configura Prometheus per raccogliere le metriche e Grafana per visualizzare il database di serie temporali.",
"imageAlt": "Dashboard Grafana con metriche ProxMenux: indicatore CPU, andamento memoria, numero di VM in esecuzione e traffico di rete",
"imageCaption": "Una dashboard Grafana con i dati ProxMenux raccolti da Prometheus: CPU, memoria, VM in esecuzione e traffico di rete. Il catalogo completo è in Riferimento API → Metriche Prometheus.",
"step1Title": "1 · Aggiungi il job di raccolta a Prometheus",
"step1Body": "Passa il token API tramite il blocco nativo authorization di Prometheus, che consente anche credenziali da file.",
"step1After": "Ricarica Prometheus con kill -HUP <PID> (sostituisci PID con il suo ID processo), systemctl reload prometheus se supportato o docker compose restart prometheus per il container. In Status → Targets, proxmenux dovrebbe diventare UP entro un intervallo. L’etichetta node=\"<hostname>\" distingue gli host.",
"tokenTipTitle": "Conserva il token in un file separato",
"tokenTipBody": "In produzione separa il token dalla configurazione. Con credentials_file: /etc/prometheus/secrets/proxmenux.token, Prometheus lo legge da un file con permessi 0600.",
"step2Title": "2 · Verifica la raccolta con alcune query",
"step2Body": "Prima di Grafana verifica che Prometheus abbia i dati. Apri http://<prometheus-host>:9090, scegli Query ed esegui una di queste query. Dovresti ottenere valori aggiornati dell’host Proxmox:",
"headerQuery": "Query",
"headerConfirms": "Cosa conferma",
"verifyRows": [
{
"query": "up{job=\"proxmenux\"}",
"confirms": "Restituisce 1 se Prometheus raccoglie correttamente i dati del Monitor, altrimenti 0. Il controllo iniziale più rapido."
},
{
"query": "proxmox_cpu_usage",
"confirms": "Uso attuale della CPU dell’host Proxmox in percentuale. Il valore dovrebbe cambiare ripetendo la query dopo alcuni secondi."
},
{
"query": "proxmox_vms_running",
"confirms": "Numero di ospiti in esecuzione. Confronta con quello che vedi nell'UI Proxmox."
},
{
"query": "proxmox_uptime_seconds / 86400",
"confirms": "Host uptime in giorni. Dovrebbe corrispondere al valore che si vede in uptime sulla shell Proxmox."
}
],
"calloutTitle": "Un 401 aprendo direttamente l’URL dell’endpoint può essere normale",
"calloutBody": "Con autenticazione attiva, il collegamento in Status → Targets apre /api/prometheus nel browser senza l’intestazione Bearer di Prometheus. La risposta può contenere '{'\"error\":\"Authentication required\"'}'. Controlla il vero State: UP del target per confermare la raccolta di Prometheus.",
"step3Title": "3 · Aggiungi Prometheus come sorgente dati Grafana",
"step3Body": "In Grafana apri Connections → Data sources → Add new → Prometheus. Imposta l’URL, ad esempio http://prometheus.lan:9090, salva e prova. Se Prometheus richiede autenticazione, configurala qui separatamente. Il token del Monitor appartiene al job di raccolta Prometheus.",
"step4Title": "4 · Costruire pannelli con queste query PromQL",
"step4Body": "Una selezione iniziale delle metriche tipiche di un host Proxmox:",
"headerPanel": "Idea del pannello",
"headerPromql": "Query PromQL",
"panelRows": [
{
"panel": "Misuratore di utilizzo CPU per host",
"promql": "proxmox_cpu_usage"
},
{
"panel": "Misuratore di utilizzo della memoria per host",
"promql": "proxmox_memory_usage_percent"
},
{
"panel": "Memoria utilizzata vs totale (serie temporali)",
"promql": "proxmox_memory_used_bytes / 1024 / 1024 / 1024"
},
{
"panel": "VM/CT in esecuzione per host",
"promql": "proxmox_vms_running"
},
{
"panel": "Temperatura CPU",
"promql": "proxmox_cpu_temperature_celsius"
},
{
"panel": "Traffico di rete RX (byte/s)",
"promql": "rate(proxmox_interface_bytes_received_total[5m])"
},
{
"panel": "Traffico di rete TX (byte/s)",
"promql": "rate(proxmox_interface_bytes_sent_total[5m])"
},
{
"panel": "Media del carico (1m)",
"promql": "proxmox_load_average{period=\"1m\"}"
},
{
"panel": "Percentuale di spazio usato per punto di montaggio",
"promql": "proxmox_disk_usage_percent"
},
{
"panel": "Livello di carica della batteria UPS",
"promql": "proxmox_ups_battery_charge_percent"
},
{
"panel": "Temperatura GPU per slot",
"promql": "proxmox_gpu_temperature_celsius"
}
],
"outro": "Aggiungi ogni query come pannello Grafana, con Stat per i valori e Time series per le tendenze, e raggruppa per categoria. Usa node come variabile della dashboard (Settings → Variables → New → Query → label_values(proxmox_cpu_usage, node)) per filtrare per host."
},
"uptimeKuma": {
"heading": "Uptime Kuma e altri controlli di stato",
"href": "https://github.com/louislam/uptime-kuma",
"intro": "Per un controllo per parola chiave usa GET /api/system-info. La route non richiede token e restituisce nome host, uptime e stato come healthy, warning o critical. È pubblica, a differenza degli endpoint di stato dettagliati protetti.",
"kumaTitle": "Uptime Kuma — Monitor di parole chiave HTTP",
"kumaSteps": [
"In Uptime Kuma, fare clic su + Aggiungi nuovo monitor.",
"Tipo di monitor: HTTP(s) - Parola chiave.",
"Nome descrittivo: ProxMenux Monitor — pve01.",
"URL: http://pve01.lan:8008/api/system-info.",
"Parola chiave: healthy (il valore di health.status quando l'host è OK).",
"Intervallo di controllo: 60 secondi sono sufficienti.",
"Salva. La route system-info non richiede un’intestazione Bearer."
],
"healthchecksTitle": "healthchecks.io / ping da attività cron",
"healthchecksBody": "Un’attività cron può leggere /api/system-info e verificare .health.status == \"healthy\". Solo dopo il successo invia un ping alla propria URL Healthchecks.io. Il servizio riceve ping dalle attività e non interroga il Monitor. Un HTTP 2xx da solo non dimostra che l’host sia sano.",
"richTitle": "Vuoi dati più dettagliati sullo stato?",
"richBody": "Per lo stato completo — dieci categorie, errori attivi e silenziati — usa GET /api/health/full. Restituisce in una risposta i dati della finestra della dashboard e richiede un token Bearer con autenticazione attiva."
},
"workflows": {
"heading": "n8n, Zapier e script personalizzati",
"intro": "Workflow e script possono inviare notifiche con POST a /api/notifications/send, per esempio dopo un errore CI o un’attività troppo lunga. L’invio diretto salta coda e intervallo tra impronte degli eventi. Mantiene formato per canale, IA facoltativa e consegna. Gestisci gli eventuali duplicati nel chiamante.",
"n8nBody": "In n8n usa un nodo HTTP Request con POST, URL sopra e lo stesso JSON di curl. Scegli credenziali generiche Header Auth: nome Authorization e valore Bearer YOUR_API_TOKEN, sostituendo il segnaposto. Collega una pianificazione, webhook o altro nodo per avviare la richiesta.",
"severityBody": "La gravità usa INFO, WARNING o CRITICAL in maiuscolo. L’oggetto data fornisce il contesto dell’evento e i campi del modello. Su questo endpoint la riscrittura IA riceve solo titolo e messaggio; i campi in data non vengono inviati al provider. Vedi Notifiche → Catalogo eventi per il significato degli eventi."
},
"pveWebhook": {
"heading": "Webhook nativo Proxmox VE (in ingresso)",
"intro1": "Il sistema di notifiche risale a PVE 8.1; i target webhook nativi richiedono Proxmox VE 8.3 o successivo. Abilita notifiche nelle impostazioni tenta di registrare il Monitor come destinazione. Gli avvisi PVE instradati lì, come rapporti di backup o replica, entrano nel suo flusso di invio. La configurazione deve essere disponibile e scrivibile.",
"intro2": "Funzionamento, modello inviato da PVE, voci in /etc/pve/notifications.cfg e comportamento in cluster sono in Notifiche → Integrazione webhook PVE."
},
"whereNext": {
"heading": "Come proseguire",
"items": [
{
"label": "Riferimento API",
"href": "/docs/monitor/api",
"tail": " — endpoint con metodo, percorso e catalogo completo delle metriche Prometheus."
},
{
"label": "Notifiche",
"href": "/docs/monitor/notifications",
"tail": " — fonti di eventi, canali, flusso di invio e integrazione webhook PVE."
},
{
"label": "Assistente AI",
"href": "/docs/monitor/ai-assistant",
"tail": " — riscrittura facoltativa dei modelli in linguaggio semplice prima dell’invio a Telegram, Discord, e-mail o Gotify."
},
{
"label": "Accesso e autenticazione",
"href": "/docs/monitor/access-auth",
"tail": " — creazione e revoca dei token API degli esempi, registro di controllo e configurazione TLS."
}
]
}
}