Como Escrever e Gerenciar Arquivos de Unidade Systemd Personalizados de Forma Eficaz

Arquivos de unidade systemd personalizados transformam um comando que funciona no seu terminal em um serviço que o sistema operacional pode iniciar, parar, reiniciar, registrar e supervisionar. A diferença é importante. Um comando em um shell herda seu ambiente e morre quando a sessão termina. Um serviço tem um usuário explícito, diretório de trabalho, política de reinicialização, dependências, limites de recursos e logs.

Este é o caminho prático que uso para pequenas APIs internas, workers, scripts sidecar e daemons pontuais: escreva a unidade correta mais simples, execute-a como um usuário dedicado, deixe os logs irem para o journal e adicione diretivas avançadas apenas quando um requisito real aparecer.

Entendendo os Arquivos de Unidade Systemd

O Systemd gerencia vários recursos do sistema, conhecidos como unidades, que são definidos por arquivos de configuração. Essas unidades incluem serviços (.service), pontos de montagem (.mount), dispositivos (.device), sockets (.socket) e mais. Para gerenciar aplicativos e processos em segundo plano, o tipo de unidade .service é o mais comum e relevante.

Os arquivos de unidade systemd são arquivos de texto simples normalmente armazenados em diretórios específicos. Os locais primários, em ordem de precedência, são:

/etc/systemd/system/: Este é o local recomendado para arquivos de unidade personalizados e substituições, pois eles têm precedência sobre os padrões do sistema e persistem nas atualizações do sistema.
/run/systemd/system/: Usado para arquivos de unidade gerados em tempo de execução.
/usr/lib/systemd/system/: Contém arquivos de unidade fornecidos por pacotes instalados. Não modifique arquivos neste diretório diretamente.

Ao colocar seus arquivos de unidade personalizados em /etc/systemd/system/, você garante que eles sejam reconhecidos e gerenciados corretamente pelo systemd.

Anatomia de um Arquivo de Unidade `.service`

Um arquivo de unidade .service do systemd é estruturado em várias seções, cada uma denotada por [NomeDaSeção], contendo várias diretivas (pares chave-valor). As três seções principais para uma unidade de serviço são [Unit], [Service] e [Install].

Vamos detalhar as diretivas mais cruciais que você usará:

Seção [Unit]

Esta seção contém opções genéricas sobre a unidade, sua descrição e dependências.

Description: Uma string legível por humanos descrevendo o serviço. Isso aparece na saída de systemctl status.
```
Description=Minha Aplicação Web Python Personalizada
```
Documentation: Uma URL apontando para a documentação do serviço (opcional).
```
Documentation=https://exemplo.com/docs/minha-app
```
After: Especifica que esta unidade deve iniciar após as unidades listadas. Isso ajuda a gerenciar a ordem de inicialização. Para aplicações web, você pode querer garantir que a rede esteja ativa.
```
After=network.target
```
Requires: Uma dependência forte. Se a unidade requerida falhar ao iniciar, esta unidade não iniciará. Se a unidade requerida for parada, esta unidade também pode ser parada.
```
Requires=docker.service
```
Wants: Uma dependência mais fraca. Se a unidade desejada falhar ou não for encontrada, esta unidade ainda tenta iniciar. Este é geralmente um padrão melhor do que Requires.
```
Wants=syslog.target
```

Seção [Service]

Esta seção define os parâmetros de execução para o seu serviço, incluindo como ele inicia, para e se comporta.

