# runner mkey

Gerencia a master key (mkey) do servidor. A mkey encripta todas as ckeys (chaves por app) antes de gravá-las no state. Sem ela, nenhuma ckey armazenada pode ser decriptada e todos os bundles secrets.enc ficam ilegíveis.

ATENCAO — perda de mkey e irreversivel. Nao existe recuperacao de secrets sem a mkey. Faca backup antes de qualquer operacao destrutiva no servidor.

Use quando: backup pre-disaster, migracao para novo servidor, auditoria de seguranca, ou rotacao periodica da mkey.

Consulte tambem: Restaurar em novo servidor.

# Subcomandos

Invocar runner mkey sem subcomando e equivalente a runner mkey reveal (compatibilidade retroativa).

# runner mkey reveal

Exibe a master key em plaintext. Toda chamada e registrada no audit log do Runner com timestamp e usuario.

runner mkey reveal [flags]

Use quando: precisa copiar a mkey para um cofre, ou verificar que a mkey correta esta instalada antes de um disaster recovery.

runner mkey reveal
# Saida:
# Master key: <base64-encoded-key>
# (audit logged at 2026-05-27T14:00:00Z)

# runner mkey export

Exporta a mkey como blob selado em formato base64 para armazenamento offline.

runner mkey export [flags]

Use para backup pre-disaster:

runner mkey export --sealed > /backup/mkey-$(hostname)-$(date +%Y%m%d).sealed

Guarde o arquivo .sealed em local seguro e separado do servidor (vault, senha manager, outra maquina). Sem ele, disaster recovery completo nao e possivel.

# runner mkey rotate

Gera uma nova master key e re-sela todas as ckeys armazenadas atomicamente. A operacao e transacional: ou todas as ckeys sao atualizadas, ou nenhuma.

runner mkey rotate [flags]

Antes de rotar: exporte a mkey atual com runner mkey export --sealed e salve em local seguro. Se a rotacao falhar a meio, voce precisara do backup para restaurar o estado.

# 1. Backup obrigatorio antes de rotar
runner mkey export --sealed > /backup/mkey-pre-rotate.sealed

# 2. Rotar
runner mkey rotate --force

# Workflow de Disaster Recovery

Quando o servidor e perdido e voce precisa recriar o ambiente:

1. Instale o Runner no novo servidor (runner init)
2. Restaure a mkey original a partir do backup .sealed
3. Reregistre as apps com runner add — os secrets.enc ja existentes serao decriptaveis porque a mkey e a mesma
4. Valide com runner doctor

Sem o arquivo .sealed, os secrets de todas as apps precisam ser reinseridos manualmente via wizard (runner add).

# Erros comuns

• mkey not initialized — Execute runner init para gerar a mkey pela primeira vez.
• mkey rotation failed: ckeys still using old key — Alguma ckey nao pode ser re-selada. Execute runner doctor --json para identificar a app com problema e reregistre-a antes de tentar rotar novamente.
• --force required — A rotacao e destrutiva e exige a flag --force para confirmar que voce entende as consequencias.
• export: mkey not found — O Runner nao tem mkey inicializada; rode runner init ou restaure de um backup.