Qué hace este módulo #
Casi cualquier servicio de tu instancia necesita un secreto: la contraseña de la base de datos, la passphrase de una herramienta de integridad, una clave de API… Guardarlos a mano —o peor, dejarlos por defecto— es una de las formas más comunes de que una máquina acabe comprometida.
El módulo secrets se encarga de ese ciclo de vida en local: genera cada secreto con un generador criptográficamente seguro (CSPRNG), lo guarda con permisos 0600 (solo root puede leerlo), lo devuelve con una salida limpia lista para encadenar en un pipe, y lo rota cuando lo necesitas. Todo se organiza por dominios (por ejemplo mariadb o tripwire), y cada dominio puede tener varios campos.
generate es idempotente: si el secreto de un dominio ya existe, no lo toca. Así, una misma imagen puede crear sus secretos en el primer arranque de cada instancia sin que dos máquinas compartan la misma contraseña. Los valores nunca se registran ni se muestran en list.
Tareas comunes #
Elige lo que quieres hacer. Cada receta trae el comando ya escrito — solo cambia el dominio por el tuyo y pulsa Copiar.
1
Generar el secreto de un servicio
Crea una contraseña fuerte para un dominio, solo si aún no existe.
Conéctate por SSH a tu servidor con el usuario ubuntu.
Genera el secreto del dominio mariadb. Al ser idempotente, puedes lanzarlo las veces que quieras sin miedo a sobrescribir:
$ sudo imaxe secrets generate mariadb¿Necesitas una passphrase larga para otra herramienta y en un campo concreto? Ajusta --format, --len y --field:
$ sudo imaxe secrets generate tripwire --field local.passphrase --format passphrase --len 400600. Si ya existía, no se ha cambiado — el comando termina igualmente en éxito.2
Leer un secreto para usarlo
Obtén el valor en crudo, listo para encadenar en otro comando.
get imprime únicamente el valor, sin adornos ni saltos extra, para que puedas pasarlo a otro proceso por pipe:
$ sudo imaxe secrets get mariadb¿El secreto está en un campo concreto del dominio? Indícalo con --field:
$ sudo imaxe secrets get tripwire --field local.passphrasePASS="$(sudo imaxe secrets get mariadb)" y usarlo directamente en tu script.3
Rotar un secreto
Sustituye el valor por uno nuevo y marca el dominio como rotado.
Genera un valor nuevo para el dominio. A diferencia de generate, rotate sí reemplaza el secreto existente:
$ sudo imaxe secrets rotate mariadblist). Recuerda actualizar el servicio que usa ese secreto con el nuevo valor de get.4
Ver qué dominios existen
Consulta los metadatos sin exponer ningún valor.
Lista los dominios con sus metadatos (cuándo se crearon y cuándo se rotaron). Nunca muestra el secreto en sí:
$ sudo imaxe secrets list¿Lo necesitas para un script o una comprobación automática? Pide la salida en JSON:
$ sudo imaxe secrets list --jsonEl secreto solo es legible por root mientras vive en disco. En cuanto lo lees con get pasa a tu terminal y a tu shell: evita dejarlo en el historial (history), en variables de entorno exportadas de más o en logs. Prefiere sustituciones de comando puntuales como "$(sudo imaxe secrets get mariadb)".
Sinopsis #
imaxe secrets <subcomando> [<dominio>] [--field CLAVE] [flags]Todos los subcomandos requieren privilegios de root (usa sudo) porque leen y escriben ficheros 0600 bajo /etc/imaxe/. Añade --json a list para obtener salida legible por máquina, apta para scripting. Recuerda: get emite el valor en crudo, sin decoración, listo para pipe.
Subcomandos #
| Subcomando | Qué hace | Flags relevantes |
|---|---|---|
| generate | Crea el secreto de un dominio si no existe (idempotente, CSPRNG). Sin dominio, genera los de generate_on_first_boot. | --len, --format, --field |
| get | Devuelve el valor de un secreto con salida limpia, apta para pipe. | --field |
| rotate | Genera un secreto nuevo y marca el dominio como rotado. | --field |
| list | Lista los dominios y metadatos (creado, rotado). Nunca muestra valores. | --json |
Argumentos y flags #
| Flag | Tipo | Por defecto | Descripción |
|---|---|---|---|
| <dominio> | string | — | Dominio del secreto (p. ej. mariadb, tripwire). Obligatorio en get y rotate. En generate, vacío = los dominios de generate_on_first_boot. |
| --field | string | value | Campo dentro del dominio. Permite guardar varios secretos por dominio (p. ej. local.passphrase). |
| --len | int | 32 | En generate: longitud del secreto en caracteres. |
| --format | enum | password | En generate: formato del valor — password, passphrase o hex. |
| --json | bool | false | En list, emite los metadatos como JSON estructurado en stdout. |
Ficheros y rutas #
| Ruta | Contenido |
|---|---|
| /etc/imaxe/secrets.yml | Configuración del módulo: valores por defecto (length, format), dominios y lista de generate_on_first_boot. Se guarda con permisos 0600. |
Ejemplo de secrets.yml:
defaults:
length: 32
format: password
domains: {}
generate_on_first_boot:
- mariadb
- tripwireCon esa configuración, un sudo imaxe secrets generate sin dominio en el primer arranque crea los secretos de mariadb y tripwire con la longitud y el formato por defecto.
Códigos de salida y logs #
Cada ejecución devuelve un código que puedes comprobar con echo $? — útil para encadenar en scripts:
get sin dominio).Uso típico en un script, aprovechando la salida limpia de get:
$ sudo imaxe secrets generate mariadb \
&& sudo imaxe secrets get mariadb | some-tool --stdin-password \
|| echo "falló con código $?"Resolución de problemas #
| Síntoma | Causa probable | Solución |
|---|---|---|
| Sale NOTFOUND (código 3) | El dominio o el --field aún no se ha generado. | Créalo primero con secrets generate <dominio> (y el mismo --field). |
| Sale USAGE (código 2) | get o rotate lanzados sin indicar el dominio. | Pasa el dominio como argumento; es obligatorio en esos subcomandos. |
generate no cambia el valor | El secreto ya existía: generate es idempotente por diseño. | Si quieres un valor nuevo, usa secrets rotate <dominio>. |
Permission denied al leer | El fichero es 0600 y lo lanzaste sin privilegios. | Ejecuta el comando con sudo; solo root accede al secreto. |
¿Te atascaste con el módulo Secretos?
Escríbenos con la salida de «imaxe <módulo> status --json» y te respondemos rápido.