Tutorial do Debian 13 / Gerenciar serviços systemd e aplicar configurações drop-in

No Debian 13, active indica o estado atual de ativação de um serviço systemd, e enabled mostra se ele está habilitado para iniciar na inicialização. Se você modificou o arquivo de unidade ou um drop-in, use daemon-reload para fazer o gerenciador systemd reler as definições de unidade, e quaisquer comandos de execução alterados devem ser seguidos por uma reinicialização do serviço e verificação da resposta real.

Distinga o estado de execução da configuração de inicialização

O systemd gerencia tarefas como serviços, timers e mounts como unidades. Este tutorial cria um serviço HTTP Python apenas com loopback em um sistema Debian 13 com systemd 257, exibindo seu status e comparando processos, portas e respostas. É uma prática para manipular serviços gerais do sistema e não implica reiniciar todos os serviços existentes da mesma forma.

Comandos Alvo a ser alterado Resultado dessa prática
start / stop Serviço atualmente em execução Iniciar ou parar o serviço sem alterar seus links de inicialização
enable / disable Links de inicialização da unidade Adicionar ou remover links de inicialização sem interromper um processo em execução
enable --now Configuração de inicialização e estado de execução Habilitar links de inicialização e também iniciar o serviço agora
daemon-reload Configurações da unidade lidas pelo systemd Reler definições de unidade sem substituir o processo HTTP
restart Processo do serviço Aplicar novo comando de execução parando e iniciando

Mesmo que enabled, o serviço pode falhar, e mesmo que disabled, ele pode ser iniciado manualmente ou executado a pedido de outra unidade. A seção [Install] contém WantedBy=multi-user.target: enable usa essa informação para criar os links que associam o serviço à inicialização desse target. A seção não é, por si só, um target. Existem serviços que são unidades estáticas sem conexões de instalação ou que iniciam via sockets, então não determine o comportamento de inicialização de todos os serviços com base apenas em se eles estão habilitados. Os significados detalhados dos comandos podem ser encontrados no manual systemctl do Debian 13.

Verifique o estado inicial do laboratório dedicado

Use a conta lfstudent com privilégios sudo, Python 3 e curl. Se for uma conta diferente, ajuste o User do serviço abaixo e o caminho do documento para corresponder à conta real. O servidor HTTP Python é apenas para fins de prática e não precisa ser exposto ao host ou à LAN, então ele escuta apenas em 127.0.0.1. Não são necessários encaminhamentos NAT ou alterações de firewall.

id lfstudent
python3 --version
curl --version
systemctl --version
systemctl show lf-http17.service -p LoadState
sudo ss -lntp 'sport = :8080'
sudo ss -lntp 'sport = :8082'
ls -ld /home/lfstudent/lf-http17 /etc/systemd/system/lf-http17.service.d

O serviço é LoadState=not-found, nenhuma das portas possui uma linha de escuta, e a pasta não existe como condição inicial. O erro de arquivo ausente no último ls é esperado para confirmar que o caminho ainda não existe. Se algum recurso de laboratório já existir, pare aqui e identifique seu proprietário. Não substitua nem interrompa outro serviço. Se o Python ou o curl não estiverem instalados, revise a lista de alterações em sudo apt install --no-install-recommends python3 curl para instalá-los.

Crie o diretório e o arquivo dedicados em um terminal conectado como lfstudent.

mkdir /home/lfstudent/lf-http17 &&
printf 'systemd-service-lab\n' > /home/lfstudent/lf-http17/probe.txt

Se a criação do diretório falhar, o comando printf encadeado será ignorado. Pare o laboratório nesse ponto em vez de continuar com o arquivo de serviço. O servidor oferece somente o diretório de documentos dedicado ao laboratório, e não todo o diretório pessoal do usuário. O serviço do sistema geralmente é gerenciado pelo administrador do sistema, mas o processo HTTP em si é executado com permissões de usuário comum conforme mostrado abaixo em User=lfstudent.

Escreva e valide a unidade completa de serviço

Abra um novo arquivo com sudo nano /etc/systemd/system/lf-http17.service e salve todo o conteúdo abaixo. Você pode usar outro editor, mas mantenha o nome do arquivo, o caminho e a estrutura de linhas. Não sobrescreva um arquivo existente com um novo exemplo.

[Unit]
Description=Local HTTP service for lesson 17

[Service]
Type=exec
User=lfstudent
ExecStart=/usr/bin/python3 -m http.server 8080 --bind 127.0.0.1 --directory /home/lfstudent/lf-http17
Restart=on-failure
RestartSec=2s

