Instalação

Uma linha instala o ironflock no Linux ou no macOS. Ela precisa de root, porque escreve em /usr/local/bin. Depois, o ironflock self-update o leva à release mais nova, e o ironflock version --check diz se há uma mais nova.

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash

O que a linha de instalação faz

1. Ela identifica o sistema (Linux ou macOS) e a arquitetura da máquina: amd64, arm64 ou ARM de 32 bits (v5 a v7) no Linux, Apple silicon ou Intel no macOS. Em Apple silicon, um shell que roda sob o Rosetta 2 também recebe o build para Apple silicon.
2. Ela baixa o version.txt e o ironflock dessa versão para esta máquina de https://instance-registry.ironflock.com/dl/cli/.
3. Ela verifica os dois com a chave de release da IronFlock que o script traz. No Linux, verifica a assinatura OpenPGP (.asc) com sqv ou gpgv. No macOS, verifica a assinatura RSA simples da mesma chave (.sig) com o /usr/bin/openssl do sistema, para que nada precise ser instalado antes.
4. Ela instala o binário como /usr/local/bin/ironflock, no lugar de um que já esteja lá. O novo arquivo é copiado ao lado do antigo e renomeado por cima dele, de modo que um ironflock em execução nesse momento continua com o binário a partir do qual foi iniciado. Em um Mac sem /usr/local/bin, o script cria a pasta.
5. Ela executa o ironflock com os argumentos passados depois de bash -s --. Sem argumentos, ela apenas instala e indica o próximo passo.

Em uma máquina Linux com CPU amd64, a saída é assim:

Download base: https://instance-registry.ironflock.com/dl
Downloading ironflock 2.0.2 (linux/amd64)...
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788).
Installed ironflock 2.0.2 as /usr/local/bin/ironflock.

Connect this machine to IronFlock with:
  sudo ironflock agent install -c /path/to/device.flock
All commands: ironflock --help
Tab completion in your shell: ironflock completion --help

Em um Mac, o próximo passo indicado é ironflock os flash, que grava o IronFlockOS para um dispositivo em um pen drive USB ou em um cartão SD. Quando a linha substitui um ironflock que já existia, a linha Installed termina com , in place of the one that was there.

Requisitos

• Root — o script escreve em /usr/local/bin. Execute-o com sudo bash.
• curl ou wget — para os downloads.
• No Linux, base64 e sqv ou gpgv — para a verificação da assinatura. O apt depende de um entre sqv e gpgv, então todo Debian e todo Ubuntu tem um deles. Sem nenhum dos dois, o script para e indica apt install gpgv.
• No macOS, nada que não venha com o sistema.

Um shell POSIX executa o script: bash, sh, dash ou BusyBox ash.

Assinatura ausente ou incorreta

Uma assinatura ausente ou incorreta interrompe o script antes que ele instale qualquer coisa, e um ironflock instalado antes permanece como estava. O script termina com o código de saída 1 e uma linha no stderr, por exemplo:

install.sh: https://instance-registry.ironflock.com/dl/cli/linux/amd64/2.0.2/ironflock is not signed by IronFlock: not installing it

Um download que falha interrompe o script da mesma forma: nada é instalado.

Instalar e executar um comando em uma linha

Os argumentos depois de bash -s -- vão para o ironflock assim que ele estiver instalado. Esta linha instala o ironflock e conecta a máquina ao IronFlock como o dispositivo do arquivo de configuração do dispositivo (.flock) device.flock:

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock

Em curl ... | bash, a entrada padrão do script é o próprio script. Por isso, o script deixa o ironflock ler do seu terminal, e as perguntas do comando continuam chegando até você, que as responde como de costume. Sem terminal (um script cloud-init, CI), o ironflock não recebe entrada: um comando que pergunta termina com o código de saída 4, a menos que você adicione --yes. O script termina com o código de saída do ironflock. ironflock agent install descreve o comando.

Atualização

O sudo ironflock self-update substitui o ironflock pela release mais nova, depois das mesmas verificações com a chave de release da IronFlock (ironflock self-update). O ironflock version --check mostra a versão que você tem e se há uma release mais nova (ironflock version).

A linha de instalação do início desta página também atualiza: execute-a novamente, e ela substitui /usr/local/bin/ironflock pela release atual.

Em um dispositivo IronFlockOS, o ironflock vem com o sistema, e o ironflock os update o atualiza junto com o sistema.

Verificar o script de instalação antes

Para verificar o próprio install.sh antes que ele rode como root, baixe-o com a assinatura, importe a chave de release e verifique a assinatura com o gpg:

curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

O gpg precisa informar uma assinatura válida da chave com a impressão digital F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Compare-a com a chave IronFlock Bootstrap em Chaves de Assinatura. Depois, execute o script verificado, sem argumentos ou com os argumentos para o ironflock:

