Cómo Escribir y Gestionar Archivos de Unidad Systemd Personalizados de Forma Efectiva

Los archivos de unidad systemd personalizados convierten un comando que funciona en tu terminal en un servicio que el sistema operativo puede iniciar, detener, reiniciar, registrar y supervisar. La diferencia es importante. Un comando en un shell hereda tu entorno y termina cuando la sesión finaliza. Un servicio tiene un usuario explícito, directorio de trabajo, política de reinicio, dependencias, límites de recursos y registros.

Este es el camino práctico que uso para APIs internas pequeñas, trabajadores, scripts sidecar y demonios únicos: escribir la unidad correcta más simple, ejecutarla como un usuario dedicado, dejar que los registros vayan al diario, y solo agregar directivas avanzadas cuando aparezca un requisito real.

Comprendiendo los Archivos de Unidad Systemd

Systemd gestiona varios recursos del sistema, conocidos como unidades, que están definidos por archivos de configuración. Estas unidades incluyen servicios (.service), puntos de montaje (.mount), dispositivos (.device), sockets (.socket) y más. Para gestionar aplicaciones y procesos en segundo plano, el tipo de unidad .service es el más común y relevante.

Los archivos de unidad systemd son archivos de texto plano típicamente almacenados en directorios específicos. Las ubicaciones principales, en orden de precedencia, son:

/etc/systemd/system/: Esta es la ubicación recomendada para archivos de unidad personalizados y anulaciones, ya que tienen prioridad sobre los valores predeterminados del sistema y persisten en las actualizaciones del sistema.
/run/systemd/system/: Se utiliza para archivos de unidad generados en tiempo de ejecución.
/usr/lib/systemd/system/: Contiene archivos de unidad proporcionados por paquetes instalados. No modifiques archivos en este directorio directamente.

Al colocar tus archivos de unidad personalizados en /etc/systemd/system/, te aseguras de que sean reconocidos y gestionados correctamente por systemd.

Anatomía de un Archivo de Unidad `.service`

Un archivo de unidad .service de systemd está estructurado en varias secciones, cada una denotada por [NombreSeccion], que contienen varias directivas (pares clave-valor). Las tres secciones principales para una unidad de servicio son [Unit], [Service] y [Install].

Desglosemos las directivas más cruciales que usarás:

Sección [Unit]

Esta sección contiene opciones genéricas sobre la unidad, su descripción y dependencias.

Description: Una cadena legible por humanos que describe el servicio. Aparece en la salida de systemctl status.
```
Description=Mi Aplicación Web Python Personalizada
```
Documentation: Una URL que apunta a la documentación del servicio (opcional).
```
Documentation=https://example.com/docs/mi-app
```
After: Especifica que esta unidad debe iniciarse después de las unidades listadas. Esto ayuda a gestionar el orden de inicio. Para aplicaciones web, es posible que desees asegurarte de que la red esté activa.
```
After=network.target
```
Requires: Una dependencia fuerte. Si la unidad requerida falla al iniciar, esta unidad no se iniciará. Si la unidad requerida se detiene, esta unidad también puede detenerse.
```
Requires=docker.service
```
Wants: Una dependencia más débil. Si la unidad deseada falla o no se encuentra, esta unidad aún intenta iniciarse. Este suele ser un valor predeterminado mejor que Requires.
```
Wants=syslog.target
```

Sección [Service]

Esta sección define los parámetros de ejecución para tu servicio, incluyendo cómo se inicia, detiene y comporta.

