# Servicios systemd

Crear, editar, controlar y borrar servicios systemd en un VPS, con vuelta atrás si no arrancan y logs del journal.

Fuente: https://ardumaker.com/docs/systemd/

- Categoría: Servidores e infraestructura
- Estado: Disponible
- Requisitos: Un VPS de la empresa encendido; Ser miembro de la empresa con acceso al VPS; Un sistema con systemd (Ubuntu 16.04 no lo soporta; se consulta con `ver_funciones_vps`)
- Herramientas MCP (Solo leen): `listar_servicios_vps`, `ver_servicio_vps`, `ver_logs_systemd_vps`
- Herramientas MCP (Escriben o modifican): `crear_servicio_vps`, `editar_servicio_vps`
- Herramientas MCP (Destructivas): `eliminar_servicio_vps`, `controlar_servicio_vps`

## ¿Qué permite hacer?

- Listar todos los servicios del VPS y ver el detalle de uno: su archivo de unidad, si está activo y si arranca al inicio.
- Crear un servicio a partir del contenido completo de un archivo de unidad.
- Reemplazar el archivo de unidad de un servicio existente.
- Arrancar, detener, reiniciar, habilitar o deshabilitar un servicio.
- Borrar un servicio (salvo los protegidos) y leer sus logs.

## ¿Cuándo conviene usarlo?

- Un proceso que tiene que quedar corriendo siempre y que no pertenece a una app de ArduMaker: un worker, un bot, un exportador de métricas.
- Reiniciar un servicio después de cambiar su configuración.
- Revisar por qué un servicio se cae.

> **INFO:** Lo que ofrece el catálogo de Apps se instala con Apps, y los procesos de una app de Git van en su configuración de deploy: así la plataforma los muestra, los reinicia en cada deploy y los respalda. Un servicio systemd suelto es para lo que no entra en ninguno de esos dos casos.

## ¿Cómo funciona en ArduMaker?

### Crear

1. Se valida el nombre: minúsculas, y espacios y `/` pasan a guiones. Solo letras, números y `_ . @ : -`, hasta 200 caracteres; si no, `nombre_invalido`.
2. Si ya existe `/etc/systemd/system/<nombre>.service`, se guarda una copia `.backup`.
3. Se escribe el contenido tal cual llega (sin validación extra), con permisos 644.
4. `systemctl daemon-reload`, después `systemctl start` y `systemctl enable`.
5. Si cualquiera de esos pasos falla, se borra la unidad nueva, se restaura la copia y se recarga systemd. La respuesta dice en qué paso falló (`Failed to start service`, `Failed to enable service`…).

En la práctica, crear un servicio siempre lo deja corriendo y habilitado al inicio; un servicio que no arranca no queda creado.

### Editar

Editar reemplaza el archivo completo con el mismo procedimiento, pero hace `start` y no `restart`: **si el servicio ya estaba corriendo, sigue con la configuración anterior** hasta que se lo reinicie con `controlar_servicio_vps` y la acción `restart`.

### Controlar y borrar

- `start`, `stop` y `restart` actúan ahora; `enable` y `disable` solo cambian si arranca con el sistema.
- Controlar no tiene lista de protegidos: se puede detener `nginx` o `docker`.
- Borrar detiene, deshabilita, quita `/etc/systemd/system/<nombre>.service` y recarga systemd. Una unidad que vino con un paquete del sistema queda detenida y deshabilitada, pero su archivo no está en esa carpeta y no se borra.
- No se pueden borrar: `ssh`, `sshd`, `networking`, `systemd-journald`, `systemd-logind`, `docker`, `containerd`, `nginx`, `apache2`, `mysql` y `postgresql`.

## ¿Qué cambia realmente?

- `/etc/systemd/system/<nombre>.service` (644) y el enlace de `enable` en el arranque del sistema.
- El proceso en ejecución, con la salida estándar y de error en el journal.
- Una entrada en el registro de actividad del VPS por cada alta, edición, acción o borrado.

## Ejemplo de unidad

Una unidad como la que arma ArduMaker para los procesos de un 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` lo vuelve a levantar si se cae.
- `StandardOutput=journal` hace que `ver_logs_systemd_vps` muestre su salida.
- `WantedBy=multi-user.target` es lo que permite `enable`.

## Esquema

**Crear un servicio**

```text
Pedido (nombre + contenido de la unidad)
  ↓
Validación del nombre (nombre_invalido)
  ↓
Agente del VPS (escribe la unidad y guarda copia)
  ↓
systemd (daemon-reload → start → enable)
  ↓
Resultado (activo y habilitado, o vuelta atrás)
```

## Resultado esperado

- Las respuestas de crear, editar y controlar traen `status`, `is_active` e `is_enabled` leídos después de la operación.
- `ver_servicio_vps` devuelve `service_file`, `content`, `status`, `is_active`, `is_enabled` y `details`.
- `ver_logs_systemd_vps` devuelve las últimas 500 líneas del journal del servicio.

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

## Errores y resolución

| Respuesta | Causa | Qué hacer |
| --- | --- | --- |
| `Failed to start service` | El proceso no arrancó; la creación se revirtió | Revisar `ExecStart`, rutas y permisos; leer los logs |
| `Failed to reload systemd daemon` | La unidad tiene un error de formato | Corregir el contenido |
| 403 al borrar | Nombre protegido | Detenerlo o deshabilitarlo en su lugar |
| 404 `Service not found` | No existe ese servicio | Listar primero |
| `nombre_invalido` | Caracteres no permitidos en el nombre | Usar el formato válido |
| `funcion_no_disponible` (409) | El sistema del VPS no tiene systemd utilizable | No se resuelve reintentando |
| Cambié la unidad y no pasó nada | Editar hace `start`, no `restart` | Reiniciar el servicio |

Crear y editar son seguros de repetir con el mismo contenido. `controlar_servicio_vps` no lo es en general (repetir un `stop` o un `restart` corta el servicio otra vez) y puede detener servicios críticos. Si el VPS no contesta, el error es reintentable (424).

## Relación con MCP

Sí, en los perfiles `/mcp` y `/mcp/vps`. Un agente de solo lectura solo ve `listar_servicios_vps`, `ver_servicio_vps` y `ver_logs_systemd_vps`.

| Herramienta | Tipo | Notas |
| --- | --- | --- |
| `listar_servicios_vps`, `ver_servicio_vps` | Lectura | — |
| `ver_logs_systemd_vps` | Lectura | Llega marcado como contenido no confiable |
| `crear_servicio_vps` | Escritura | Acepta `idempotency_key` |
| `editar_servicio_vps` | Escritura | Reemplazo completo |
| `controlar_servicio_vps` | Destructiva | Sin guarda de servicios protegidos |
| `eliminar_servicio_vps` | Destructiva | Rechaza los nombres protegidos |

Para los procesos de una app de Git conviene `ver_config_deploy_app` y `guardar_config_deploy_app` en lugar de estas herramientas. Referencia en [/mcp/docs](https://ardumaker.com/mcp/docs) y ejemplos en [/mcp/servicios](https://ardumaker.com/mcp/servicios).

## Funciones relacionadas

- [Tareas programadas](https://ardumaker.com/docs/cron/)
- [Deploy desde GitHub](https://ardumaker.com/docs/github-deploy/)
- [Monitorización](https://ardumaker.com/docs/monitorizacion/)
- [Terminal web](https://ardumaker.com/docs/terminal-web/)
- [Servidores VPS](https://ardumaker.com/docs/vps/)