O que faz este módulo #
Quase todos os serviços da tua instância precisam de um segredo: a palavra-passe da base de dados, a passphrase de uma ferramenta de integridade, uma chave de API… Guardá-los à mão — ou pior, deixá-los nos valores por omissão — é uma das formas mais comuns de uma máquina acabar comprometida.
O módulo secrets trata desse ciclo de vida localmente: gera cada segredo com um gerador criptograficamente seguro (CSPRNG), guarda-o com permissões 0600 (só o root o pode ler), devolve-o com saída limpa pronta para encadear num pipe, e roda-o quando precisas. Tudo está organizado por domínios (por exemplo mariadb ou tripwire), e cada domínio pode ter vários campos.
O generate é idempotente: se o segredo de um domínio já existir, não lhe toca. Assim, uma única imagem pode criar os seus segredos no primeiro arranque de cada instância sem que duas máquinas partilhem a mesma palavra-passe. Os valores nunca são registados no log nem mostrados no list.
Tarefas comuns #
Escolhe o que queres fazer. Cada receita traz o comando já escrito — basta trocar o domínio pelo teu e clicar em Copiar.
1
Gerar o segredo de um serviço
Cria uma palavra-passe forte para um domínio, apenas se ainda não existir.
Liga-te por SSH ao teu servidor com o utilizador ubuntu.
Gera o segredo para o domínio mariadb. Como é idempotente, podes executá-lo as vezes que quiseres sem receio de sobrescrever:
$ sudo imaxe secrets generate mariadbPrecisas de uma passphrase longa para outra ferramenta e num campo específico? Ajusta --format, --len e --field:
$ sudo imaxe secrets generate tripwire --field local.passphrase --format passphrase --len 400600. Se já existia, nada mudou — o comando termina na mesma com sucesso.2
Ler um segredo para o usar
Obtém o valor em bruto, pronto para encadear noutro comando.
O get imprime apenas o valor, sem decoração nem quebras de linha extra, para que o possas passar a outro processo por pipe:
$ sudo imaxe secrets get mariadbO segredo está num campo específico do domínio? Aponta-lhe com --field:
$ sudo imaxe secrets get tripwire --field local.passphrasePASS="$(sudo imaxe secrets get mariadb)" e usá-la diretamente no teu script.3
Rodar um segredo
Substitui o valor por um novo e marca o domínio como rodado.
Gera um novo valor para o domínio. Ao contrário do generate, o rotate substitui o segredo existente:
$ sudo imaxe secrets rotate mariadblist). Lembra-te de atualizar o serviço que usa esse segredo com o novo valor do get.4
Ver que domínios existem
Consulta os metadados sem expor nenhum valor.
Lista os domínios com os seus metadados (quando foram criados e quando foram rodados). Nunca mostra o próprio segredo:
$ sudo imaxe secrets listPrecisas dele para um script ou uma verificação automática? Pede a saída em JSON:
$ sudo imaxe secrets list --jsonO segredo só é legível pelo root enquanto vive no disco. Assim que o lês com get passa para o teu terminal e a tua shell: evita deixá-lo no histórico (history), em variáveis de ambiente demasiado exportadas ou em logs. Prefere substituições de comando pontuais como "$(sudo imaxe secrets get mariadb)".
Sinopse #
imaxe secrets <subcomando> [<dominio>] [--field CLAVE] [flags]Todos os subcomandos requerem privilégios de root (usa sudo) porque leem e escrevem ficheiros 0600 em /etc/imaxe/. Adiciona --json a list para obter saída legível por máquina, apta para scripting. Lembra-te: o get emite o valor em bruto, sem decoração, pronto para um pipe.
Subcomandos #
| Subcomando | O que faz | Flags relevantes |
|---|---|---|
| generate | Cria o segredo de um domínio se não existir (idempotente, CSPRNG). Sem domínio, gera os de generate_on_first_boot. | --len, --format, --field |
| get | Devolve o valor de um segredo com saída limpa, apta para um pipe. | --field |
| rotate | Gera um novo segredo e marca o domínio como rodado. | --field |
| list | Lista os domínios e os metadados (criado, rodado). Nunca mostra valores. | --json |
Argumentos e flags #
| Flag | Tipo | Por omissão | Descrição |
|---|---|---|---|
| <dominio> | string | — | Domínio do segredo (por exemplo mariadb, tripwire). Obrigatório em get e rotate. Em generate, vazio = os domínios de generate_on_first_boot. |
| --field | string | value | Campo dentro do domínio. Permite guardar vários segredos por domínio (por exemplo local.passphrase). |
| --len | int | 32 | Em generate: comprimento do segredo em caracteres. |
| --format | enum | password | Em generate: formato do valor — password, passphrase ou hex. |
| --json | bool | false | Em list, emite os metadados como JSON estruturado em stdout. |
Ficheiros e caminhos #
| Caminho | Conteúdo |
|---|---|
| /etc/imaxe/secrets.yml | Configuração do módulo: valores por omissão (length, format), domínios e a lista generate_on_first_boot. Guardado com permissões 0600. |
Exemplo de secrets.yml:
defaults:
length: 32
format: password
domains: {}
generate_on_first_boot:
- mariadb
- tripwireCom essa configuração, um sudo imaxe secrets generate sem domínio no primeiro arranque cria os segredos de mariadb e tripwire com o comprimento e o formato por omissão.
Códigos de saída e logs #
Cada execução devolve um código que podes verificar com echo $? — útil para encadear em scripts:
get sem domínio).Uso típico num script, aproveitando a saída limpa do get:
$ sudo imaxe secrets generate mariadb \
&& sudo imaxe secrets get mariadb | some-tool --stdin-password \
|| echo "falló con código $?"Resolução de problemas #
| Sintoma | Causa provável | Solução |
|---|---|---|
| Sai NOTFOUND (código 3) | O domínio ou o --field ainda não foi gerado. | Cria-o primeiro com secrets generate <dominio> (e o mesmo --field). |
| Sai USAGE (código 2) | get ou rotate executados sem especificar o domínio. | Passa o domínio como argumento; é obrigatório nesses subcomandos. |
generate não muda o valor | O segredo já existia: o generate é idempotente por design. | Se queres um novo valor, usa secrets rotate <dominio>. |
Permission denied ao ler | O ficheiro é 0600 e executaste-o sem privilégios. | Executa o comando com sudo; só o root pode aceder ao segredo. |
Ficou bloqueado com o módulo Segredos?
Escreva-nos com a saída de «imaxe <module> status --json» e respondemos rapidamente.