Comandos do appliance

Os comandos ironflock appliance instalam o appliance IronFlock em um servidor Linux que você mesmo opera e cuidam dele a partir daí. Com eles, você instala o appliance, altera as suas configurações, o atualiza, o inicia, para e reinicia, lê os seus logs, redefine a senha de admin, faz backup, restauração e rotação dos seus segredos e o remove de novo.

O appliance é o sistema IronFlock completo em uma única máquina no local. O que ele é, os seus modos HTTPS, a sua rede e a sua operação estão descritos em IronFlock Appliance. Os requisitos da máquina (CPU, memória, armazenamento, sincronização de horário) estão na página Instalação dele.

Nota: Estes comandos são novos na release 2.1.0 do ironflock. Eles passaram por uma execução de teste, do appliance install ao appliance remove --purge, em uma máquina virtual Ubuntu 24.04 nova (amd64). Ainda não foi comprovada uma atualização que falha, com a sua reversão para a release anterior.

O appliance

Os comandos do appliance rodam no Linux. O appliance install precisa de um sistema baseado em Debian ou Ubuntu com systemd. No macOS, os comandos terminam com o código de saída 3 antes de examinar qualquer coisa; execute-os na máquina do appliance, ou a partir do Mac com --host.

Execute-os como root, com sudo. Um comando que altera o sistema termina com o código de saída 3 sem root e não chama o sudo por conta própria (Privilégios de root).

Cada comando também aceita as flags globais --yes, --json, --download-base, --host, --hosts e --parallel (Flags globais). Uma pergunta precisa de um terminal; sem ele, informe --yes (Perguntas e confirmação).

O ironflock status mostra o appliance instalado: a sua versão e o seu canal, o endereço da sua UI, se a sua licença está presente, o seu serviço, a saúde dos seus serviços e uma atualização pendente (ironflock status).

Como é um appliance instalado

Além do ironflock.service, a instalação configura um watchdog, que verifica o router e o backend a cada cinco minutos e reinicia o ironflock.service quando eles não estão bem, no máximo uma vez a cada cinco minutos, e um timer que tenta de novo, a cada hora, uma atualização da UI que falhou.

Mantenha o /usr/local/bin/ironflock no lugar: as units do appliance o executam a cada início. O appliance install se recusa a rodar a partir de outro lugar e diz como instalá-lo ali. O ironflock status, executado como root, avisa quando esse binário falta ou é mais antigo que o que instalou ou atualizou o appliance por último. O sudo ironflock self-update o substitui pela release mais nova (ironflock self-update).

O appliance também executa o agente do dispositivo do próprio host, que o appliance install instala, a menos que você informe --no-agent. Esse agente é mantido com os comandos agent.

Uma alteração por vez

Roda uma instalação, atualização ou outra alteração do appliance por vez. Uma segunda espera pela primeira e diz isso:

Another IronFlock install, update or other change of the appliance is running on this host (process <pid>); waiting up to <time> for it to finish

install, update, configure, rotate, revoke-direct-access, reset-admin-password e restore esperam até uma hora. start, stop, restart e remove esperam até 30 segundos. Quando a outra execução ainda continua depois disso, o comando não altera nada e termina com o código de saída 3.

ironflock appliance install

Instala o appliance IronFlock em /opt/ironflock e o inicia. Ele espera até que todos os serviços estejam saudáveis e que a nuvem IronFlock alcance o appliance, e então mostra o login de admin da UI web, uma única vez, em um terminal.

ironflock appliance install --license-file <file> [flags]

Roda em: um Linux baseado em Debian ou Ubuntu com systemd. Root: necessário.

A instalação configura:

• a release do canal, ou a que --version indica, verificada com a chave de release do appliance;
• a configuração e os segredos do appliance;
• o agente do dispositivo do próprio host, e o Docker quando ele falta;
• as configurações do host;
• o login do Docker no registro com a chave de licença;
• as imagens da release;
• o ironflock.service.

Quando o Docker falta, a instalação executa como root o script de instalação do Docker de get.docker.com. Esse download é protegido apenas por TLS.