[Install]
WantedBy=multi-user.target

Type=exec ajuda a verificar erros na etapa de início do executável. No entanto, a inicialização bem-sucedida do executável não garante que o listener HTTP esteja pronto. Restart=on-failure é uma configuração para reiniciar em caso de término anormal, e não é uma opção para reviver um serviço que o administrador parou normalmente.

Não anexe & para execução em segundo plano em ExecStart. O systemd gerencia diretamente o processo executando-o em primeiro plano. Diferente de uma linha de comando shell normal, pipes e redirecionamentos não são automaticamente tratados como sintaxe de shell. Consulte a opção relevante na documentação systemd.service para métodos de execução.

sudo systemd-analyze verify /etc/systemd/system/lf-http17.service
sudo systemctl daemon-reload
systemctl is-enabled lf-http17.service
systemctl is-active lf-http17.service
systemctl cat lf-http17.service

Verifique a causa se houver erros ou avisos de inspeção. Mesmo após a validação e a releitura sem erros, o serviço ainda não foi iniciado: os estados esperados são disabled e inactive. Essas duas consultas retornam códigos de saída diferentes de zero dependendo do status, portanto, não trate simplesmente todas as saídas anormais como falhas de instalação na automação.

Observe active e enabled separadamente

Primeiro, inicie o serviço manualmente e verifique a resposta real do arquivo.

sudo systemctl start lf-http17.service
systemctl is-active lf-http17.service
systemctl is-enabled lf-http17.service
curl --noproxy '*' --retry 5 --retry-connrefused --retry-delay 1 --max-time 10 -fsS http://127.0.0.1:8080/probe.txt
sudo ss -lntp 'sport = :8080'

Espere active e disabled nas consultas de estado, e systemd-service-lab na solicitação HTTP. As tentativas limitadas no curl levam em consideração a pequena diferença de tempo para a porta estar pronta imediatamente após o início do processo. Se continuar falhando, não confie apenas no status e verifique a causa com sudo journalctl -u lf-http17.service -b --no-pager -n 30.

Ative o link de inicialização e, em seguida, pare o processo atual.

sudo systemctl enable lf-http17.service
sudo systemctl stop lf-http17.service
systemctl is-enabled lf-http17.service
systemctl is-active lf-http17.service

Os estados esperados são enabled e inactive. Parar não remove o link de inicialização na inicialização. Inicie o serviço novamente e, em seguida, desative seu link de inicialização.

sudo systemctl start lf-http17.service
sudo systemctl disable lf-http17.service
systemctl is-enabled lf-http17.service
systemctl is-active lf-http17.service
curl --noproxy '*' --retry 5 --retry-connrefused --retry-delay 1 --max-time 10 -fsS http://127.0.0.1:8080/probe.txt

Os estados esperados são disabled e active, com a mesma resposta HTTP do arquivo. Neste exemplo, desativar não parou o processo HTTP em execução. Se a parada imediata for desejada, use disable --now. Nesta comparação, mantenha o serviço active e disabled para a alteração de porta subsequente.

Altere a porta com um drop-in

Um drop-in é uma configuração suplementar adicionada à pasta unit-name.d/ ao lado do arquivo de unidade original. Em vez de modificar diretamente o arquivo /usr/lib/systemd/system/ fornecido pelo pacote, os administradores geralmente gerenciam as alterações como um drop-in de /etc/systemd/system/. Este exemplo aplica o mesmo método a uma unidade criada manualmente para distinguir entre os arquivos originais e suplementares.

systemctl show lf-http17.service -p MainPID -p ExecStart -p FragmentPath -p DropInPaths
sudo install -d /etc/systemd/system/lf-http17.service.d

Registre o MainPID atual, isto é, o identificador do processo principal acompanhado pelo systemd, para compará-lo após as alterações. Crie o drop-in com sudo nano /etc/systemd/system/lf-http17.service.d/20-port.conf.

[Service]
ExecStart=
ExecStart=/usr/bin/python3 -m http.server 8082 --bind 127.0.0.1 --directory /home/lfstudent/lf-http17

Um ExecStart= vazio serve para redefinir o comando de execução previamente definido e substituí-lo na linha seguinte. Se um segundo comando de execução for adicionado sem redefinir, a substituição pretendida neste tipo de serviço não ocorrerá. Drop-ins mesclam ou substituem de forma diferente dependendo da opção, portanto, nem todas as configurações são tratadas da mesma maneira. O caminho de pesquisa de configuração e a descrição do drop-in do systemd.unit são a referência.

