Gestire il nodo

Il lavoro quotidiano su un nodo è poco. È tutto qui.

Salute

sudo scripts/tc-operator/tc-operator status --config operator.yaml

Di sola lettura, e non ti chiede mai di confermare nulla, quindi puoi schedularlo. Stampa un riepilogo leggibile dello stato di ogni container, l’identità di federazione del nodo, quali flag sono attivi, quali integrazioni sono configurate, e la build attualmente in esecuzione. Scrive anche una riga JSON leggibile da macchina, così puoi puntarci un monitor.

Eseguilo come root. Tutto oltre gli stati dei container viene letto attraverso /etc/trusted-codes/secrets.env, che solo root può aprire. Senza root ottieni gli stati dei container e nient’altro, e non ti dice che il resto manca — così un monitor impostato senza privilegi riporta un nodo sano senza vedere nulla della sua identità.

I container su cui riporta, e che cosa significa che ciascuno sia giù:

Container	Che cos’è	Se è giù
`db`	il database — tutto lo stato del nodo	tutto è giù
`auth`	registrazione, accesso, emissione di token	nessun nuovo accesso; i token emessi funzionano finché non scadono
`rest`	l’API REST sopra il database	tutte le letture e scritture dei client falliscono
`functions`	tutta la logica di business e gli handler di federazione	le azioni dell’app e la federazione falliscono; auth e REST grezzi rispondono ancora
`storage`	file e blob	caricamenti e download falliscono; nient’altro
`realtime`	sollecitazioni di sincronizzazione via WebSocket	i client tornano a scansioni in primo piano — degradato, non rotto
`kong`	l’unico gateway davanti a tutto questo	l’intera API è irraggiungibile anche se i servizi sono attivi

Altri due girano a fianco: un sidecar WebFinger, che è come i peer risolvono gli utenti sul tuo nodo, e il proxy che termina il TLS e serve le superfici.

/etc/trusted-codes/README.md sulla macchina porta la stessa tabella con i nomi reali dei container del tuo nodo, più che cosa serve ogni file in quella cartella. /etc/trusted-codes/install.log ha l’output completo di ogni comando eseguito dall’installer.

Avviare e fermare le superfici

Quali superfici sono attive viene da operator.yaml, ma puoi attivarne o disattivarne una a runtime senza una reinstallazione.

tc-operator service status              # per superficie: attiva, pronta, in servizio
tc-operator service start my            # compila se necessario, poi serve
tc-operator service stop business       # rimuove il vhost; il pacchetto viene mantenuto
tc-operator service restart verify
tc-operator service start all           # ogni superficie tranne admin

Le superfici sono my, business, verify, provider, status e admin.

start prepara il pacchetto se non è stato ancora compilato, aggiunge il vhost della superficie e ricarica a caldo il proxy. Un nuovo host emette il suo certificato in circa 30-60 secondi; service status mostra cert-pending finché non risponde, poi serving.
Una superficie ha bisogno del proprio record DNS A prima che il certificato possa essere emesso.
admin non può mai essere fermata. È la superficie di ripristino.
Questo è l’unico modo per controllare il servizio delle superfici. L’app di amministrazione ti mostra il comando ma non avvia o ferma mai nulla da sola — un’applicazione web non deve poter controllare la tua macchina.

Account amministratore

L’app di amministrazione del tuo nodo è controllata per ruolo. C’è un ruolo che usi: operator_admin. Amministra questo server — utenti, sessioni, cronologia degli accessi, tentativi bloccati, organizzazioni, vault, notifiche.

Gli viene negata ogni superficie di controllo centrale: concessioni dell’operatore, diritti, piani, parametri di sistema, marketing, e le azioni privilegiate dietro di essi. Quel diniego è imposto sul server a ogni richiesta, non solo nascosto nell’interfaccia, e non c’è percorso da operator_admin al ruolo centrale super_admin.

Aggiungere e rimuovere

tc-operator add-admin --email someone@example.com
tc-operator add-admin --email someone@example.com --revoke

Nessuna conferma al terminale, idempotente, sicuro da rieseguire. Il verbo è fissato su operator_admin e non può mai concedere il ruolo centrale.

L’account deve già esistere — la persona deve aver effettuato l’accesso almeno una volta. add-admin concede soltanto; non crea account. Il percorso admin_email dell’installer è ciò che crea il primo.

Due capacità sopra il ruolo

tc-operator add-admin --email <indirizzo> --can-revoke
tc-operator add-admin --email <indirizzo> --can-reveal
tc-operator add-admin --email <indirizzo> --revoke --can-reveal   # solo quella capacità

