Como Escrever Arquivos de Unidade systemd - Registrando Serviços Personalizados

2026-05-31 Tempo de leitura: Cerca de 10 min Dificuldade: Intermediário+

O que é um arquivo de unidade systemd?

Um arquivo de unidade systemd é um arquivo de configuração que registra serviços, pontos de montagem, timers e outros recursos no sistema. Colocando um arquivo .service em /etc/systemd/system/, você pode gerenciar qualquer script ou aplicação como um daemon com controle completo do ciclo de vida.

Estrutura do arquivo de unidade

Um arquivo de unidade tem três seções:

[Unit]
Description=My Custom Service
After=network.target

[Service]
ExecStart=/usr/local/bin/myapp
Restart=on-failure
User=myuser

[Install]
WantedBy=multi-user.target

1. Registrar um serviço personalizado com um arquivo de unidade mínimo

A maneira mais rápida de transformar um shell script em um serviço gerenciado.

1-1. Criar o script

sudo tee /usr/local/bin/myapp.sh > /dev/null << 'EOF'
#!/bin/bash
while true; do
    echo "$(date) running" >> /var/log/myapp.log
    sleep 10
done
EOF
sudo chmod +x /usr/local/bin/myapp.sh

1-2. Criar o arquivo de unidade

sudo tee /etc/systemd/system/myapp.service > /dev/null << 'EOF'
[Unit]
Description=My Application
After=network.target

[Service]
ExecStart=/usr/local/bin/myapp.sh
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

1-3. Recarregar, habilitar e iniciar

sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp

● myapp.service - My Application
     Loaded: loaded (/etc/systemd/system/myapp.service; enabled)
     Active: active (running) since Sun 2026-05-31 12:00:00 UTC; 3s ago
   Main PID: 12345 (myapp.sh)

2. Seção [Unit] - Definindo ordem de inicialização e dependências

[Unit] controla metadados do serviço e ordenação de inicialização.

[Unit]
Description=Web Application Backend
After=network.target postgresql.service
Wants=postgresql.service

3. Seção [Service] - Comando de inicialização e comportamento

A seção com mais configurações. Estas são as diretivas principais.

Escolhendo Type=

Type= define como o systemd rastreia o estado do processo.

Para a maioria dos casos, simple ou oneshot é a escolha certa.

Diretivas principais

[Service]
Type=simple
ExecStart=/usr/local/bin/myapp --config /etc/myapp/config.yml
ExecStop=/bin/kill -TERM $MAINPID
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
User=www-data
Group=www-data
WorkingDirectory=/var/lib/myapp
EnvironmentFile=/etc/myapp/env

Passando variáveis de ambiente

[Service]
Environment="NODE_ENV=production"
Environment="PORT=3000"
EnvironmentFile=/etc/myapp/env

Exemplo /etc/myapp/env:

DB_HOST=localhost
DB_PORT=5432
SECRET_KEY=changeme

sudo chmod 600 /etc/myapp/env
sudo chown root:root /etc/myapp/env

4. Seção [Install] - Controlando o comportamento do enable

Esta seção é lida quando você executa systemctl enable.

[Install]
WantedBy=multi-user.target

WantedBy=multi-user.target é a escolha padrão. Executar systemctl enable myapp cria um symlink em /etc/systemd/system/multi-user.target.wants/myapp.service, que aciona a inicialização automática no boot.

5. Comandos de gerenciamento de serviços

Operações comuns após criar um arquivo de unidade:

# Recarregar arquivos de unidade (obrigatorio apos qualquer alteracao)
sudo systemctl daemon-reload

# Habilitar (inicio automatico no boot) + iniciar imediatamente
sudo systemctl enable --now myapp

# Verificar status
sudo systemctl status myapp

# Reiniciar
sudo systemctl restart myapp

# Recarregar configuracao (requer ExecReload)
sudo systemctl reload myapp

# Parar
sudo systemctl stop myapp

# Desabilitar inicio automatico
sudo systemctl disable myapp

# Ver logs recentes (ultimas 50 linhas)
journalctl -u myapp -n 50 --no-pager

6. Falhas comuns e como corrigi-las

Caminho do ExecStart não encontrado

myapp.service: control process exited with error code
ExecStart=/usr/local/bin/myapp (code=exited, status=203/EXEC)

Correção: verifique o caminho completo.

which myapp
ls -la /usr/local/bin/myapp

Esqueceu daemon-reload

Alterações no arquivo de unidade não são refletidas, ou "Unit not found" aparece.

sudo systemctl daemon-reload
sudo systemctl restart myapp

Permissão negada

journalctl -u myapp -n 20
# myapp.sh: Permission denied

Correção: verifique a permissão de execução.

ls -la /usr/local/bin/myapp.sh
# Se falta permissao de execucao:
sudo chmod +x /usr/local/bin/myapp.sh

Se User= estiver definido, verifique também se o usuário especificado pode ler o arquivo.

EnvironmentFile não encontrado

Se EnvironmentFile= aponta para um arquivo ausente, o serviço falhará ao iniciar. Para permitir a inicialização mesmo quando o arquivo está ausente, prefixe o caminho com -:

EnvironmentFile=-/etc/myapp/env

Cheatsheet do fluxo completo

# 1. Criar o script
sudo vim /usr/local/bin/myapp.sh
sudo chmod +x /usr/local/bin/myapp.sh

# 2. Criar o arquivo de unidade
sudo vim /etc/systemd/system/myapp.service

# 3. Registrar e iniciar
sudo systemctl daemon-reload
sudo systemctl enable --now myapp

# 4. Verificar
sudo systemctl status myapp
journalctl -u myapp -f