Códigos de saída do systemctl: is-active, is-enabled, is-failed e o que significa o código LSB 3

O que é

O systemctl mistura duas convenções diferentes de código de saída, conforme o subcomando:

Subcomando	0 significa	não zero significa
is-active PATTERN	pelo menos uma unit correspondente está ativa	nenhuma está ativa: 3 se inativa, 4 se desconhecida (imprime o estado, a menos que se use --quiet)
is-failed PATTERN	pelo menos uma unit correspondente está no estado "failed"	nenhuma falhou (1; 4 se desconhecida)
is-enabled UNIT	habilitada, ou "static", "indirect", "generated", "alias"	por exemplo "linked", "masked", "disabled"; "not-found" resulta em 4
status [PATTERN|PID]	a unit está ativa	segue a tabela LSB mais antiga abaixo

Para systemctl status (e outras verificações no estilo LSB), o manual do systemctl afirma que ele "uses the return codes defined by LSB, as defined in LSB 3.0.0" (usa os códigos de retorno definidos pela LSB, conforme a LSB 3.0.0):

Valor	Significado na LSB	Uso no systemd
0	o programa está em execução / serviço OK	a unit está ativa
1	o programa está morto, existe um arquivo de PID em /var/run	a unit não falhou (usado por is-failed)
2	o programa está morto, existe um arquivo de lock em /var/lock	não utilizado
3	o programa não está em execução	a unit não está ativa
4	o estado do programa ou serviço é desconhecido	a unit não existe

O manual acrescenta um aviso explícito: "The mapping of LSB service states to systemd unit states is imperfect, so it is better to not rely on those return values but to look for specific unit states and substates instead." (O mapeamento dos estados de serviço LSB para os estados de unit do systemd é imperfeito; por isso é melhor não depender desses valores de retorno e consultar estados e subestados específicos da unit.)

Por que importa

O código LSB 3 ("not running") não é um erro de execução: é o systemctl informando, com sucesso, que o serviço simplesmente está parado, um estado perfeitamente válido e comum (uma unit oneshot, um serviço desabilitado, uma unit parada de propósito para manutenção). Tratar qualquer saída não zero do systemctl como "a chamada ao systemctl falhou" gera alarmes para uma resposta rotineira do tipo "está apenas desligado".

Como aplicar

• Use is-active/is-failed/is-enabled em verificações automatizadas em vez de analisar a saída de status: cada um tem um significado documentado e restrito para 0 e não zero.
• Use --quiet com is-active/is-enabled/is-failed para suprimir o estado impresso e depender apenas do código de saída nos scripts.
• Quando precisar da tabela LSB (por exemplo, a partir de um wrapper de script init antigo), lembre-se de que 3 significa não ativa, o que inclui uma unit failed; por isso, use is-failed para distinguir parada de travada. Já 4 significa que o systemd não conhece essa unit (erro de digitação, arquivo de unit ausente).
• Prefira systemctl show -p ActiveState,SubState <unit> para qualquer coisa além de uma verificação booleana simples, de acordo com a recomendação do manual.

Armadilhas

• Presumir que o não zero de is-active é sempre 1: o systemd atual (por exemplo, 255) retorna 3 para uma unit inativa e 4 para uma desconhecida, enquanto is-failed retorna 1 para "não falhou".
• Disparar alertas para qualquer valor não zero de systemctl status <unit> em um script de monitoramento sem verificar se o valor é simplesmente 3 (parada).