Type: Define el tipo de inicio del proceso. Es crítico para cómo systemd monitorea tu servicio.
- simple (predeterminado): El comando ExecStart es el proceso principal del servicio. Systemd considera el servicio iniciado inmediatamente después de invocar ExecStart. Espera que el proceso se ejecute indefinidamente en primer plano.
- forking: El comando ExecStart bifurca un proceso hijo y el padre sale. Systemd considera el servicio iniciado una vez que el proceso padre sale. Úsalo si tu aplicación se demoniza a sí misma.
- oneshot: El comando ExecStart es un proceso único que sale cuando termina. Útil para scripts que realizan una tarea y terminan (por ejemplo, un script de respaldo).
- notify: Similar a simple, pero el servicio le dice a systemd cuando está listo. Esto requiere soporte de la aplicación para notificaciones de systemd.
- idle: El comando ExecStart se ejecuta solo cuando todos los trabajos están terminados, retrasando la ejecución hasta que el sistema esté mayormente inactivo.
```
Type=simple
```
ExecStart: El comando a ejecutar cuando el servicio se inicia. Esta es la directiva más importante en esta sección. Siempre usa la ruta absoluta a tu ejecutable o script.
```
ExecStart=/usr/bin/python3 /opt/mi_app/app.py
```
ExecStop: El comando a ejecutar cuando el servicio se detiene (opcional). Si no se especifica, systemd envía SIGTERM a los procesos.
```
ExecStop=/usr/bin/pkill -f 'mi_app/app.py'
```
ExecReload: El comando a ejecutar para recargar la configuración del servicio (opcional).
```
ExecReload=/bin/kill -HUP $MAINPID
```
User: La cuenta de usuario bajo la cual se ejecutarán los procesos del servicio. Esencial para la seguridad; evita root a menos que sea absolutamente necesario.
```
User=usuariomiapp
```
Group: La cuenta de grupo bajo la cual se ejecutarán los procesos del servicio.
```
Group=grupo miapp
```
WorkingDirectory: El directorio de trabajo para los comandos ejecutados.
```
WorkingDirectory=/opt/mi_app
```
Restart: Define cuándo se debe reiniciar automáticamente el servicio.
- no (predeterminado): Nunca reiniciar.
- on-success: Reiniciar solo si el servicio sale limpiamente.
- on-failure: Reiniciar solo si el servicio sale con un código de estado distinto de cero o es eliminado por una señal.
- always: Reiniciar siempre el servicio, independientemente del estado de salida.
```
Restart=on-failure
```
RestartSec: Cuánto tiempo esperar antes de reiniciar el servicio (por ejemplo, 5s para 5 segundos).
```
RestartSec=5s
```
Environment: Establece variables de entorno para los comandos ejecutados.
```
Environment="APP_ENV=production" "DEBUG=false"
```
EnvironmentFile: Lee variables de entorno desde un archivo. Cada línea debe ser KEY=VALUE.
```
EnvironmentFile=/etc/default/mi_app
```
LimitNOFILE: Establece el número máximo de descriptores de archivo abiertos permitidos para el servicio (por ejemplo, 100000). Importante para aplicaciones de alta concurrencia.
```
LimitNOFILE=65536
```

Sección [Install]

Esta sección define cómo se habilita el servicio para iniciarse automáticamente al arrancar.

WantedBy: Especifica la unidad objetivo que "desea" este servicio. Cuando la unidad objetivo está habilitada, este servicio se enlazará simbólicamente en su directorio .wants, haciendo efectivamente que se inicie con el objetivo.
- multi-user.target: El objetivo estándar para la mayoría de los servicios de servidor, indicando un sistema con inicios de sesión multiusuario no gráficos.
- graphical.target: Para servicios que requieren un entorno gráfico.
```
WantedBy=multi-user.target
```
RequiredBy: Similar a WantedBy, pero una dependencia más fuerte. Si el objetivo está habilitado, esta unidad también se habilita, y si esta unidad falla, el objetivo también fallará.

Para la mayoría de los servicios personalizados destinados a ejecutarse en segundo plano en un servidor, Type=simple y WantedBy=multi-user.target son el punto de partida correcto. Si la aplicación ya se demoniza a sí misma, deshabilita ese comportamiento o usa Type=forking con cuidado. Un proceso en primer plano es más fácil de supervisar para systemd.

Paso a Paso: Creando y Gestionando un Servicio Systemd Personalizado

Creemos un ejemplo práctico: un servidor HTTP Python simple que sirve archivos desde un directorio especificado. Lo configuraremos como un servicio systemd.

Paso 1: Prepara tu Aplicación/Script

Primero, crea el script de la aplicación. Para este ejemplo, usaremos un servidor HTTP Python simple. Crea un directorio para tu aplicación, por ejemplo, /opt/mi_app, y coloca app.py dentro.

# /opt/mi_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"Sirviendo directorio {DIRECTORY} en el puerto {PORT}")

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

Crea el directorio y el archivo:

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