sudo systemd-analyze verify /etc/systemd/system/lf-http17.service
sudo systemctl daemon-reload
systemctl cat lf-http17.service
systemctl show lf-http17.service -p MainPID -p ExecStart -p DropInPaths
curl --noproxy '*' --max-time 5 -fsS http://127.0.0.1:8080/probe.txt
curl --noproxy '*' --max-time 3 -fsS http://127.0.0.1:8082/probe.txt

Embora o gerenciador agora mostre 8082 em ExecStart, o MainPID do processo em execução é o valor anterior, e as respostas da porta 8080 continuam. Espera-se que as solicitações para 8082 falhem porque nada está ouvindo lá ainda. Esta é a comparação de que o daemon-reload relê a definição da unidade e é diferente de reiniciar o processo.

sudo systemctl restart lf-http17.service
systemctl show lf-http17.service -p MainPID -p ActiveState -p SubState -p UnitFileState
sudo ss -lntp 'sport = :8082'
curl --noproxy '*' --retry 5 --retry-connrefused --retry-delay 1 --max-time 10 -fsS http://127.0.0.1:8082/probe.txt
curl --noproxy '*' --max-time 3 -fsS http://127.0.0.1:8080/probe.txt

Verifique o PID do processo reiniciado e verifique o listener na porta 8082 e o arquivo de resposta, e compare se o listener anterior na porta 8080 desapareceu. O número do PID varia dependendo do ambiente, e é mais importante verificar o status, o listener e a resposta juntos do que o número em si. O comando reload é uma ação separada de daemon-reload e restart. A unidade deste laboratório não define ExecReload nem outro mecanismo de recarga compatível; use restart para substituir seu processo. A releitura de uma configuração interna de outro aplicativo depende dos mecanismos oferecidos por esse aplicativo.

Remova apenas o drop-in do laboratório e restaure a porta 8080

Mantenha o arquivo de serviço original e exclua apenas o 20-port.conf criado desta vez. Não use uma reversão completa nesta operação, o que poderia apagar outras configurações suplementares.

sudo rm -- /etc/systemd/system/lf-http17.service.d/20-port.conf
sudo rmdir -- /etc/systemd/system/lf-http17.service.d
sudo systemctl daemon-reload
sudo systemctl restart lf-http17.service
systemctl show lf-http17.service -p ExecStart -p DropInPaths
curl --noproxy '*' --retry 5 --retry-connrefused --retry-delay 1 --max-time 10 -fsS http://127.0.0.1:8080/probe.txt
sudo journalctl -u lf-http17.service -b --no-pager -n 20

A restauração é confirmada quando DropInPaths está vazio, ExecStart novamente especifica a porta 8080 e a requisição HTTP retorna o arquivo original. Se rmdir falhar porque não está vazio, primeiro verifique se há outros arquivos e não exclua toda a pasta. O log mantém rastros de início, parada e requisições, permitindo verificar as transições de estado.

Diagnostique erros e remova o serviço dedicado

Erros de digitação no caminho do arquivo ou problemas de permissão de acesso podem se manifestar como falhas nas requisições HTTP ou falhas na inicialização do serviço. Conflitos de porta podem ser verificados com ss para ver se outro servidor está ouvindo. Leia os resultados de systemctl status lf-http17.service --no-pager e os erros específicos no journal e corrija-os. Executar apenas reset-failed para limpar registros de falha não resolve a causa subjacente.

Após terminar a prática, pare apenas o serviço dedicado, desative a inicialização automática e então remova os arquivos criados.

sudo systemctl disable --now lf-http17.service
sudo rm -- /etc/systemd/system/lf-http17.service
sudo systemctl daemon-reload
rm -- /home/lfstudent/lf-http17/probe.txt
rmdir -- /home/lfstudent/lf-http17
systemctl show lf-http17.service -p LoadState
sudo ss -lntp 'sport = :8080'
sudo ss -lntp 'sport = :8082'

Verifique se a unidade não foi encontrada e se nenhuma das portas do laboratório possui uma linha de escuta. Se o serviço permanecer em estado de falha, primeiro confirme a remoção dos arquivos e a finalização do processo, então limpe apenas os registros de falha dessa unidade com o sudo systemctl reset-failed lf-http17.service. Mantenha outros registros de serviço e sistema.