sudo bash install.sh
sudo bash install.sh agent install -c device.flock

Base de download

O ironflock e o script de instalação baixam da nuvem IronFlock, https://instance-registry.ironflock.com/dl. Uma base de download diferente, como um espelho na sua rede, é indicada de uma de duas formas. Para um dispositivo de um appliance IronFlock, alguns comandos encontram sozinhos o espelho de downloads do appliance:

Abaixo da base de download, o script de instalação lê cli/version.txt e cli/<system>/<arch>/<version>/ironflock, cada um com a sua assinatura .asc e .sig. Ele os verifica com a chave de release que traz, seja qual for a base de download, de modo que um espelho serve os arquivos assinados da IronFlock sem alterações. O ironflock lê o catálogo e as imagens do IronFlockOS abaixo de ironflockos/, o agente do dispositivo abaixo de device-agent/ e, abaixo de cli/, a release mais nova (version.txt, para self-update e version --check) e os binários ironflock (para self-update e, com --host, os de outras plataformas).

Por padrão, o sudo não repassa as variáveis do seu shell. Defina a variável depois do sudo, ou use a flag:

# Instalar o ironflock a partir de um espelho
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# Conectar esta máquina com o agente do espelho
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

Dois comandos usam a base de download de outra forma. O agent update deixa o agente se atualizar a partir do seu próprio servidor de atualizações, o update_url do seu arquivo .flock, e a base de download não muda isso. O os update usa a flag, depois a variável, depois o update_url do arquivo .flock do agente. Com --host, a base de download vai junto para a outra máquina; uma base com credenciais (https://user:[email protected]/dl) termina com o código de saída 2 antes que qualquer máquina seja alcançada.

Dispositivos de um appliance IronFlock

O arquivo .flock emitido por um appliance IronFlock indica o espelho de downloads do appliance como servidor de atualizações do agente (update_url), por exemplo http://10.0.0.5:15002/dl, ou https://registry.<domain>/dl quando o appliance roda com um domínio. Quando nem --download-base nem IRONFLOCK_DL_BASE estão definidos, o agent install, o doctor e o os install obtêm os seus arquivos desse espelho, de modo que uma máquina que alcança o appliance, mas não o ironflock.com, pode ser conectada ou convertida. Um arquivo .flock da nuvem IronFlock indica um host da nuvem e usa a nuvem.

• O que o espelho não fornece vem do mesmo caminho abaixo da base de download da nuvem IronFlock, com um aviso: para o agent install, uma linha Warning: no stderr e uma entrada de warnings no resultado de --json; para o os install, um aviso no plano; para o doctor, um warning da verificação download_tree. O agent install e o os install só falham quando nem o espelho nem a nuvem fornecem um arquivo, e o erro então indica os dois.
• O agent install e o os install alcançam o espelho diretamente, e a nuvem pelo proxy, quando há um.
• Um espelho HTTPS com um certificado da CA própria do appliance só funciona onde o sistema da máquina confia nessa CA.

Alguns downloads continuam vindo de outro lugar:

• O install.sh e o binário ironflock vêm do ironflock.com. Com --host, o binário vai do seu computador para a máquina (Máquinas remotas via SSH).
• O agent install obtém os pacotes da distribuição e o Docker dos seus próprios servidores.
• O self-update e o version --check leem a flag, depois a variável, senão a nuvem IronFlock, e não o espelho do appliance.

Depois da instalação, o agente recebe as atualizações do appliance. Veja Dispositivos de borda.

Preenchimento automático com Tab

O ironflock completion imprime o script que permite ao seu shell completar linhas de comando do ironflock quando você pressiona Tab.

ironflock completion <shell>

O shell é bash, zsh ou fish. Roda no Linux e no macOS. Sem root. Não pergunta nada. O comando não tem flags próprias; valem as flags globais.

Execute a linha do seu shell para ter o preenchimento automático no shell em que você digita. Adicione a linha ao arquivo da terceira coluna para tê-lo em todo shell novo:

O script completa:

• os comandos e as suas flags;
• os valores das flags que aceitam um entre poucos valores: --channel, --variant e --kernel de os images, --channel de os update e --installer-confirm, --installer-after e --installer-allow-usb de os flash;
• um arquivo .flock para -c;
• os nomes de arquivo do shell para --hosts, --proxy-password-file, --wifi-password-file, --image-file, --output, --drive e --disk.

Outras flags e os argumentos de outros comandos não completam nada. Para completar, o script pergunta ao ironflock quais palavras cabem, e o ironflock responde a partir da sua própria lista de comandos: completar não executa nenhum comando, não lista nenhuma unidade, não baixa nada e não alcança nenhuma outra máquina, também quando a linha contém --host. Com --host ou --hosts, o ironflock completion é respondido nesta máquina, como o --help.

# Completar no bash em que você digita
eval "$(ironflock completion bash)"
 
# Completar em todo bash novo
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

$ eval "$(ironflock completion bash)"
$ ironflock os images --kernel <Tab>
rt   std

Com --json, o resultado é o script em um objeto JSON:

{"shell":"bash","script":"..."}

Um shell ausente ou desconhecido, ou mais de um, é uma linha de comando incorreta: código de saída 2, e o erro indica os shells aceitos.

ironflock version

Imprime a versão do binário ironflock e a plataforma para a qual ele foi compilado. Com --check, também pergunta ao servidor de download se há uma release mais nova.

ironflock version [flags]

Roda no Linux e no macOS. Sem root. Não pergunta nada. Valem as flags globais.

# A versão do ironflock nesta máquina
ironflock version
 
# O mesmo em JSON
ironflock version --json
 
# O binário que roda em outra máquina via SSH: mesma versão, plataforma daquela máquina
ironflock --host pi@device-17 version
 
# Há uma release mais nova?
ironflock version --check

ironflock 2.0.2 linux/amd64

{"version":"2.0.2","os":"linux","arch":"amd64"}

Com --host, a plataforma é a da outra máquina, por exemplo ironflock 2.0.2 linux/arm64: a outra máquina executa um binário da mesma versão para a sua própria plataforma.

Um build de desenvolvimento indica o seu commit: 2.0.0-23-g5b38681 é o build do commit 5b38681, 23 commits depois da release 2.0.0.

Há uma release mais nova?

O --check lê o cli/version.txt da base de download (--download-base, senão IRONFLOCK_DL_BASE, senão a nuvem IronFlock) e o verifica com a sua assinatura (.asc), usando a chave de release da IronFlock que o binário traz. Ele pergunta pelo proxy que o agent configure definiu (/etc/ironflock/proxy.env), senão pelo proxy do ambiente. Só o root lê esse arquivo, então, sem root, ele usa o do ambiente. O version --check e o self-update são os únicos comandos que perguntam pela release mais nova; nenhum comando faz isso por conta própria.

Uma segunda linha no stdout diz o que ele encontrou, e o que instala uma release mais nova: o self-update ou, no IronFlockOS, o os update.

$ ironflock version --check
ironflock 2.0.3 linux/amd64
ironflock 2.1.0 is out at https://instance-registry.ironflock.com/dl. 'sudo ironflock self-update' installs it.

Quando o version.txt indica a versão deste binário, a segunda linha é This is the newest release. Quando este binário é mais novo, um build de desenvolvimento posterior à release, a linha diz isso. Um build de desenvolvimento x.y.z-N-g<commit> conta como mais novo que a release x.y.z e mais antigo que a próxima; com N = 0, ele equivale a x.y.z, e a linha diz que não há release mais nova.

Com --json, o objeto tem mais dois campos: latest_version, o que o version.txt indica, e newer, se essa versão é mais nova que este binário.

{"version":"2.0.3","os":"linux","arch":"amd64","latest_version":"2.1.0","newer":true}

O código de saída é 0 haja ou não uma release mais nova. É 1 quando o servidor não responde, não tem version.txt, ou tem um que não está assinado pela chave. Com --host, a primeira linha indica o binário deste build, como no version, e a outra máquina pergunta ao servidor.

ironflock self-update

Substitui o binário ironflock em execução pela release mais nova, ou pela release que --version indica, também uma mais antiga. A release é verificada com a chave de release da IronFlock antes que qualquer coisa no disco mude.

ironflock self-update [flags]

Roda em: Linux e macOS; não no IronFlockOS. Root: necessário para /usr/local/bin/ironflock (Quem pode substituir o binário). Pergunta: sim, depois de dizer qual release substitui qual; --yes responde.

# Atualizar o ironflock para a release mais nova; o comando pergunta antes
sudo ironflock self-update
 
# Atualizar sem pergunta e ler o resultado como JSON
sudo ironflock self-update --yes --json
 
# Voltar para uma release mais antiga
sudo ironflock self-update --version 2.0.3
 
# Atualizar o ironflock instalado em outra máquina
ironflock --host pi@device-17 self-update --yes

O que ele substitui, e pelo quê

• O arquivo. O binário em execução, com todo link simbólico resolvido: o arquivo para o qual um link aponta é substituído, e o link permanece. O comando indica o arquivo antes de qualquer outra coisa. A pasta /opt/ironflock/device-init da instalação de um agente guarda o registro dessa instalação, nenhum ironflock, e o comando não a toca.
• A release. Sem --version, a mais nova: o que o cli/version.txt da base de download indica (--download-base, senão IRONFLOCK_DL_BASE, senão a nuvem IronFlock), o arquivo que a linha de instalação lê. O binário de uma release é cli/<system>/<arch>/<version>/ironflock. Não há canais: outra árvore é outra base de download, como um espelho.
• O proxy. Os downloads passam pelo proxy que o agent configure definiu (/etc/ironflock/proxy.env), senão por HTTP_PROXY, HTTPS_PROXY e NO_PROXY do ambiente. O sudo e um comando com --host não têm proxy no seu ambiente. O arquivo pertence ao root, então uma execução sem root usa o proxy do ambiente e diz isso. O comando diz quando usa o do arquivo.
• Nada a fazer. Quando o binário já é essa release, ou é mais novo que ela (um build de desenvolvimento posterior), o comando diz isso e termina com o código de saída 0, sem pergunta e sem download; o outcome do resultado é current. Sem --version, ele nunca volta para uma release mais antiga.

As verificações

Antes que o binário seja substituído:

1. O version.txt é verificado com a sua assinatura pela chave de release da IronFlock que o binário em execução traz.
2. O novo binário é verificado com a sua assinatura pela mesma chave, e com as suas informações de build: o programa ironflock, para esta plataforma, a partir de uma árvore de código-fonte sem modificações.
3. Ele é gravado ao lado do antigo, na mesma pasta, com o modo, o dono e o grupo do antigo, e executado uma vez (version --json). Ele precisa dizer que é a release pedida, nesta plataforma. Uma assinatura não vincula nenhuma versão, então um binário assinado mais antigo, servido no lugar do mais novo, é recusado aqui.
4. Só então ele é renomeado por cima do antigo, em um único passo.

Nenhum sqv ou gpgv é necessário: o próprio ironflock verifica as assinaturas.

Um arquivo que não passa em uma verificação nunca substitui o binário, e o novo arquivo ao lado dele é removido de novo. Uma execução que falha, é recusada ou é interrompida deixa o binário antigo como estava. Um comando do ironflock que roda enquanto o arquivo é substituído continua com o arquivo a partir do qual começou. Um segundo Ctrl-C, ou uma queda de energia, entre a gravação e a renomeação pode deixar o novo arquivo (.ironflock.new-* ao lado do binário) para trás; remova-o manualmente.

Quem pode substituir o binário

O comando precisa de acesso de escrita à pasta do binário e precisa rodar como o dono do binário e membro do seu grupo, ou como root, para que o novo arquivo mantenha o dono e o grupo. Para /usr/local/bin/ironflock, onde a linha de instalação o coloca, isso é root. Caso contrário, o comando termina com o código de saída 3 antes de baixar qualquer coisa, indica o dono ou o grupo e indica a linha de comando com sudo.

IronFlockOS e outras máquinas

• O IronFlockOS traz o ironflock junto com o seu sistema, e cada atualização do sistema operacional substitui o sistema por inteiro. Ali, o comando termina com o código de saída 3 antes de examinar qualquer coisa e indica o os update. No pen drive de instalação do IronFlockOS, ele recusa como os comandos agent.
• Com --host, o binário em execução é a cópia da execução, que é removida quando o comando termina. Por isso, o comando atualiza em vez disso o /usr/local/bin/ironflock da máquina. Sem esse arquivo, ele termina com o código de saída 3 e indica a linha de instalação. Um ironflock instalado que não roda, ou que não informa a sua versão, também o encerra com o código de saída 3, antes de qualquer download: a linha de instalação instala o ironflock de novo.
• Em várias máquinas (--host mais de uma vez, --hosts), com --yes, cada máquina atualiza o seu /usr/local/bin/ironflock.

Resultado

$ sudo ironflock self-update
This ironflock is 2.0.3, at /usr/local/bin/ironflock.
Download base: https://instance-registry.ironflock.com/dl (from default)
The downloads go through the proxy of the install's record (/etc/ironflock/proxy.env).
The newest release at https://instance-registry.ironflock.com/dl is ironflock 2.1.0 (its version.txt is signed by key F6C94D96CE315377ACA7C8EA4990543373212788).
ironflock 2.1.0 replaces 2.0.3 at /usr/local/bin/ironflock.
A command of ironflock that runs now goes on with 2.0.3; the next one runs 2.1.0.
? Install ironflock 2.1.0? Yes
Downloading ironflock 2.1.0 for linux/amd64 from https://instance-registry.ironflock.com/dl.
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788): the program ironflock for linux/amd64.
The new file says it is ironflock 2.1.0 linux/amd64; it is in place.
ironflock at /usr/local/bin/ironflock is updated from 2.0.3 to 2.1.0.

O binário é baixado depois da resposta. Sem terminal, ou com --json, o comando precisa de --yes. Com --json, para um binário que já é a release mais nova:

{"outcome":"current","path":"/usr/local/bin/ironflock","version":"2.1.0","latest_version":"2.1.0"}

Códigos de saída