(Pega el código Python)

Asegúrate de que el script sea ejecutable (opcional para el comando python3, pero buena práctica):

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

Considera crear un usuario dedicado para tu servicio por razones de seguridad:

sudo useradd --system --no-create-home usuariomiapp

Establece la propiedad adecuada para tu directorio de aplicación:

sudo chown -R usuariomiapp:usuariomiapp /opt/mi_app

Paso 2: Crea el Archivo de Unidad

Ahora, crea el archivo de unidad systemd para nuestra aplicación Python. Lo nombraremos mi_app.service.

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

Pega el siguiente contenido:

# /etc/systemd/system/mi_app.service

[Unit]
Description=Mi Servidor HTTP Python Personalizado
Documentation=https://github.com/example/mi_app
After=network.target

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

[Install]
WantedBy=multi-user.target

Nota: Hemos establecido StandardOutput=journal y StandardError=journal para dirigir la salida del servicio al diario de systemd, facilitando la visualización de registros con journalctl.

Si tu aplicación necesita secretos, evita ponerlos directamente en el archivo de unidad. Usa un archivo de entorno con permisos restrictivos, un gestor de secretos o soporte de credenciales específico de la distribución. Los archivos de unidad a menudo son legibles por más personas de las que esperas.

Paso 3: Coloca el Archivo de Unidad

Como se indicó, hemos colocado el archivo de unidad en /etc/systemd/system/. Aquí es donde deben residir los archivos de unidad personalizados.

Paso 4: Recarga el Demonio Systemd

Después de crear o modificar un archivo de unidad, systemd necesita ser informado de los cambios. Esto se hace recargando el demonio systemd:

sudo systemctl daemon-reload

Paso 5: Inicia el Servicio

Ahora puedes iniciar tu servicio:

sudo systemctl start mi_app.service

Paso 6: Verifica el Estado y los Registros del Servicio

Verifica que tu servicio se esté ejecutando correctamente:

systemctl status mi_app.service

Ejemplo de salida (truncada):

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

Oct 26 10:30:00 nombrehost python3[12345]: Sirviendo directorio /var/www/html en el puerto 8080
Oct 26 10:30:00 nombrehost python3[12345]: Servidor iniciado.

Para ver los registros del servicio, usa journalctl:

journalctl -u mi_app.service -f

Este comando muestra los registros de mi_app.service y -f (seguir) mostrará nuevos registros en tiempo real.

También puedes probar el servidor desde tu navegador o curl en http://localhost:8080 (asumiendo que /var/www/html existe y contiene algunos archivos).

Paso 7: Habilita el Servicio para Inicio Automático

Para que tu servicio se inicie automáticamente cada vez que el sistema arranque, debes habilitarlo:

sudo systemctl enable mi_app.service

Este comando crea un enlace simbólico desde /etc/systemd/system/multi-user.target.wants/mi_app.service a /etc/systemd/system/mi_app.service.

Paso 8: Detén y Deshabilita el Servicio

Para detener un servicio en ejecución:

sudo systemctl stop mi_app.service

Para evitar que un servicio se inicie automáticamente al arrancar (dejándolo habilitado para ser iniciado manualmente):

sudo systemctl disable mi_app.service

Si deseas eliminar el servicio por completo, primero disablelo, luego stoplo, y finalmente elimina el archivo .service de /etc/systemd/system/ y ejecuta sudo systemctl daemon-reload.

Paso 9: Actualizando un Servicio

Si modificas tu script app.py o el archivo de unidad mi_app.service, necesitarás actualizar systemd y reiniciar el servicio:

Edita /opt/mi_app/app.py o /etc/systemd/system/mi_app.service.
Si modificaste el archivo de unidad, ejecuta sudo systemctl daemon-reload.
Reinicia el servicio: sudo systemctl restart mi_app.service.

Patrones Más Seguros para Servicios Reales

Una unidad que funciona no siempre es una unidad que quieras mantener durante años. Estos patrones previenen errores comunes:

