# Serviços systemd

Criar, editar, controlar e apagar serviços systemd em um VPS, com reversão se não arrancarem e logs do journal.

Fonte: https://ardumaker.com/pt/docs/systemd/

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um VPS da empresa ligado; Ser membro da empresa com acesso ao VPS; Um sistema com systemd (o Ubuntu 16.04 não é suportado; consulte com `ver_funciones_vps`)
- Ferramentas MCP (Só leem): `listar_servicios_vps`, `ver_servicio_vps`, `ver_logs_systemd_vps`
- Ferramentas MCP (Escrevem ou modificam): `crear_servicio_vps`, `editar_servicio_vps`
- Ferramentas MCP (Destrutivas): `eliminar_servicio_vps`, `controlar_servicio_vps`

## O que permite fazer?

- Listar todos os serviços do VPS e ver o detalhe de um: o arquivo de unidade, se está ativo e se arranca no arranque do sistema.
- Criar um serviço a partir do conteúdo completo de um arquivo de unidade.
- Substituir o arquivo de unidade de um serviço existente.
- Arrancar, parar, reiniciar, ativar ou desativar um serviço.
- Apagar um serviço (salvo os protegidos) e ler os seus logs.

## Quando convém usar?

- Um processo que tem de ficar sempre a correr e não pertence a uma app da ArduMaker: um worker, um bot, um exportador de métricas.
- Reiniciar um serviço depois de mudar a sua configuração.
- Rever porque é que um serviço cai.

> **INFO:** O que o catálogo de Apps oferece instala-se com Apps, e os processos de uma app de Git vão na sua configuração de deploy: assim a plataforma mostra-os, reinicia-os em cada deploy e faz cópia deles. Um serviço systemd solto é para o que não cabe em nenhum desses dois casos.

## Como funciona na ArduMaker?

### Criar

1. Valida-se o nome: minúsculas, e espaços e `/` passam a hífens. Só letras, números e `_ . @ : -`, até 200 caracteres; caso contrário, `nombre_invalido`.
2. Se já existe `/etc/systemd/system/<nombre>.service`, guarda-se uma cópia `.backup`.
3. Escreve-se o conteúdo tal como chega (sem validação extra), com permissões 644.
4. `systemctl daemon-reload`, depois `systemctl start` e `systemctl enable`.
5. Se qualquer um desses passos falhar, apaga-se a unidade nova, restaura-se a cópia e recarrega-se o systemd. A resposta diz em que passo falhou (`Failed to start service`, `Failed to enable service`…).

Na prática, criar um serviço deixa-o sempre a correr e ativado no arranque; um serviço que não arranca não fica criado.

### Editar

Editar substitui o arquivo completo com o mesmo procedimento, mas faz `start` e não `restart`: **se o serviço já estava correndo, continua com a configuração anterior** até ser reiniciado com `controlar_servicio_vps` e a ação `restart`.

### Controlar e apagar

- `start`, `stop` e `restart` atuam agora; `enable` e `disable` só mudam se arranca com o sistema.
- Controlar não tem lista de protegidos: é possível parar o `nginx` ou o `docker`.
- Apagar para, desativa, remove `/etc/systemd/system/<nombre>.service` e recarrega o systemd. Uma unidade que veio com um pacote do sistema fica parada e desativada, mas o arquivo não está nessa pasta e não é apagado.
- Não podem ser apagados: `ssh`, `sshd`, `networking`, `systemd-journald`, `systemd-logind`, `docker`, `containerd`, `nginx`, `apache2`, `mysql` e `postgresql`.

## O que muda realmente?

- `/etc/systemd/system/<nombre>.service` (644) e o link de `enable` no arranque do sistema.
- O processo em execução, com a saída padrão e de erro no journal.
- Uma entrada no registro de atividade do VPS por cada criação, edição, ação ou exclusão.

## Exemplo de unidade

Uma unidade como a que a ArduMaker monta para os processos de um deploy:

```ini
[Unit]
Description=mi-worker
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/mi-worker
Environment="MODO=produccion"
ExecStart=/opt/mi-worker/venv/bin/python worker.py
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

- `Restart=always` volta a levantá-lo se cair.
- `StandardOutput=journal` faz com que `ver_logs_systemd_vps` mostre a sua saída.
- `WantedBy=multi-user.target` é o que permite o `enable`.

## Esquema

**Criar um serviço**

```text
Pedido (nome + conteúdo da unidade)
  ↓
Validação do nome (nombre_invalido)
  ↓
Agente do VPS (escreve a unidade e guarda cópia)
  ↓
systemd (daemon-reload → start → enable)
  ↓
Resultado (ativo e ativado, ou reversão)
```

## Resultado esperado

- As respostas de criar, editar e controlar trazem `status`, `is_active` e `is_enabled` lidos depois da operação.
- `ver_servicio_vps` devolve `service_file`, `content`, `status`, `is_active`, `is_enabled` e `details`.
- `ver_logs_systemd_vps` devolve as últimas 500 linhas do journal do serviço.

```bash
systemctl status mi-worker
journalctl -u mi-worker -n 100 --no-pager
```

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| `Failed to start service` | O processo não arrancou; a criação foi revertida | Rever `ExecStart`, caminhos e permissões; ler os logs |
| `Failed to reload systemd daemon` | A unidade tem um erro de formato | Corrigir o conteúdo |
| 403 ao apagar | Nome protegido | Pará-lo ou desativá-lo em vez disso |
| 404 `Service not found` | Esse serviço não existe | Listar primeiro |
| `nombre_invalido` | Caracteres não permitidos no nome | Usar o formato válido |
| `funcion_no_disponible` (409) | O sistema do VPS não tem systemd utilizável | Não se resolve tentando de novo |
| Mudei a unidade e nada aconteceu | Editar faz `start`, não `restart` | Reiniciar o serviço |

Criar e editar são seguros de repetir com o mesmo conteúdo. `controlar_servicio_vps` em geral não é (repetir um `stop` ou um `restart` corta o serviço outra vez) e pode parar serviços críticos. Se o VPS não responder, o erro pode ser repetido (424).

## Relação com MCP

Sim, nos perfis `/mcp` e `/mcp/vps`. Um agente só de leitura vê apenas `listar_servicios_vps`, `ver_servicio_vps` e `ver_logs_systemd_vps`.

| Ferramenta | Tipo | Notas |
| --- | --- | --- |
| `listar_servicios_vps`, `ver_servicio_vps` | Leitura | — |
| `ver_logs_systemd_vps` | Leitura | Chega marcado como conteúdo não confiável |
| `crear_servicio_vps` | Escrita | Aceita `idempotency_key` |
| `editar_servicio_vps` | Escrita | Substituição completa |
| `controlar_servicio_vps` | Destrutiva | Sem proteção de serviços protegidos |
| `eliminar_servicio_vps` | Destrutiva | Rejeita os nomes protegidos |

Para os processos de uma app de Git convém usar `ver_config_deploy_app` e `guardar_config_deploy_app` em vez destas ferramentas. Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/servicios](https://ardumaker.com/pt/mcp/servicios).

## Funcionalidades relacionadas

- [Tarefas agendadas](https://ardumaker.com/pt/docs/cron/)
- [Deploy do GitHub](https://ardumaker.com/pt/docs/github-deploy/)
- [Monitoramento](https://ardumaker.com/pt/docs/monitorizacion/)
- [Terminal web](https://ardumaker.com/pt/docs/terminal-web/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)