API Tunnel

AutenticazioneCopia il link alla sezione

Gli endpoint di gestione usano la sessione autenticata della dashboard. Le richieste che modificano la configurazione richiedono l’header Origin esatto della dashboard. Puoi gestire solo i connettori e i siti dell’account selezionato.

Sostituisci ACCOUNT-ID, SITE-ID e TUNNEL-ID nei percorsi seguenti. Leggi la revisione corrente della configurazione prima di modificarla. La prima configurazione usa una revisione vuota; una revisione superata restituisce HTTP 409.

Endpoint dei connettori dell’accountCopia il link alla sezione

Usa GET o PUT /customer/api/account-tunnels/ACCOUNT-ID?account=ACCOUNT-ID.

GET restituisce config, i reports delle connessioni, control_url, account_id, websites, publications ed eventuali notice di migrazione. Include anche service_reports e le service_revisions desiderate, indicizzate per ID del connettore. I segreti sono oscurati; token_configured indica se il connettore dispone di una credenziale.

PUT accetta l’elenco dei connettori e la revisione corrente:

{
  "revision": "CURRENT-REVISION",
  "connectors": [{
    "id": "customer-server",
    "name": "Customer server",
    "enabled": true,
    "auto_update_disabled": false
  }],
  "routes": []
}

Imposta auto_update_disabled a true per disabilitare gli aggiornamenti automatici. Questo non modifica il token.

Rimuovere un connettore usato da un sito restituisce HTTP 400. Disabilitalo per interrompere i servizi mantenendo le route configurate.

Endpoint delle route del sitoCopia il link alla sezione

Usa GET o PUT /customer/api/tunnels/SITE-ID?account=ACCOUNT-ID.

GET include i connettori dell’account per la selezione delle route. PUT accetta revision, un array connectors vuoto e le routes del sito. Ogni route specifica id, tunnel_id, service, path, match ed enabled.

Le route possono usare solo connettori dell’account del sito. Le modifiche generali al sito conservano queste route. Per un intero sito, imposta l’origine su tunnel://CONNECTOR-ID/SERVICE tramite l’endpoint di configurazione del sito.

Endpoint dei tokenCopia il link alla sezione

Invia POST /customer/api/account-tunnels/ACCOUNT-ID/TUNNEL-ID/token?account=ACCOUNT-ID con:

{"revision":"CURRENT-REVISION"}

La risposta contiene un nuovo token e la config aggiornata con i segreti oscurati. Conserva il token in modo sicuro: viene restituito una sola volta. La sostituzione impedisce subito al vecchio token di recuperare la configurazione e disconnette poco dopo le repliche esistenti.

Codici di attivazioneCopia il link alla sezione

Invia POST /customer/api/account-tunnels/ACCOUNT-ID/TUNNEL-ID/activation?account=ACCOUNT-ID con la revision corrente.

La risposta contiene code, expires e la config aggiornata. Un codice scade dopo dieci minuti ed è utilizzabile una sola volta. Crearlo non modifica il token in uso; generarne un altro invalida il codice precedente non ancora utilizzato.

Il connettore riscatta il codice su POST /api/agent/connectors/activate con account_id, tunnel_id e code. Questo endpoint autentica tramite il codice anziché con i cookie della dashboard.

Il riscatto riuscito sostituisce il token permanente e restituisce account_id, tunnel_id e token. Codici non validi, scaduti o già usati restituiscono HTTP 401. Errori temporanei di salvataggio restituiscono HTTP 503.

La sostituzione o revoca del token annulla anche un codice di attivazione ancora valido. Le risposte con credenziali usano Cache-Control: no-store.

Rilevamento della configurazioneCopia il link alla sezione

I connettori recuperano la configurazione da GET /api/agent/connectors/config con:

Authorization: Bearer TUNNEL-TOKEN
X-Loclix-Account: ACCOUNT-ID
X-Loclix-Tunnel: TUNNEL-ID
X-Loclix-Connector-Protocol: 3

La risposta include account_id, tunnel_id, endpoints e auto_update_disabled. Ogni endpoint attuale fornisce address, server_name, account_scoped: true e un insieme di certificati PEM trust per la verifica del certificato.

L’indirizzo condiviso è waf-ingress.loclix.network:443. Può essere restituito prima della pubblicazione di un sito. Credenziali non valide restituiscono HTTP 401; un elenco di endpoint vuoto indica che al momento non è disponibile alcun endpoint di connessione.

DownloadCopia il link alla sezione

Usa il comando di installazione fornito da Install connector. I download sono disponibili sull’host della dashboard sotto /downloads/connectors/.

Il programma di installazione supporta Linux amd64 e arm64 con systemd 247 o successivo. Le directory linux-amd64 e linux-arm64 contengono loclix-connector, il checksum .sha256, i metadati firmati release.json e THIRD-PARTY-NOTICES.txt.

Conserva gli avvisi di licenza quando ridistribuisci un binario del connettore. Consulta Aggiornamenti del connettore per i controlli sugli aggiornamenti.

Definizioni dei servizi gestitiCopia il link alla sezione

In un connettore dell’account, imposta services_managed: true e fornisci una mappa services completa:

{
  "id": "customer-server",
  "name": "Customer server",
  "enabled": true,
  "services_managed": true,
  "services": {
    "web": "http://127.0.0.1:8080",
    "api": "http://127.0.0.1:3000"
  }
}

Includi questo oggetto nell’array connectors della configurazione dell’account, insieme alla revisione corrente. La mappa sostituisce le definizioni dei servizi per ogni replica. Il salvataggio può interrompere le connessioni attive mentre il connettore applica la modifica.

Le mappe supportano fino a 64 servizi e 32 KiB di definizioni. Rimuovere un servizio ancora usato da un sito restituisce HTTP 400. Una mappa vuota è consentita se nessuna pubblicazione usa i suoi servizi.

Usa service_reports per esaminare le destinazioni applicate. Un indirizzo desiderato non è attivo finché il connettore non lo comunica. I dati scadono dopo 60 secondi e i connettori meno recenti non possono applicare mappe gestite dalla dashboard. Consulta Servizi locali per i requisiti di versione e le modifiche in attesa.