Ejecuta en primer plano. Deja que systemd supervise el proceso principal. Evita nohup, screen, tmux, & en segundo plano, o modos de demonio de aplicación dentro de ExecStart.
Mantén ExecStart directo. Si necesitas características del shell como tuberías o expansión de variables, llama a /bin/sh -c '...' intencionalmente. De lo contrario, ejecuta el ejecutable directamente.
Usa un usuario dedicado. Un servicio que solo necesita leer /opt/mi_app y enlazar a un puerto no privilegiado no debe ejecutarse como root.
Recarga después de editar la unidad. sudo systemctl daemon-reload es necesario cuando el archivo de unidad cambia.
Separa los despliegues de código de los cambios de unidad. Si solo cambió el código Python, reinicia el servicio. Si cambió la unidad, recarga systemd primero.

Solución de Problemas de una Nueva Unidad

Si el servicio falla, comienza con:

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

Los fallos comunes suelen ser simples:

status=203/EXEC a menudo significa que la ruta del ejecutable es incorrecta, el archivo falta o el archivo no es ejecutable.
Permission denied generalmente significa que el usuario del servicio no puede leer un archivo, entrar a un directorio, escribir registros o enlazar el puerto solicitado.
address already in use significa que otro proceso posee el puerto. Verifica con sudo ss -tulpen | grep ':8080'.
Un servicio que se inicia manualmente pero falla bajo systemd a menudo depende de variables de entorno, un directorio de trabajo diferente o archivos en tu directorio personal.

Puedes probar el comando como el usuario del servicio:

sudo -u usuariomiapp /usr/bin/python3 /opt/mi_app/app.py

Eso no es una reproducción perfecta del entorno de systemd, pero detecta errores obvios de la aplicación antes de que persigas detalles del archivo de unidad.

Una Variante Más Amigable para Producción

Para un servicio interno de larga duración, normalmente agregaría algunas barreras de seguridad:

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

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

[Install]
WantedBy=multi-user.target

ProtectSystem=full hace que gran parte del sistema sea de solo lectura para el servicio, así que agrega ReadWritePaths= solo para los directorios que la aplicación necesita genuinamente escribir. Prueba el endurecimiento una directiva a la vez. Las opciones de seguridad son útiles, pero un servicio que no puede leer su configuración o escribir sus datos fallará al iniciar.

Mejores Prácticas y Solución de Problemas

Rutas Absolutas: Siempre usa rutas absolutas para ExecStart, WorkingDirectory y cualquier otra ruta de archivo dentro de tu archivo de unidad. Las rutas relativas pueden llevar a comportamientos inesperados.
Usuarios Dedicados: Ejecuta servicios bajo cuentas de usuario no privilegiadas y dedicadas (por ejemplo, usuariomiapp) para mejorar la seguridad y limitar el daño potencial en caso de compromiso.
Registro Claro: Utiliza StandardOutput=journal y StandardError=journal para dirigir la salida del servicio al diario de systemd. Usa journalctl -u <nombre_servicio> para ver los registros.
Dependencias: Considera cuidadosamente After, Wants y Requires para asegurar que tu servicio se inicie en el orden correcto en relación con sus dependencias (por ejemplo, redes, bases de datos).
Prueba de Cambios: Antes de habilitar un servicio para que se inicie al arrancar, pruébalo a fondo iniciándolo y deteniéndolo manualmente. Verifica su estado y registros.
Límites de Recursos: Usa directivas como LimitNOFILE, LimitNPROC y MemoryMax cuando el servicio tenga límites conocidos o modos de fallo.
Variables de Entorno: Usa Environment= o EnvironmentFile= para valores de configuración que puedan cambiar o variar entre entornos, en lugar de codificarlos en el archivo de unidad o script.
Manejo de Errores en Scripts: Asegúrate de que los scripts de tu aplicación manejen los errores con gracia. Un código de salida distinto de cero activará Restart=on-failure.

Advertencia: Evita modificar archivos de unidad directamente en /usr/lib/systemd/system/. Cualquier cambio probablemente será sobrescrito por las actualizaciones de paquetes. Usa /etc/systemd/system/ para unidades personalizadas o anulaciones.

Una buena unidad personalizada es aburrida de la mejor manera: el comando es explícito, el usuario no tiene privilegios, el comportamiento de reinicio es intencional y los registros son fáciles de encontrar. Una vez que eso es sólido, los temporizadores de systemd, la activación de sockets y los controles más profundos de cgroup son los siguientes pasos naturales.