can_revoke taglia fuori un server peer, in entrambe le direzioni. Il tuo primo amministratore la riceve all’installazione, perché un controllo di emergenza che richiede un passaggio da riga di comando a metà di un incidente non è un controllo di emergenza.

can_reveal smaschera un indirizzo nel registro degli inviti — una ragione digitata, sottoposta ad audit, con limite di frequenza — e attiva la conservazione che crea la copia recuperabile fin dall’inizio. È disattivata per impostazione predefinita e resta spenta finché non decidi altrimenti. È nuova esposizione di dati personali, quindi è una tua decisione consapevole piuttosto che un predefinito.

Un semplice --revoke toglie il ruolo e tutte le capacità. --revoke con un flag di capacità rimuove solo quella capacità.

Accesso

L’app di amministrazione rileva quali metodi ha configurato il tuo nodo e li mostra.

Password. Sempre disponibile, ed è il tuo primo modo per entrare: admin_email più la password monouso che l’installer ha stampato. Funziona su un nodo nudo senza email e senza OAuth, ed è per questo che è il percorso garantito. Cambiala dopo il primo accesso.
Link magico. Ha bisogno di SMTP. L’opzione resta nascosta finché il trasporto non è configurato.
Google o Apple. Ha bisogno delle credenziali del provider nell’ambiente del servizio di autenticazione, con l’URL di callback del tuo stesso nodo registrato presso Google o Apple. Il pulsante compare automaticamente una volta che sono impostate.

In ogni caso, il nodo ammette solo utenti che possiedono operator_admin o super_admin. Un accesso riuscito da chiunque altro viene rifiutato e disconnesso.

URL dei portali

I link di invito e i riferimenti ai portali si risolvono in URL derivati da home_server — https://my.<dominio>, https://admin.<dominio>, e così via. Per puntarli altrove, apri l’app di amministrazione e modificali sotto This Server → Portal URLs. I cambiamenti hanno effetto immediato, e rieseguire l’installazione non sovrascrive mai un URL che hai personalizzato.

Se il tuo nodo gira sotto una concessione operativa

sudo scripts/tc-operator/tc-operator renew-grant --config operator.yaml

Un tentativo di rinnovo della concessione: firma un’attestazione, la invia centralmente, verifica la concessione restituita e la salva. L’installazione collega un lavoro schedulato giornaliero per questo, quindi normalmente non lo esegui mai a mano. Esce in modo pulito e non fa nulla se il centro è irraggiungibile o non è presente alcuna concessione, e registra in /etc/trusted-codes/renew-grant.log.

Ruotare il certificato mTLS del nodo

Il tuo nodo custodisce un certificato client autofirmato, emesso una sola volta alla prima installazione, salvato sotto /etc/trusted-codes/mtls/, valido per 398 giorni. La sua impronta fa parte del tuo payload di ammissione — è l’identità stabile del tuo nodo verso il registro, ed è per questo che rieseguire l’installazione la preserva deliberatamente e non la ruota mai silenziosamente.

Ruotala solo quando si avvicina alla scadenza o pensi che la chiave sia stata esposta. Non c’è ancora un comando unico per questo:

sudo mv /etc/trusted-codes/mtls /etc/trusted-codes/mtls.old
sudo scripts/tc-operator/tc-operator install --config operator.yaml
scripts/tc-operator/tc-operator submit-admission

L’installazione conia un certificato nuovo, il che significa una nuova impronta. Il registro continua a fidarsi di quella vecchia finché qualcuno presso Trusted Codes non verifica la nuova impronta fuori banda e la approva — esattamente come alla prima installazione. Tieni mtls.old fino ad allora, così puoi tornare indietro.

Come è protetta la macchina

Ogni porta di container pubblicata si lega solo a 127.0.0.1. Questo è il controllo strutturale, e conta più di quanto sembri: Docker pubblica le porte inserendo le proprie regole firewall, che aggirano ufw. Un deny del firewall non blocca una porta di container pubblicata. Una porta legata al loopback è raggiungibile solo dalla macchina stessa a prescindere. Le regole firewall sulle porte 22, 80 e 443 sono difesa in profondità, non il meccanismo.

Raggiungi Postgres dalla tua workstation tramite un tunnel SSH:

ssh -L 5432:127.0.0.1:5432 <la-tua-macchina>

Il proxy è l’unico processo legato a una porta pubblica. Termina il TLS e inoltra al gateway sul loopback.

I segreti vivono solo in /etc/trusted-codes/secrets.env, modalità 0600. Il payload di ammissione porta solo materiale a chiave pubblica.