Documentazione Tecnica
Opra.eu espone un'API HTTP semplice per aggiornare dinamicamente i record DNS del tuo hostname. L'obiettivo è uno: darti un nome stabile anche quando l'IP pubblico cambia.
In questa pagina trovi: come creare l'account, come gestire le chiavi API, i dettagli del protocollo di update e alcune guide pratiche per i dispositivi più comuni.
Quick start
- Crea un account e genera una API key.
- Scegli un hostname (es. mio-host.opra.eu).
- Configura un client (script o router) che chiami l'endpoint di update.
- Verifica la risoluzione DNS e, se necessario, aggiusta la frequenza di aggiornamento.
Creazione account
L'account serve per gestire i tuoi hostname e le credenziali di update. In un servizio DDNS la sicurezza è fondamentale: una chiave esposta potrebbe permettere a terzi di cambiare l'IP associato al tuo nome.
Passi consigliati
- Usa una password lunga e unica (password manager).
- Associa un'email che controlli regolarmente.
- Se possibile, separa ambienti "casa" e "lavoro" con hostname distinti.
Buone pratiche
Evita di condividere le credenziali del tuo account. Per dispositivi e script, usa sempre una API key dedicata: è più semplice da ruotare e riduce l'impatto in caso di leak.
Gestione Chiavi API
Le API key sono usate dal client per autenticare le richieste di aggiornamento. Il consiglio è mantenere una chiave per "unità operativa": un host, un router, uno script, o un ambiente (staging vs produzione).
Rotazione e sicurezza
- Non committare mai la key su repository o backup non cifrati.
- Preferisci variabili d'ambiente o secret manager.
- Se sospetti una compromissione, rigenera la key e aggiorna il client.
- Usa chiavi distinte per ridurre l'impatto (principio del minimo privilegio).
HTTP GET Update
Il metodo più comune è una richiesta HTTP GET. In un setup reale, lo script viene eseguito dal tuo server o router e aggiorna l'hostname ogni volta che cambia l'IP (o a intervallo).
L'hostname da aggiornare (senza il suffisso).
La chiave API associata al tuo account.
Modalità automatica: il server usa l'IP della richiesta.
Aggiornamento via cURL
Il modo più semplice per aggiornare il tuo IP da qualsiasi script shell.
curl -X GET "https://api.opra.eu/update?domain=mio-host&key=YOUR_API_KEY&ip=auto"IPv4 (Record A)
Il record A punta un hostname a un indirizzo IPv4. È il caso più comune quando si accede a casa/ufficio da reti tradizionali. Se il tuo ISP cambia l'IPv4, basta un update per ripristinare la raggiungibilità.
IPv6 (Record AAAA)
Il record AAAA punta un hostname a un indirizzo IPv6. In molti scenari IPv6 permette percorsi più diretti e meno dipendenti dal NAT. Se la tua connessione è dual stack, aggiornare sia A che AAAA rende l'hostname "future-proof".
Guida: Raspberry Pi
Su Raspberry Pi puoi creare un cronjob che chiama l'endpoint di update a intervallo. È leggero, non richiede dipendenze e funziona bene anche per piccoli homelab.
Guida: Synology NAS
Su NAS è comune eseguire uno script pianificato (Task Scheduler) che aggiorna l'hostname. Il consiglio è usare una API key dedicata e conservare la configurazione in modo sicuro.
- Crea un'attività pianificata che esegua un comando curl.
- Imposta un intervallo coerente (es. 5 minuti) o trigger su evento di rete.
- Verifica la risoluzione con nslookup o dig.
Guida: MikroTik Router
In alcuni setup conviene far gestire il DDNS direttamente al router, così l'update avviene "alla fonte" e copre tutti i dispositivi della rete. L'implementazione dipende dal modello e dalla tua policy di sicurezza.
Approccio consigliato: crea uno script RouterOS che effettua una richiesta HTTP periodica (o su cambio WAN) verso l'endpoint di update.
Suggerimento: usa una key dedicata al router e limita la frequenza per evitare chiamate inutili.
Guida: Ubiquiti EdgeRouter
Anche su EdgeRouter puoi automatizzare l'update via script e scheduler. L'idea è identica: chiamare un endpoint HTTP con domain, key e ip=auto.