Os modos HTTPS e o que cada um criptografa estão descritos em HTTPS e certificados e em Segurança. A senha do proxy segue as regras de Segredos: uma URL de proxy com senha é uma linha de comando incorreta.

A chave de licença

A chave de licença é a Instance Key que você cria em ironflock.com em Perfil → Instâncias (Instalação). Ela vem de --license-file ou de --license. Um appliance que já está instalado mantém a sua chave sem nenhuma das duas. Uma chave em license.env que não é uma chave de licença válida (uma chave de licença é um UUID) é ignorada, com um aviso, por todo comando do appliance; a execução precisa então de uma chave, ou de --skip-login.

Variáveis de ambiente

Algumas flags obtêm o seu padrão de uma variável de ambiente:

O sudo descarta a maioria das variáveis do seu shell. Passe-as com sudo env NAME=value ironflock appliance install ....

O registro das escolhas da instalação

O <install-dir>/install.json, que só o root lê, guarda as escolhas que nem o .env nem as units guardam: o registro e o seu usuário, o host do appliance (IRONFLOCK_APPLIANCE_HOST), --no-agent, a base de download de --bucket-url e a versão do ironflock que instalou ou atualizou o appliance por último. Ele não contém nenhuma senha, token ou chave.

Um appliance install posterior, um appliance update e o appliance configure mantêm essas escolhas, a menos que uma flag (ou a sua variável) diga o contrário. Uma flag informada prevalece e é registrada. Para voltar a um padrão, informe --registry "", --no-agent=false ou um IRONFLOCK_APPLIANCE_HOST vazio.

Um registro que não pode ser lido, ou um de um formato mais novo, interrompe o install, o update e o configure antes que eles alterem qualquer coisa, com o código de saída 3. A mensagem diz o que fazer: mover o registro para o lado e instalar de novo com as flags, ou usar o ironflock mais novo.

Executar de novo

Executado em um appliance instalado, o comando o leva à release e às opções informadas e mantém os seus segredos e configurações. Use isso para mudar a release de propósito: ironflock appliance install --version <version> baixa, reinicia e verifica essa release de novo, também quando ela já está rodando.

Uma execução que parou continua de onde parou quando o mesmo comando roda de novo.

Assim que as suas verificações de saúde passam, a instalação remove a cópia de uma release anterior que uma atualização guardou (/opt/ironflock/.update-previous): a release que ela instalou é a que deve rodar.

A partir da sua primeira alteração, um terminal ou uma sessão SSH perdidos (SIGHUP), ou uma saída que ninguém lê mais (um pipe fechado), não interrompem a instalação. Ctrl-C e SIGTERM a interrompem. A instalação continua escrevendo no terminal depois de uma sessão SSH perdida, para que a senha de admin não se perca. Com a configuração use_pty do sudo, um terminal que continua aberto, mas não é mais lido, pode por isso segurar a instalação enquanto ela detém a trava de instalação.

Exemplos

# Instalar o appliance; a chave de licença vem de um arquivo
sudo ironflock appliance install --license-file license.txt
# Instalar com HTTPS da CA própria do appliance; a chave vem da entrada padrão
sudo ironflock appliance install --license-file - --tls < license.txt
# Instalar atrás de um proxy; os hosts abaixo de .corp.example.com não passam por ele
sudo ironflock appliance install --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
# Perguntar o endereço e o domínio do appliance, e instalar com HTTPS
sudo ironflock appliance install --license-file license.txt --interactive --tls

Quando recusa e quando falha

• Uma base de download de --bucket-url que as units não conseguem indicar como está (com credenciais, %, espaço em branco, $, \, aspas, um caractere de controle, bytes que não são UTF-8) é recusada antes que qualquer coisa seja gravada, com o código de saída 2.
• O comando recusa com o código de saída 3 quando não roda como root, quando o registro das escolhas da instalação não pode ser lido e quando outra execução detém a trava de instalação além da espera de uma hora. Ele também recusa quando o ironflock em execução não é /usr/local/bin/ironflock, e diz como instalá-lo ali.
• Uma etapa que falha encerra o comando com o código de saída 1. Execute o mesmo comando de novo para continuar.

