# Tarefas agendadas

Comandos com horário no VPS através de um serviço e um timer do systemd, com atalhos de minutos, execução manual e logs.

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

- Categoria: Servidores e infraestrutura
- Estado: Disponível
- Requisitos: Um VPS da empresa ligado, com systemd; Para criar, editar, controlar ou apagar: ser admin da empresa; Para listar e ver: ser membro com acesso ao VPS
- Ferramentas MCP (Só leem): `listar_tareas_vps`, `ver_tarea_vps`, `ver_logs_tarea_vps`
- Ferramentas MCP (Escrevem ou modificam): `crear_tarea_vps`, `editar_tarea_vps`, `controlar_tarea_vps`
- Ferramentas MCP (Destrutivas): `eliminar_tarea_vps`

## O que permite fazer?

- Correr um comando com horário: a cada N minutos, a uma hora fixa, em certos dias ou com os atalhos `hourly`, `daily` e `weekly`.
- Executar a tarefa uma vez no momento, ou interromper uma execução em curso.
- Mudar o comando ou o horário de uma tarefa existente.
- Ver a próxima e a última execução, e ler os logs do comando e do timer.

## Quando convém usar?

- Limpezas, exportações ou sincronizações periódicas que não são de uma app da ArduMaker.
- Um script que tem de correr mesmo que o VPS estivesse desligado a essa hora (executa ao ligar).

> **INFO:** Não se usa `crontab`: cada tarefa é um par serviço + timer do systemd. O trabalho agendado de uma app de Git vai como processo `timer` na sua configuração de deploy, não aqui.

## Como funciona na ArduMaker?

### Validações antes de tocar no VPS

- **Nome**: as mesmas regras que um serviço systemd (`nombre_invalido`).
- **Comando**: uma única linha, até 4000 caracteres, com aspas fechadas (`comando_invalido`). Se usa pipes, `&&`, variáveis, redirecionamentos ou comandos internos da shell, é envolvido automaticamente em `/bin/sh -c "…"` com o escape necessário.
- **Horário**: uma expressão `OnCalendar` (`daily`, `*-*-* 02:00:00`, `Mon..Fri *-*-* 10:00`, `*-*-* *:0/5:00 Europe/Madrid`). Atalhos: `5` ou `*/5` significam a cada 5 minutos, e `1` a cada minuto.
- O erro de validação diz que campo falhou em `data.fields`.

### Criação

1. Guardam-se cópias da unidade e do timer se já existiam.
2. Escreve-se `/etc/systemd/system/<nombre>.service` (`Type=oneshot`, saída para o journal com o nome da tarefa) e `/etc/systemd/system/<nombre>.timer` (`OnCalendar`, `Persistent=true`).
3. `daemon-reload`, arranca-se o timer e ativa-se no arranque. Se um passo falhar, apaga-se o novo e restauram-se as cópias.
4. Com `start=true` o comando corre também uma vez nesse momento (se essa execução falhar, a tarefa fica criada na mesma).

### Editar, controlar e apagar

- **Editar** lê o comando e o horário atuais, **apaga a tarefa e volta a criá-la** com o novo. A tarefa editada fica ativada.
- **`start`** corre o comando agora; **`stop`** interrompe essa execução (não para o timer).
- **`enable`** e **`disable`** mudam se o timer arranca com o sistema. `disable` não para um timer que já está ativo: continua a disparar até ao próximo reinício do VPS.
- **Apagar** para e desativa o timer, remove os dois arquivos e recarrega o systemd. Não há nomes protegidos.

## O que muda realmente?

- `/etc/systemd/system/<nombre>.service` e `/etc/systemd/system/<nombre>.timer`, com permissões 644.
- O comando corre como `root`, e a sua saída fica no journal identificada com o nome da tarefa.
- Uma entrada no registro de atividade do VPS por cada criação, edição, ação e exclusão.

```ini
# <nombre>.timer
[Unit]
Description=Timer for task: limpieza

[Timer]
OnCalendar=*-*-* 02:00:00
Unit=limpieza.service
Persistent=true

[Install]
WantedBy=timers.target
```

## Esquema

**Uma tarefa agendada**

```text
Timer (OnCalendar dispara à hora indicada)
  ↓
Serviço oneshot (corre o comando uma vez e termina)
  ↓
journal (saída e erros com o nome da tarefa)
```

Com `Persistent=true`, se o VPS estava desligado à hora prevista, a tarefa corre ao ligar.

## Resultado esperado

- Criar, editar e controlar devolvem `timer_status`, `is_enabled` e, salvo ao criar, `next_run`.
- `ver_tarea_vps` mostra o conteúdo do serviço e do timer, o estado, e a próxima e a última execução.
- `ver_logs_tarea_vps` com `log_type: "service"` mostra a saída do comando; com `"timer"`, a do timer.

```bash
systemctl list-timers --no-pager
journalctl -u limpieza.service -n 50 --no-pager
```

## Erros e resolução

| Resposta | Causa | O que fazer |
| --- | --- | --- |
| 400 `nombre_invalido` em `schedule` | O horário tem caracteres que não são de uma expressão OnCalendar (aspas, `$`, `;`) | Corrigir o horário |
| 400 `comando_invalido` | Quebra de linha, aspas por fechar ou mais de 4000 caracteres | Passá-lo para um script e chamar o script |
| 400 com `data.cause` | O VPS não conseguiu escrever ou ativar a tarefa; `cause` diz em que passo | Rever o passo indicado |
| 404 `Task not found` | A tarefa não existe | Listar primeiro |
| 403 | Só um admin da empresa pode criar, editar, controlar ou apagar | Pedir a um admin |
| A tarefa continua a correr depois de `disable` | `disable` só afeta o arranque | Apagar a tarefa se tiver de parar já |

> **PRECAUCION:** Editar apaga e volta a criar a tarefa: se a recriação falhar (por exemplo, o VPS deixa de responder a meio), a tarefa fica apagada. Convém salvar o comando e o horário antes de editar.

Criar com o mesmo nome substitui a tarefa; tentar de novo após um corte é seguro com a mesma `idempotency_key`. `controlar_tarea_vps` com `start` volta a correr o comando de cada vez.

## Relação com MCP

Sim, nos perfis `/mcp` e `/mcp/vps`.

| Ferramenta | Tipo | Notas |
| --- | --- | --- |
| `listar_tareas_vps`, `ver_tarea_vps` | Leitura | Membro |
| `ver_logs_tarea_vps` | Leitura | Conteúdo não confiável |
| `crear_tarea_vps` | Escrita | Admin; aceita `idempotency_key` |
| `editar_tarea_vps` | Escrita | Admin; apaga e recria |
| `controlar_tarea_vps` | Escrita | Admin; `start`, `stop`, `enable`, `disable` (sem `restart`) |
| `eliminar_tarea_vps` | Destrutiva | Admin; sem nomes protegidos |

Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs) e exemplos em [/mcp/servicios](https://ardumaker.com/pt/mcp/servicios).

## Funcionalidades relacionadas

- [Serviços systemd](https://ardumaker.com/pt/docs/systemd/)
- [Cópias de segurança](https://ardumaker.com/pt/docs/backups/)
- [Monitoramento](https://ardumaker.com/pt/docs/monitorizacion/)
- [Servidores VPS](https://ardumaker.com/pt/docs/vps/)