Cosa fa questo modulo #
Quasi ogni servizio della tua istanza ha bisogno di un segreto: la password del database, la passphrase di uno strumento di integrità, una chiave di API… Conservarli a mano —o peggio, lasciarli con i valori predefiniti— è uno dei modi più comuni perché una macchina finisca compromessa.
Il modulo secrets si occupa di questo ciclo di vita in locale: genera ogni segreto con un generatore crittograficamente sicuro (CSPRNG), lo salva con permessi 0600 (solo root può leggerlo), lo restituisce con un output pulito pronto per essere concatenato in una pipe, e lo ruota quando ti serve. Tutto è organizzato per domini (per esempio mariadb o tripwire), e ogni dominio può avere diversi campi.
generate è idempotente: se il segreto di un dominio esiste già, non lo tocca. Così una stessa immagine può creare i suoi segreti al primo avvio di ogni istanza senza che due macchine condividano la stessa password. I valori non vengono mai registrati né mostrati in list.
Operazioni comuni #
Scegli cosa vuoi fare. Ogni ricetta porta il comando già scritto — cambia solo il dominio con il tuo e premi Copia.
1
Generare il segreto di un servizio
Crea una password forte per un dominio, solo se ancora non esiste.
Connettiti via SSH al tuo server con l'utente ubuntu.
Genera il segreto del dominio mariadb. Essendo idempotente, puoi lanciarlo tutte le volte che vuoi senza timore di sovrascrivere:
$ sudo imaxe secrets generate mariadbTi serve una passphrase lunga per un altro strumento e in un campo specifico? Regola --format, --len e --field:
$ sudo imaxe secrets generate tripwire --field local.passphrase --format passphrase --len 400600. Se esisteva già, non è stato cambiato — il comando termina comunque con successo.2
Leggere un segreto per usarlo
Ottieni il valore grezzo, pronto per essere concatenato in un altro comando.
get stampa unicamente il valore, senza fronzoli né interruzioni extra, così puoi passarlo a un altro processo tramite pipe:
$ sudo imaxe secrets get mariadbIl segreto è in un campo specifico del dominio? Indicalo con --field:
$ sudo imaxe secrets get tripwire --field local.passphrasePASS="$(sudo imaxe secrets get mariadb)" e usarlo direttamente nel tuo script.3
Ruotare un segreto
Sostituisci il valore con uno nuovo e segna il dominio come ruotato.
Genera un valore nuovo per il dominio. A differenza di generate, rotate sì sostituisce il segreto esistente:
$ sudo imaxe secrets rotate mariadblist). Ricordati di aggiornare il servizio che usa quel segreto con il nuovo valore di get.4
Vedere quali domini esistono
Consulta i metadati senza esporre alcun valore.
Elenca i domini con i loro metadati (quando sono stati creati e quando sono stati ruotati). Non mostra mai il segreto in sé:
$ sudo imaxe secrets listTi serve per uno script o un controllo automatico? Richiedi l'output in JSON:
$ sudo imaxe secrets list --jsonIl segreto è leggibile solo da root mentre vive su disco. Non appena lo leggi con get passa al tuo terminale e alla tua shell: evita di lasciarlo nella cronologia (history), in variabili d'ambiente esportate di troppo o nei log. Preferisci sostituzioni di comando puntuali come "$(sudo imaxe secrets get mariadb)".
Sinossi #
imaxe secrets <subcomando> [<dominio>] [--field CLAVE] [flags]Tutti i sottocomandi richiedono privilegi di root (usa sudo) perché leggono e scrivono file 0600 sotto /etc/imaxe/. Aggiungi --json a list per ottenere output leggibile dalla macchina, adatto allo scripting. Ricorda: get emette il valore grezzo, senza decorazioni, pronto per la pipe.
Sottocomandi #
| Sottocomando | Cosa fa | Flag rilevanti |
|---|---|---|
| generate | Crea il segreto di un dominio se non esiste (idempotente, CSPRNG). Senza dominio, genera quelli di generate_on_first_boot. | --len, --format, --field |
| get | Restituisce il valore di un segreto con output pulito, adatto alla pipe. | --field |
| rotate | Genera un segreto nuovo e segna il dominio come ruotato. | --field |
| list | Elenca i domini e i metadati (creato, ruotato). Non mostra mai i valori. | --json |
Argomenti e flag #
| Flag | Tipo | Predefinito | Descrizione |
|---|---|---|---|
| <dominio> | string | — | Dominio del segreto (ad es. mariadb, tripwire). Obbligatorio in get e rotate. In generate, vuoto = i domini di generate_on_first_boot. |
| --field | string | value | Campo all'interno del dominio. Permette di salvare più segreti per dominio (ad es. local.passphrase). |
| --len | int | 32 | In generate: lunghezza del segreto in caratteri. |
| --format | enum | password | In generate: formato del valore — password, passphrase o hex. |
| --json | bool | false | In list, emette i metadati come JSON strutturato in stdout. |
File e percorsi #
| Percorso | Contenuto |
|---|---|
| /etc/imaxe/secrets.yml | Configurazione del modulo: valori predefiniti (length, format), domini ed elenco di generate_on_first_boot. Viene salvato con permessi 0600. |
Esempio di secrets.yml:
defaults:
length: 32
format: password
domains: {}
generate_on_first_boot:
- mariadb
- tripwireCon quella configurazione, un sudo imaxe secrets generate senza dominio al primo avvio crea i segreti di mariadb e tripwire con la lunghezza e il formato predefiniti.
Codici di uscita e log #
Ogni esecuzione restituisce un codice che puoi verificare con echo $? — utile per concatenare negli script:
get senza dominio).Uso tipico in uno script, sfruttando l'output pulito di get:
$ sudo imaxe secrets generate mariadb \
&& sudo imaxe secrets get mariadb | some-tool --stdin-password \
|| echo "falló con código $?"Risoluzione dei problemi #
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Esce NOTFOUND (codice 3) | Il dominio o il --field non è ancora stato generato. | Crealo prima con secrets generate <dominio> (e lo stesso --field). |
| Esce USAGE (codice 2) | get o rotate lanciati senza indicare il dominio. | Passa il dominio come argomento; è obbligatorio in quei sottocomandi. |
generate non cambia il valore | Il segreto esisteva già: generate è idempotente per design. | Se vuoi un valore nuovo, usa secrets rotate <dominio>. |
Permission denied in lettura | Il file è 0600 e lo hai lanciato senza privilegi. | Esegui il comando con sudo; solo root accede al segreto. |
Bloccato con il modulo Segreti?
Scrivici allegando l'output di «imaxe <module> status --json» e ti rispondiamo in fretta.