ironflock appliance configure

Altera as configurações de um appliance instalado: a sua licença, o modo TLS (também com um certificado próprio), o proxy, mais nomes de host para a UI, o túnel e a política de segundo fator.

ironflock appliance configure [flags]

Roda em: Linux, com um appliance instalado. Root: necessário.

As configurações ficam no .env e nos arquivos do appliance, então uma atualização as mantém. Uma configuração não informada mantém o que o appliance tem. Só uma execução que alterou algo reinicia o appliance, então o mesmo comando executado duas vezes não altera nada na segunda vez.

• Uma nova licença (--license, --license-file, ou --license-file - para a entrada padrão) precisa abrir o registro antes de ser gravada. O seu login no registro vai para --registry como --registry-user, senão para os que a instalação escolheu (o registro), senão para o registro a partir do qual o espelho do appliance sincroniza. Um login com --registry ou --registry-user os guarda no registro para as atualizações.
• --tls-cert e --tls-key instalam o seu certificado e ativam o TLS, e os dispositivos passam para o domínio do appliance.
• --http-proxy "" ou --https-proxy "", informado sozinho, remove o proxy.
• --no-agent da instalação permanece como estava.
• O Caddyfile de que o TLS precisa vem de --bucket-url, senão de onde a instalação obteve as releases.

Exemplos

# Dar ao appliance uma nova chave de licença a partir de um arquivo
sudo ironflock appliance configure --license-file license.txt
# Servir a UI com o certificado da sua organização
sudo ironflock appliance configure --tls-cert wildcard.crt --tls-key wildcard.key
# Definir um proxy, e removê-lo de novo
sudo ironflock appliance configure --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
sudo ironflock appliance configure --https-proxy ""
# Exigir um segundo fator de todos os usuários
sudo ironflock appliance configure --2fa required

Antes de definir --2fa required, certifique-se de que todas as contas tenham um segundo fator: um usuário sem segundo fator não consegue mais fazer login (Contas e acesso).

Quando recusa

O comando recusa com o código de saída 3, e não altera nada, quando não roda como root, quando o registro das escolhas da instalação não pode ser lido, quando outra execução detém a trava de instalação além da espera de uma hora, e enquanto uma atualização está incompleta (Quando uma atualização ficou incompleta).

ironflock appliance update

Atualiza o appliance desta máquina para a release mais nova do seu canal, ou para a release que --version indica. A release é verificada com a chave de release do appliance, as suas imagens são baixadas e o appliance reinicia com ela. O comando espera até que todos os serviços estejam saudáveis e que a nuvem IronFlock alcance o appliance. O appliance mantém os seus segredos e configurações. As imagens das releases anteriores são removidas assim que a nova está saudável.

