{ "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." } ] } }