Type: Define o tipo de inicialização do processo. Crítico para como o systemd monitora seu serviço.
- simple (padrão): O comando ExecStart é o processo principal do serviço. O systemd considera o serviço iniciado imediatamente após ExecStart ser invocado. Ele espera que o processo seja executado indefinidamente em primeiro plano.
- forking: O comando ExecStart bifurca um processo filho e o pai sai. O systemd considera o serviço iniciado assim que o processo pai sai. Use isso se seu aplicativo se daemonizar.
- oneshot: O comando ExecStart é um processo único que termina quando termina. Útil para scripts que executam uma tarefa e terminam (por exemplo, um script de backup).
- notify: Semelhante a simple, mas o serviço informa ao systemd quando está pronto. Isso requer suporte do aplicativo para notificações do systemd.
- idle: O comando ExecStart é executado apenas quando todos os jobs são concluídos, atrasando a execução até que o sistema esteja quase ocioso.
```
Type=simple
```
ExecStart: O comando a ser executado quando o serviço iniciar. Esta é a diretiva mais importante nesta seção. Sempre use o caminho absoluto para seu executável ou script.
```
ExecStart=/usr/bin/python3 /opt/minha_app/app.py
```
ExecStop: O comando a ser executado quando o serviço for parado (opcional). Se não especificado, o systemd envia SIGTERM para os processos.
```
ExecStop=/usr/bin/pkill -f 'minha_app/app.py'
```
ExecReload: O comando a ser executado para recarregar a configuração do serviço (opcional).
```
ExecReload=/bin/kill -HUP $MAINPID
```
User: A conta de usuário sob a qual os processos do serviço serão executados. Essencial para segurança; evite root a menos que absolutamente necessário.
```
User=meuusuarioapp
```
Group: A conta de grupo sob a qual os processos do serviço serão executados.
```
Group=meugrupoapp
```
WorkingDirectory: O diretório de trabalho para os comandos executados.
```
WorkingDirectory=/opt/minha_app
```
Restart: Define quando o serviço deve ser reiniciado automaticamente.
- no (padrão): Nunca reiniciar.
- on-success: Reiniciar apenas se o serviço terminar de forma limpa.
- on-failure: Reiniciar apenas se o serviço terminar com um código de status diferente de zero ou for morto por um sinal.
- always: Sempre reiniciar o serviço, independentemente do status de saída.
```
Restart=on-failure
```
RestartSec: Quanto tempo esperar antes de reiniciar o serviço (por exemplo, 5s para 5 segundos).
```
RestartSec=5s
```
Environment: Define variáveis de ambiente para os comandos executados.
```
Environment="APP_ENV=producao" "DEBUG=false"
```
EnvironmentFile: Lê variáveis de ambiente de um arquivo. Cada linha deve ser CHAVE=VALOR.
```
EnvironmentFile=/etc/default/minha_app
```
LimitNOFILE: Define o número máximo de descritores de arquivo abertos permitidos para o serviço (por exemplo, 100000). Importante para aplicações de alta concorrência.
```
LimitNOFILE=65536
```

Seção [Install]

Esta seção define como o serviço é habilitado para iniciar automaticamente na inicialização.

WantedBy: Especifica a unidade alvo que "deseja" este serviço. Quando a unidade alvo é habilitada, este serviço será vinculado simbolicamente em seu diretório .wants, efetivamente fazendo com que ele inicie com o alvo.
- multi-user.target: O alvo padrão para a maioria dos serviços de servidor, indicando um sistema com logins multiusuário não gráficos.
- graphical.target: Para serviços que exigem um ambiente gráfico.
```
WantedBy=multi-user.target
```
RequiredBy: Semelhante a WantedBy, mas uma dependência mais forte. Se o alvo for habilitado, esta unidade também é habilitada, e se esta unidade falhar, o alvo também falhará.

Para a maioria dos serviços personalizados destinados a serem executados em segundo plano em um servidor, Type=simple e WantedBy=multi-user.target são o ponto de partida certo. Se o aplicativo já se daemoniza, desabilite esse comportamento ou use Type=forking com cuidado. Um processo em primeiro plano é mais fácil para o systemd supervisionar.

Passo a Passo: Criando e Gerenciando um Serviço Systemd Personalizado

Vamos criar um exemplo prático: um servidor HTTP Python simples que serve arquivos de um diretório especificado. Vamos configurá-lo como um serviço systemd.

Passo 1: Prepare seu Aplicativo/Script

Primeiro, crie o script do aplicativo. Para este exemplo, usaremos um servidor HTTP Python simples. Crie um diretório para seu aplicativo, por exemplo, /opt/minha_app, e coloque app.py dentro dele.

# /opt/minha_app/app.py

import http.server
import socketserver
import os

PORT = int(os.environ.get("PORT", 8000))
DIRECTORY = os.environ.get("DIRECTORY", os.getcwd())

class Handler(http.server.SimpleHTTPRequestHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory=DIRECTORY, **kwargs)

print(f"Servindo diretório {DIRECTORY} na porta {PORT}")

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("Servidor iniciado.")
    httpd.serve_forever()

Crie o diretório e o arquivo:

sudo mkdir -p /opt/minha_app
sudo nano /opt/minha_app/app.py

(Cole o código Python)

Certifique-se de que o script seja executável (opcional para o comando python3, mas boa prática):

sudo chmod +x /opt/minha_app/app.py

Considere criar um usuário dedicado para seu serviço por razões de segurança:

sudo useradd --system --no-create-home meuusuarioapp

Defina a propriedade apropriada para seu diretório de aplicativo:

sudo chown -R meuusuarioapp:meuusuarioapp /opt/minha_app

Passo 2: Crie o Arquivo de Unidade

Agora, crie o arquivo de unidade systemd para nosso aplicativo Python. Vamos nomeá-lo minha_app.service.