ironflock appliance update [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: nada, exceto com --discard-previous.

As releases vêm de --bucket-url, senão de IRONFLOCK_BUCKET_URL, senão de onde a instalação as obteve (o registro das suas escolhas, /opt/ironflock/install.json, ou as suas units o indicam), senão da IronFlock. O registro, o seu usuário, o host do appliance e --no-agent ficam como a instalação os escolheu.

Um novo canal permanece quando a atualização tem sucesso; o canal anterior volta com uma reversão. O Apply update da UI executa a mesma atualização.

Assim que as suas verificações passam, uma instalação ou uma atualização também tira o próprio dispositivo do appliance do segredo que todo appliance compartilhava antes e o passa para o valor de APPLIANCE_DEVICE_SECRET. O agente dele reinicia então 35 segundos depois da execução. Uma mudança que não pode ser feita é um aviso que diz por quê; a próxima instalação ou atualização tenta de novo.

Já atualizado

Um appliance que já roda a release mais nova do seu canal (ou a release que --version indica), no mesmo canal e com a mesma base de download, é deixado como está. O comando diz isso e termina com o código de saída 0; com --json, o result é nothing-to-do. Para baixar, reiniciar e verificar essa release de novo de propósito, execute ironflock appliance install --version <version>.

Isso só vale para um appliance que a última atualização deixou limpo. Com uma cópia guardada de uma release anterior (uma atualização que ficou incompleta), ou com um arquivo de status que diz failed ou running, a atualização executa tudo de novo.

Reversão

Antes que a atualização altere qualquer coisa, ela guarda os arquivos da release em execução em /opt/ironflock/.update-previous. Quando a atualização falha depois de ter alterado o appliance, esses arquivos são colocados de volta e a release anterior inicia de novo. Isso não precisa de rede, pois as imagens dela estão na máquina. Isso é tentado até três vezes. Então o comando desiste e deixa os arquivos da release anterior no lugar, para que o próximo início do appliance seja essa release.

Uma atualização que falha antes de ter alterado qualquer coisa não altera mais nada e diz isso: por exemplo, uma release que não existe ou não está assinada, ou uma base de download que não responde.

Uma release pode precisar de um ironflock mais novo que o que está rodando. Então nada é alterado, e o comando diz qual ironflock instalar primeiro. O appliance update não atualiza o ironflock por conta própria; o ironflock self-update instala o mais novo.

Arquivo de status e nova tentativa

A atualização escreve o seu progresso em triggers/apply-update.status, como faz a atualização da UI, para que a UI o mostre. A sua saída também vai para triggers/apply-update.log. O timer que tenta de novo uma atualização da UI que falhou não tenta de novo uma atualização deste comando que falhou, ou que foi interrompida antes de alterar qualquer coisa.

Interrupções

• Ctrl-C ou SIGTERM antes que a atualização tenha alterado qualquer coisa a interrompe. Depois disso, o primeiro traz a release anterior de volta (código de saída 130), e um segundo interrompe imediatamente.
• Um terminal ou uma sessão SSH perdidos (SIGHUP), ou uma saída que ninguém lê mais, não interrompem a atualização. A atualização, e uma reversão, vão até o fim. O arquivo de status e o ironflock status dizem como ela terminou.
• Com --host sem terminal, os dois primeiros Ctrl-C chegam à máquina. Depois do primeiro, o comando espera até 30 minutos que a atualização termine ali; depois do segundo, 15 segundos; um terceiro o encerra aqui imediatamente. Uma sessão perdida aqui, ou SIGTERM, não é um Ctrl-C: o comando termina aqui imediatamente. Sempre que ele termina aqui primeiro, a atualização continua na máquina, e ironflock --host <machine> status mostra como ela terminou.

Quando uma atualização ficou incompleta

Uma atualização ficou incompleta quando começou a alterar o appliance e depois não terminou: ela foi interrompida, a máquina caiu, ou a sua reversão não conseguiu subir a release anterior. O diretório de instalação pode então conter arquivos de duas releases. A cópia guardada indica a release que se sabe que roda, e o ironflock status também a indica.

• A próxima atualização coloca essa cópia de volta primeiro e depois atualiza. Uma cópia que não pode ser lida nem colocada de volta interrompe a atualização com o código de saída 3, e o erro indica ironflock appliance install --version <version>.
• O timer de nova tentativa, a cada hora, coloca a cópia de volta por conta própria, reinicia essa release e a verifica, também quando não existe release mais nova.
• configure, rotate, revoke-direct-access, restore e reset-admin-password recusam antes de qualquer alteração, com o código de saída 3. Eles indicam as três saídas: ironflock appliance update; ironflock appliance install --version <version>; e, sem rede, ironflock appliance update --discard-previous.
• backup apenas lê, e avisa. start, stop e restart deixam a cópia como está. remove leva a cópia junto com o resto dos arquivos do appliance.
• appliance install roda como sempre e, assim que as suas verificações de saúde passam, remove a cópia.

Para trabalhar manualmente nos arquivos de uma atualização incompleta, defina primeiro IRONFLOCK_UPDATE_RETRY=off no .env. Caso contrário, o timer de nova tentativa coloca a release anterior de volta em cerca de uma hora. Essa configuração desativa o timer de nova tentativa por inteiro, incluindo a sua reversão.

--discard-previous

ironflock appliance update --discard-previous [--yes]

Não atualiza nada. Remove a cópia da release anterior que uma atualização guardou (/opt/ironflock/.update-previous), em qualquer estado e também quando ela não pode ser lida, e não altera mais nada. Não precisa de rede.

É a saída sem rede quando uma atualização ficou incompleta e a sua release anterior não inicia de novo. Os arquivos do diretório de instalação ficam como estão agora, essa release não pode mais ser colocada de volta, e os comandos que recusavam rodam de novo.

Ele diz o que remove e pergunta antes, com “No” pré-selecionado; --yes responde sim. Sem terminal, ou com --json, ele precisa de --yes; caso contrário, termina com o código de saída 4. Sem cópia, ele diz isso e termina com o código de saída 0. Ele não combina com --version, --channel ou --bucket-url (código de saída 2). Com --json, o resultado tem action (discarded, cleaned ou none), path, version, state e removed.

Exemplos

# Atualizar para a release mais nova do canal
sudo ironflock appliance update
# Instalar a release 1.6.41, também para voltar a ela
sudo ironflock appliance update --version 1.6.41
# Mudar para o canal de testes e ler o resultado como JSON
sudo ironflock appliance update --channel test --json
# Remover a cópia da release anterior, sem rede
sudo ironflock appliance update --discard-previous

Resultado

{"from":"1.6.40","target":"1.6.41","version":"1.6.41","result":"updated"}

Uma atualização que falhou é um erro que diz se o appliance voltou à release anterior. Com --json, o seu kind é um destes, também quando ela foi interrompida:

ironflock appliance start

Inicia o appliance quando ele não está rodando: o ironflock.service inicia os seus contêineres (docker compose up), e o seu watchdog e os seus outros paths e timers iniciam de novo. Os serviços levam um ou dois minutos para subir; o ironflock status mostra a saúde deles.

ironflock appliance start [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: nada. O comando não tem flags próprias.

Quando uma restauração deixou roles do banco de dados com as suas senhas antigas, porque o appliance não estava rodando naquele momento, elas recebem as senhas do .env restaurado assim que os seus bancos de dados rodam (até um minuto). Uma role que não responde fica para o próximo início, com um aviso, e o início continua.

sudo ironflock appliance start
sudo ironflock appliance start --json

Enquanto outra execução altera o appliance, o comando espera até 30 segundos e diz isso; quando essa execução continua, ele não altera nada e termina com o código de saída 3.

ironflock appliance stop

Para o appliance: o seu watchdog e os seus outros paths e timers e o que eles iniciaram, depois o ironflock.service, que para e remove os seus contêineres (docker compose down). Os seus dados permanecem.

ironflock appliance stop [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: sim, depois de dizer o que a parada encerra; --yes responde.

A UI fica offline, assim como todo dispositivo que se conecta ao appliance, também o agente desta máquina. O ironflock appliance start inicia o appliance de novo, assim como a próxima inicialização. O comando não tem flags próprias.

# Parar o appliance; o comando diz o que isso encerra e pergunta
sudo ironflock appliance stop
# Pará-lo sem pergunta
sudo ironflock appliance stop --yes

A resposta não, ou uma pergunta sem terminal e sem --yes, encerra o comando com o código de saída 4. Enquanto outra execução altera o appliance, o comando espera como o start.

ironflock appliance restart

Reinicia o appliance: o ironflock.service para os seus contêineres e os inicia de novo (docker compose down, depois up), como faz o seu watchdog. Os paths e timers que o appliance stop parou iniciam de novo.

ironflock appliance restart [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: nada. O comando não tem flags próprias.

A UI e os dispositivos que se conectam ao appliance ficam offline por um ou dois minutos; os seus dados permanecem. O ironflock status mostra a saúde dos serviços assim que eles sobem. As roles do banco de dados que uma restauração deixou com as suas senhas antigas recebem as do .env, como no start.

sudo ironflock appliance restart
sudo ironflock appliance restart --json

Enquanto outra execução altera o appliance, o comando espera como o start.

ironflock appliance logs

Mostra o que os serviços do appliance escreveram, como o docker compose logs o mostra: por padrão, as últimas 100 linhas de cada serviço. Não altera nada.

ironflock appliance logs [<service>...] [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: nada.

Indique serviços para ver apenas os deles, como router, backend, kratos ou caddy.

Com --json, cada linha é um objeto JSON, com a linha como a sua mensagem.

# As últimas 100 linhas de cada serviço
sudo ironflock appliance logs
# Tudo o que o backend escreveu na última hora
sudo ironflock appliance logs backend --since 1h
# As últimas 20 linhas do router e do Kratos, depois cada nova linha até Ctrl-C
sudo ironflock appliance logs router kratos --follow --lines 20

ironflock appliance reset-admin-password

Dá uma nova senha ao usuário admin da UI, para um operador que a perdeu. A senha é definida primeiro no banco de dados, o que encerra todas as sessões ativas do admin, e depois no .env como APPLIANCE_ADMIN_PASSWORD. O appliance precisa estar rodando.

ironflock appliance reset-admin-password [flags]

Roda em: Linux, com um appliance em execução. Root: necessário.

A nova senha é mostrada uma única vez, e somente em um terminal. Sem terminal, e com --json, o comando diz em vez disso onde ela está armazenada. Ele recusa com o código de saída 3 enquanto uma atualização está incompleta (Quando uma atualização ficou incompleta).

sudo ironflock appliance reset-admin-password

ironflock appliance backup

Grava em um arquivo tar.gz tudo do appliance que não pode ser recriado: o .env com todos os segredos, o license.env, a CA local do certificado TLS, o par de chaves de token do registro, o registro de segredos e o rotation.log.

ironflock appliance backup [-o <file>] [flags]

Roda em: Linux. Root: necessário.

Sem -o, o arquivo compactado vai para a saída padrão, que não pode ser um terminal. Um arquivo para o qual ela é redirecionada fica legível somente pelo seu dono.

Aviso: O arquivo compactado contém todos os segredos do appliance. Uma FLEETDB_SECRET_KEYS ou FILE_CRED_KEY perdida não pode ser recuperada de nenhuma outra forma. Criptografe o arquivo compactado e guarde-o junto com os backups dos volumes.

Não estão no arquivo compactado: o certificado TLS e a sua chave (um certificado gerado é assinado de novo a partir da CA), a configuração do Kratos, os arquivos da release e os volumes Docker. De certs/ca e registry-token-certs, ele pega os arquivos que uma instalação cria ali (rootCA.crt, rootCA.key, rootCA.srl; token_private.key, token_public.crt, token_public.der, também com .prev ou .new). Qualquer outro arquivo ali fica de fora, com um aviso que o indica, pois o restore não aceita nenhum outro.

# Gravar o arquivo compactado em um arquivo que só o root pode ler
sudo ironflock appliance backup -o /root/appliance-secrets.tar.gz
# Gravá-lo na saída padrão, redirecionada para um arquivo
sudo ironflock appliance backup > appliance-secrets.tar.gz

ironflock appliance restore

Coloca de volta no diretório de instalação um backup que o appliance backup gravou.

ironflock appliance restore <file> [flags]

Roda em: Linux. Root: necessário.

O comando pega os arquivos que um backup contém e nada mais, cada um com o dono e o modo que uma instalação lhe dá. Em certs/ca e registry-token-certs, ele pega apenas os arquivos que uma instalação cria ali. Um arquivo compactado que contém qualquer outra coisa é recusado antes de qualquer alteração, e o erro indica o quê.

Os segredos de um appliance instalado só são substituídos com --force; o seu .env é mantido como .env.prev. Sem --force, a restauração sobre um appliance instalado é recusada antes de qualquer alteração, com o código de saída 3, e a mensagem indica a restauração com --force e depois o appliance restart.

Uma chave de licença no backup que não é uma chave de licença válida é restaurada como está, com um aviso: todo comando do appliance a ignora.

Senhas do banco de dados

• Enquanto o banco de dados do appliance roda, as suas roles recebem as senhas restauradas imediatamente. Reinicie então o appliance (appliance restart), para que todos os serviços leiam os arquivos restaurados.
• Enquanto o appliance não roda, as suas roles do banco de dados mantêm as senhas de antes. A restauração as marca (<install-dir>/.db-roles-pending; roles_pending com --json). O próximo início as define com o .env restaurado: appliance start ou restart, o início na inicialização, uma instalação ou uma atualização.

# Restaurar em um appliance instalado e depois reiniciá-lo
sudo ironflock appliance restore appliance-secrets.tar.gz --force
sudo ironflock appliance restart

Ele recusa com o código de saída 3 enquanto uma atualização está incompleta (Quando uma atualização ficou incompleta).

ironflock appliance rotate

Dá um novo valor a um segredo do appliance. O novo valor vai para onde o antigo está guardado (uma role do banco de dados, o arquivo de dispositivo do agente, o par de chaves de token do registro) e para o .env. Depois, apenas os serviços que o leem são recriados, e o comando verifica se eles estão saudáveis.

ironflock appliance rotate <name> [flags]

Roda em: Linux, com um appliance em execução. Root: necessário. Pergunta: para um segredo que algo mais também guarda; --yes responde.

O .env anterior à alteração fica guardado como .env.prev, legível somente pelo root. O rotation.log lista cada rotação, nunca um valor.

• Um segredo que algo mais também guarda (dados, um dispositivo, um token) pergunta antes da sua rotação; --yes responde.
• FILE_CRED_KEY precisa de uma escolha para as chaves de acesso direto dos clientes. --keep-direct-access: elas continuam funcionando, para uma rotação planejada; encerre-a depois com revoke-direct-access. --revoke-direct-access: elas deixam de funcionar e são removidas, após suspeita de vazamento.
• APPLIANCE_ADMIN_PASSWORD é o mesmo que reset-admin-password.

Os segredos que ele rotaciona:

POSTGRES_PASSWORD, PGPASSWORD_KRATOS, PGPASSWORD_ACCT_MANAGER,
PGPASSWORD_ACCT_PUSHER, PGPASSWORD_EXT_ACCT_USER, PGPASSWORD_AUDIT_SANDBOX,
DATASERVICE_PASSWORD, WAMP_SYSTEM_SECRET, WAMP_SECRET_SVC_VDM,
WAMP_SECRET_SVC_IDE, WAMP_SECRET_SVC_IDE_PROXY, WAMP_SECRET_SVC_GIT,
WAMP_SECRET_SVC_REGISTRY, WAMP_SECRET_SVC_REGISTRY_PROXY,
WAMP_SECRET_SVC_ACCT, WAMP_SECRET_SVC_ACCT_PUSH, WAMP_SECRET_SVC_PAYMENT,
WAMP_SECRET_SVC_FLEETDB, WAMP_SECRET_SVC_FLEETFILES, WAMP_SECRET_SVC_AI,
WAMP_SECRET_SVC_TUNNEL, WAMP_SECRET_SVC_RENDERER, WAMP_SECRET_SVC_WEBSERVER,
WAMP_SECRET_SVC_REAPI, WAMP_SECRET_SVC_AUTH, RENDER_TICKET_KEY,
FILES_FORWARD_SECRET, KRATOS_WEBHOOK_SECRET, KRATOS_SECRETS_PAGINATION,
REGISTRY_HTTP_SECRET, TUNNEL_DASHBOARD_PASSWORD, EDGE_SESSION_SECRET,
OBJECTSTORE_ADMIN_ACCESS_KEY, OBJECTSTORE_ADMIN_SECRET_KEY, FILE_CRED_KEY,
FLEETDB_SECRET_KEYS, KRATOS_SECRETS_COOKIE, KRATOS_SECRETS_CIPHER,
APPLIANCE_DEVICE_SECRET, APPLIANCE_ADMIN_PASSWORD, REGISTRY_TOKEN_KEY

O que uma rotação faz com cada tipo de segredo, e quais segredos rotacionar somente junto com a equipe da IronFlock, está descrito em Rotação de um segredo interno.

# Rotacionar o segredo de um serviço
sudo ironflock appliance rotate WAMP_SECRET_SVC_AI
# Rotacionar a chave de arquivos de forma planejada; as chaves de acesso direto continuam funcionando
sudo ironflock appliance rotate FILE_CRED_KEY --keep-direct-access --yes

Ele recusa com o código de saída 3 enquanto uma atualização está incompleta (Quando uma atualização ficou incompleta).

ironflock appliance revoke-direct-access

Encerra uma rotação de FILE_CRED_KEY feita com --keep-direct-access. Toda chave de acesso direto dos clientes que não foi criada com a FILE_CRED_KEY atual deixa de funcionar e é removida; a própria chave permanece. O serviço fleetfiles é recriado e informa o que removeu.

ironflock appliance revoke-direct-access [flags]

Roda em: Linux, com um appliance instalado. Root: necessário. Pergunta: sim, pois os donos dessas chaves precisam criar novas; --yes responde.

sudo ironflock appliance revoke-direct-access

Ele recusa com o código de saída 3 enquanto uma atualização está incompleta (Quando uma atualização ficou incompleta).

ironflock appliance remove

Remove o appliance IronFlock desta máquina e desfaz o que a sua instalação registrou no host. Os seus dados permanecem, a menos que você informe --purge.

ironflock appliance remove [flags]

Roda em: Linux. Root: necessário. Pergunta: sim, depois de listar o que sai e o que fica. A pergunta vem com “No” pré-selecionado: Enter sozinho não remove nada.

Ele remove:

• as units systemd do appliance, os seus contêineres e a sua rede no Docker;
• o login do Docker no registro da IronFlock;
• toda alteração que a sua instalação registrou no host (/etc/ironflock/appliance.json): as configurações de proxy que ela gravou, as suas configurações no daemon.json do Docker, as configurações do journal e os targets de suspensão mascarados;
• a cópia da release anterior que uma atualização guardou para a sua reversão (.update-previous no diretório de instalação).

Os volumes anônimos dos contêineres do appliance também saem, com ou sem --purge: nunca um volume nomeado, e nunca um que um contêiner ainda usa.

O que permanece

Sem --purge, os dados do appliance permanecem, para que uma instalação posterior os aproveite:

• o diretório de instalação (/opt/ironflock) com o .env, que contém os segredos, o license.env, o registro das escolhas da instalação (install.json) e a marca das senhas do banco de dados que uma restauração não conseguiu definir (.db-roles-pending);
• os volumes no Docker.

O --purge remove também esses, e as imagens: o que o appliance continha se perde para sempre.

Estes permanecem também com --purge:

• O próprio Docker e o agente do dispositivo do host. O ironflock agent remove remove o agente.
• Um arquivo que o appliance gravou e que foi alterado desde então, como as configurações de proxy que o ironflock agent configure definiu, com os drop-ins que as indicam, para que o agente mantenha o seu proxy.
• O que o registro do agente (/opt/ironflock/device-init/installed.json) indica como sendo do agente, e os targets de suspensão que o agente mascarou. O ironflock agent remove os remove.

Quando uma chamada falha

Quando uma chamada do desfazer continua falhando (por exemplo, um reinício de um Docker que foi removido manualmente), o registro permanece. O comando diz qual chamada falhou e termina com um erro. Execute-o de novo assim que isso funcionar, ou com --force, que descarta o registro mesmo assim e segue adiante após uma unit que não pode ser desabilitada ou um Docker que não responde.

Enquanto uma instalação, uma atualização ou outra alteração do appliance roda, o comando espera até 30 segundos e diz isso. Quando essa execução continua, ele não altera nada e termina com o código de saída 3.

Exemplos

# Remover o appliance e manter os seus dados; o comando lista o que sai e pergunta
sudo ironflock appliance remove
# Remover o appliance com todos os seus dados, sem pergunta
sudo ironflock appliance remove --purge --yes

A resposta não, ou uma pergunta sem terminal e sem --yes, encerra o comando com o código de saída 4.

Antes de remover um appliance de vez, transfira ou libere a sua licença enquanto ele ainda está online (Desativação).