sudo nano /etc/systemd/system/minha_app.service

Cole o seguinte conteúdo:

# /etc/systemd/system/minha_app.service

[Unit]
Description=Meu Servidor HTTP Python Personalizado
Documentation=https://github.com/exemplo/minha_app
After=network.target

[Service]
Type=simple
User=meuusuarioapp
Group=meuusuarioapp
WorkingDirectory=/opt/minha_app
Environment="PORT=8080" "DIRECTORY=/var/www/html"
ExecStart=/usr/bin/python3 /opt/minha_app/app.py
Restart=on-failure
RestartSec=10s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Nota: Definimos StandardOutput=journal e StandardError=journal para direcionar a saída do serviço para o journal do systemd, facilitando a visualização de logs com journalctl.

Se seu aplicativo precisar de segredos, evite colocá-los diretamente no arquivo de unidade. Use um arquivo de ambiente com permissões restritivas, um gerenciador de segredos ou suporte a credenciais específico da distribuição. Os arquivos de unidade geralmente são legíveis por mais pessoas do que você espera.

Passo 3: Coloque o Arquivo de Unidade

Conforme instruído, colocamos o arquivo de unidade em /etc/systemd/system/. Este é o local onde os arquivos de unidade personalizados devem residir.

Passo 4: Recarregue o Daemon Systemd

Após criar ou modificar um arquivo de unidade, o systemd precisa ser informado das alterações. Isso é feito recarregando o daemon systemd:

sudo systemctl daemon-reload

Passo 5: Inicie o Serviço

Agora você pode iniciar seu serviço:

sudo systemctl start minha_app.service

Passo 6: Verifique o Status do Serviço e Logs

Verifique se seu serviço está sendo executado corretamente:

systemctl status minha_app.service

Exemplo de saída (truncada):

● minha_app.service - Meu Servidor HTTP Python Personalizado
     Loaded: loaded (/etc/systemd/system/minha_app.service; disabled; vendor preset: enabled)
     Active: active (running) since Tue 2023-10-26 10:30:00 UTC; 5s ago
       Docs: https://github.com/exemplo/minha_app
   Main PID: 12345 (python3)
      Tasks: 1 (limit: 1100)
     Memory: 6.5M
        CPU: 45ms
     CGroup: /system.slice/minha_app.service
             └─12345 /usr/bin/python3 /opt/minha_app/app.py

Oct 26 10:30:00 seu_hostname python3[12345]: Servindo diretório /var/www/html na porta 8080
Oct 26 10:30:00 seu_hostname python3[12345]: Servidor iniciado.

Para visualizar os logs do serviço, use journalctl:

journalctl -u minha_app.service -f

Este comando mostra logs para minha_app.service e -f (follow) mostrará novos logs em tempo real.

Você também pode testar o servidor a partir do seu navegador ou curl em http://localhost:8080 (assumindo que /var/www/html existe e contém alguns arquivos).

Passo 7: Habilite o Serviço para Inicialização Automática

Para fazer seu serviço iniciar automaticamente toda vez que o sistema for inicializado, você precisa habilitá-lo:

sudo systemctl enable minha_app.service

Este comando cria um link simbólico de /etc/systemd/system/multi-user.target.wants/minha_app.service para /etc/systemd/system/minha_app.service.

Passo 8: Pare e Desabilite o Serviço

Para parar um serviço em execução:

sudo systemctl stop minha_app.service

Para impedir que um serviço inicie automaticamente na inicialização (enquanto o deixa habilitado para ser iniciado manualmente):

sudo systemctl disable minha_app.service

Se você quiser remover o serviço completamente, disable primeiro, depois stop e, finalmente, exclua o arquivo .service de /etc/systemd/system/ e execute sudo systemctl daemon-reload.

Passo 9: Atualizando um Serviço

Se você modificar seu script app.py ou o arquivo de unidade minha_app.service, precisará atualizar o systemd e reiniciar o serviço:

Edite /opt/minha_app/app.py ou /etc/systemd/system/minha_app.service.
Se você modificou o arquivo de unidade, execute sudo systemctl daemon-reload.
Reinicie o serviço: sudo systemctl restart minha_app.service.

Padrões Mais Seguros para Serviços Reais

Uma unidade que funciona nem sempre é uma unidade que você deseja manter por anos. Esses padrões evitam erros comuns:

Execute em primeiro plano. Deixe o systemd supervisionar o processo principal. Evite nohup, screen, tmux, & em segundo plano ou modos de daemon do aplicativo dentro de ExecStart.
Mantenha ExecStart direto. Se você precisar de recursos do shell, como pipes ou expansão de variáveis, chame /bin/sh -c '...' intencionalmente. Caso contrário, execute o executável diretamente.
Use um usuário dedicado. Um serviço que só precisa ler /opt/minha_app e vincular a uma porta não privilegiada não deve ser executado como root.
Recarregue após edições de unidade. sudo systemctl daemon-reload é necessário quando o arquivo de unidade muda.
Separe implantações de código de alterações de unidade. Se apenas o código Python mudou, reinicie o serviço. Se a unidade mudou, recarregue o systemd primeiro.

Solucionando Problemas de uma Nova Unidade

Se o serviço falhar, comece com:

systemctl status minha_app.service
journalctl -u minha_app.service -n 100 --no-pager
systemctl cat minha_app.service

Falhas comuns geralmente são simples:

status=203/EXEC geralmente significa que o caminho do executável está errado, o arquivo está faltando ou o arquivo não é executável.
Permission denied geralmente significa que o usuário do serviço não pode ler um arquivo, entrar em um diretório, escrever logs ou vincular a porta solicitada.
address already in use significa que outro processo possui a porta. Verifique com sudo ss -tulpen | grep ':8080'.
Um serviço que inicia manualmente, mas falha sob o systemd, geralmente depende de variáveis de ambiente, um diretório de trabalho diferente ou arquivos em seu diretório home.

Você pode testar o comando como o usuário do serviço:

sudo -u meuusuarioapp /usr/bin/python3 /opt/minha_app/app.py

Isso não é uma reprodução perfeita do ambiente do systemd, mas captura erros óbvios do aplicativo antes de você perseguir detalhes do arquivo de unidade.

Uma Variante Mais Amigável para Produção

Para um serviço interno de longa duração, eu geralmente adicionaria algumas proteções:

[Unit]
Description=Meu Servidor HTTP Python Personalizado
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=meuusuarioapp
Group=meuusuarioapp
WorkingDirectory=/opt/minha_app
EnvironmentFile=-/etc/minha_app/minha_app.env
ExecStart=/usr/bin/python3 /opt/minha_app/app.py
Restart=on-failure
RestartSec=10s
TimeoutStopSec=30s
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ReadWritePaths=/opt/minha_app /var/log/minha_app
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

ProtectSystem=full torna grande parte do sistema somente leitura para o serviço, então adicione ReadWritePaths= apenas para diretórios que o aplicativo realmente precisa escrever. Teste o endurecimento uma diretiva de cada vez. As opções de segurança são úteis, mas um serviço que não consegue ler sua configuração ou escrever seus dados falhará na inicialização.

Melhores Práticas e Solução de Problemas

Caminhos Absolutos: Sempre use caminhos absolutos para ExecStart, WorkingDirectory e quaisquer outros caminhos de arquivo dentro do seu arquivo de unidade. Caminhos relativos podem levar a comportamentos inesperados.
Usuários Dedicados: Execute serviços sob contas de usuário não privilegiadas e dedicadas (por exemplo, meuusuarioapp) para aumentar a segurança e limitar danos potenciais em caso de comprometimento.
Registro Claro: Utilize StandardOutput=journal e StandardError=journal para direcionar a saída do serviço para o journal do systemd. Use journalctl -u <nome_do_serviço> para visualizar logs.
Dependências: Considere cuidadosamente After, Wants e Requires para garantir que seu serviço inicie na ordem correta em relação às suas dependências (por exemplo, rede, bancos de dados).
Testando Alterações: Antes de habilitar um serviço para iniciar na inicialização, teste-o completamente iniciando e parando manualmente. Verifique seu status e logs.
Limites de Recursos: Use diretivas como LimitNOFILE, LimitNPROC e MemoryMax quando o serviço tiver limites conhecidos ou modos de falha.
Variáveis de Ambiente: Use Environment= ou EnvironmentFile= para valores de configuração que podem mudar ou variar entre ambientes, em vez de codificá-los no arquivo de unidade ou script.
Tratamento de Erros em Scripts: Certifique-se de que seus scripts de aplicativo tratem erros com elegância. Um código de saída diferente de zero acionará Restart=on-failure.

Aviso: Evite modificar arquivos de unidade diretamente em /usr/lib/systemd/system/. Quaisquer alterações provavelmente serão sobrescritas por atualizações de pacotes. Use /etc/systemd/system/ para unidades personalizadas ou substituições.

Uma boa unidade personalizada é chata da melhor maneira: o comando é explícito, o usuário não tem privilégios, o comportamento de reinicialização é intencional e os logs são fáceis de encontrar. Uma vez que isso é sólido, timers do systemd, ativação de socket e controles mais profundos de cgroup são os próximos passos naturais.