SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Systemd no inicia: cómo leer el código de salida

Consulte systemctl status primero: 203/EXEC y 226/NAMESPACE indican fallos distintos, y una unidad puede iniciar bien pero terminar un segundo después.

Por qué no se inicia una unidad de systemd

Una unidad de systemd que no se inicia indica el motivo en un campo. Ejecute systemctl status <unit> y busque code= y status= en la línea que informa del fallo. Un código de estado de la serie 200 casi siempre significa que systemd nunca llegó a ejecutar el programa: falló al preparar el entorno que solicitaba el archivo de unidad. Si la línea muestra code=exited con un estado inferior a 200, el programa sí se ejecutó y terminó por su cuenta. Por tanto, el archivo de unidad probablemente es correcto y el problema está en la aplicación. code=killed significa que una señal terminó el proceso. Es un caso distinto que se trata cerca del final.

Esa distinción determina el procedimiento. Todo lo que sigue se basa en ella y mantiene el orden en que aparecen los códigos.

Qué tres comandos responden a la pregunta, en orden

systemctl status myapp.service
journalctl -u myapp.service -b --no-pager
systemd-analyze verify /etc/systemd/system/myapp.service

systemctl status da el veredicto. Lea primero la línea Loaded:, porque indica el archivo que systemd analizó realmente y si la unidad está habilitada, enmascarada o no se ha encontrado. Después, lea la línea Active: y el par code= y status= que aparece debajo.

journalctl -u myapp.service -b --no-pager proporciona los detalles. -u filtra esa unidad concreta, -b limita la salida al arranque actual para que no lea un fallo de la semana pasada y --no-pager imprime directamente en el terminal, de modo que pueda canalizar la salida a grep. status muestra sólo las últimas líneas del registro y acorta las líneas largas. El journal muestra todo lo que el programa escribió antes de finalizar, que suele ser el error real. Sin -n obtiene todas las entradas de este arranque. Añada -n 100 para conservar sólo las 100 más recientes o ejecútelo con -f en un segundo terminal mientras reinicia la unidad.

systemd-analyze verify carga un archivo de unidad sin ejecutarlo. Advierte sobre secciones y directivas desconocidas, y marca los comandos de ExecStart= que no puede ejecutar. Esto detecta las dos clases de errores silenciosos: una clave escrita incorrectamente, que systemd ignora al cargarla y sólo indica mediante una advertencia que la mayoría de las personas nunca lee, y una ruta inexistente.

Después de editar cualquier archivo de unidad, ejecute sudo systemctl daemon-reload. Hasta hacerlo, systemd sigue usando la copia que cargó antes y systemctl status añade una advertencia indicando que el archivo del disco ha cambiado. Una corrección que «no hizo nada» suele ser una corrección que systemd todavía no ha leído.

Hay otros dos comandos que también resultan útiles. systemctl cat myapp.service muestra la unidad efectiva, es decir, el archivo principal más todos los drop-ins de /etc/systemd/system/myapp.service.d/. systemctl show myapp.service -p ExecStart -p User -p WorkingDirectory muestra esos valores tal como los interpretó systemd, que es lo que se ejecutará realmente.

¿Qué significa status=203/EXEC?

203/EXEC indica que systemd terminó la configuración, llamó a execve() y el kernel rechazó la ejecución. El programa no llegó a ejecutar ninguna línea de su propio código. Cuatro causas cubren casi todos los casos.

  1. La ruta de ExecStart= es incorrecta o no es absoluta. Compruébela con ls -l y compárela con la cadena exacta del archivo de unidad.
  2. El archivo no tiene el bit de ejecución. sudo chmod +x /opt/myapp/run.sh lo corrige. Un archivo extraído de un archivo comprimido o copiado desde otra máquina suele perder ese bit.
  3. La línea shebang está dañada. El kernel lee la primera línea de un script y ejecuta el intérprete indicado allí. Por eso #!/usr/bin/env python3 falla cuando el PATH del servicio no contiene ningún python3, y un archivo guardado con finales de línea de Windows solicita un intérprete llamado /bin/bash\r, que no existe.
  4. El archivo no es algo que esta máquina pueda ejecutar: tiene una arquitectura incorrecta o es un archivo de texto sin ninguna línea shebang.

Reprodúzcalo manualmente, como el usuario del servicio, antes de cambiar nada.

sudo -u appuser /opt/myapp/run.sh
file /opt/myapp/run.sh
head -1 /opt/myapp/run.sh | cat -A

file muestra la arquitectura y devuelve "with CRLF line terminators" cuando el problema está en los finales de línea. cat -A muestra lo mismo mediante un ^M final. Elimínelos con sed -i 's/\r$//' /opt/myapp/run.sh.

Hay una salvedad importante sobre el rango: 200 o superior es una convención, no una garantía. Su propio programa puede terminar con el código 203, y systemd no puede distinguir ambos casos. systemd-analyze exit-status 203 muestra el nombre y la clase de cualquier código, lo que ayuda a leer la tabla, pero si la aplicación usa códigos de salida superiores a 199, cámbielos.

¿Por qué aparece 217/USER o 216/GROUP?

217/USER normalmente significa que la cuenta indicada en User= no existe cuando se inicia el servicio. El mismo código también incluye un fallo al configurar el espacio de nombres de usuarios para una opción de aislamiento como PrivateUsers=. En ese caso, el journal muestra "Failed to set up user namespacing" en lugar de indicar que falta un usuario. 216/GROUP representa el mismo fallo para Group= o SupplementaryGroups=. Confírmelo con un comando para cada caso.

getent passwd appuser
getent group appgroup

Cada comando muestra una línea o no muestra nada y devuelve un código distinto de cero. Si no muestra nada, el nombre no existe en el sistema. Por tanto, systemd no puede cambiar a esa cuenta y se detiene antes de ejecutar el proceso. La solución es crear la cuenta, no establecer User=root. Ejecutar un servicio con una cuenta de sistema dedicada con privilegios mínimos es precisamente el objetivo de esa directiva.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin appuser

DynamicUser=yes evita el problema haciendo que systemd asigne una cuenta temporal en cada inicio. Es adecuada para un servicio que no conserva estado. Todo lo que escriba archivos necesita StateDirectory= junto con ella, porque el ID de usuario cambia entre inicios y los archivos de una ruta normal terminan perteneciendo a una cuenta que ya no existe.

¿Qué es 226/NAMESPACE?

226/NAMESPACE procede de las directivas de aislamiento. Cuando una unidad define ProtectSystem=, ProtectHome=, PrivateTmp=, ReadWritePaths= o algo similar, systemd crea un espacio de nombres de montajes privado para ese servicio antes de ejecutar el programa. Aquí, un espacio de nombres es una vista privada del sistema de archivos para un proceso. Si falla cualquier montaje de ese plan, el arranque termina con 226 y el programa nunca se ejecuta.

La causa habitual es que no existe una ruta incluida en ReadWritePaths=. ProtectSystem=strict monta todo el sistema de archivos como de solo lectura y ReadWritePaths= vuelve a abrir las rutas indicadas con permisos de escritura. systemd no puede volver a abrir un directorio que no existe. Hay dos soluciones adecuadas. Permita que systemd cree el directorio con StateDirectory=, que crea /var/lib/<name> en cada arranque y se lo asigna al usuario del servicio, o anteponga - a la ruta para indicar a systemd que ignore esa entrada si falta el origen. La solución incorrecta es eliminar el aislamiento, porque convierte un problema de cinco minutos en uno permanente.

[Service]
ProtectSystem=strict
ProtectHome=yes
StateDirectory=myapp
ReadWritePaths=-/srv/uploads

Si no puede determinar qué línea es la responsable, elimine todo el bloque de aislamiento, recargue la configuración e inicie el servicio. Si el servicio arranca, vuelva a añadir las líneas una por una y reinicie después de cada cambio. Dos directivas relacionadas son 233/RUNTIME_DIRECTORY y 238/STATE_DIRECTORY. Indican que systemd no pudo crear o asumir la propiedad del directorio especificado en RuntimeDirectory= o StateDirectory=, normalmente porque esa ruta ya existe y pertenece a otro usuario.

¿Por qué aparece 200/CHDIR cuando WorkingDirectory parece correcto?

200/CHDIR indica que chdir() en WorkingDirectory= falló. El directorio no existe o el usuario del servicio no puede acceder a él. Para acceder a un directorio se necesita permiso de ejecución en ese directorio y en todos sus directorios padre. Por eso, un /home/deploy/app perfectamente legible resulta inaccesible cuando /home/deploy tiene el modo 700 y el servicio se ejecuta como appuser.

sudo -u appuser test -x /srv/myapp && echo ok
namei -l /srv/myapp

namei -l muestra el propietario y el modo de cada componente de la ruta. Es la forma más rápida de encontrar el directorio que bloquea el acceso al resto. Escribir WorkingDirectory=-/srv/myapp hace que la ausencia del directorio no sea fatal. Esto es adecuado para un programa al que no le importa desde dónde se inicia, pero no para uno que abre archivos mediante rutas relativas.

¿Por qué el servicio se inicia y se detiene un segundo después?

Aquí no aparece ningún código de la serie 200 y, a menudo, tampoco aparece ningún texto de error. La unidad muestra inactive (dead) justo después del inicio o pasa repetidamente por activating (auto-restart). systemd creó correctamente el entorno. La discrepancia está entre lo que hace el programa y lo que Type= indica que hará.

Type=simple, el valor predeterminado, indica que el programa permanece en primer plano. Si le proporciona un daemon que se bifurca al segundo plano y termina, systemd ve que finaliza el proceso principal y da por terminado el servicio. La mayoría de los daemons tienen una opción para permanecer en primer plano, como nginx -g 'daemon off;'.

Type=forking indica que el primer proceso termina cuando su proceso hijo está listo. Si le proporciona un programa que permanece en primer plano, el trabajo de inicio espera hasta que se agota TimeoutStartSec=, 90 segundos de forma predeterminada. Después, systemd lo termina y registra un tiempo de espera agotado.

Type=notify indica que el programa llama a sd_notify() para anunciar que está listo. Un programa que no admite este mecanismo no anuncia nada. Por eso, el inicio agota el tiempo de espera y el journal registra el resultado como un fallo de protocolo.

Elija el tipo según el comportamiento real del programa. Diferencias entre simple, forking, oneshot y notify es la decisión que resuelve toda esta clase de fallos.

Cuando un servicio termina una y otra vez, systemd deja de intentarlo e informa de que la solicitud de inicio se repitió demasiado rápido. La unidad queda en estado fallido y systemd no la reiniciará automáticamente. Puede iniciarla manualmente cuando haya transcurrido el intervalo del límite de frecuencia, o ejecutar sudo systemctl reset-failed myapp.service. Esto borra el estado fallido y el contador de reinicios, de modo que el inicio manual funciona de inmediato. Aumentar el límite sólo oculta el síntoma. Lea el journal desde el primer fallo, no desde el último, y consulte qué vuelve a intentar realmente Restart=on-failure antes de cambiarlo.

¿Por qué la unidad está inactiva sin mostrar ningún error?

Una unidad se puede omitir en lugar de iniciarse. Las directivas Condition* son silenciosas por diseño: cuando la comprobación falla, systemd marca el trabajo como correcto y no hace nada. Una unidad que contiene ConditionPathExists=/etc/myapp/config.yml nunca se iniciará mientras falte ese archivo, pero tampoco informará de ningún error.

systemctl show myapp.service -p ConditionResult -p ConditionTimestamp
journalctl -u myapp.service -b --no-pager | grep -i condition

ConditionResult=no confirma que la unidad se omitió, y el journal indica qué comprobación no se cumplió. Use una directiva Assert* cuando la falta de un requisito previo deba producir un error explícito. Condiciones, aserciones y orden de las unidades explica qué comprobación corresponde en cada caso.

Hay otros casos silenciosos relacionados. Un error «could not be found» suele indicar que el archivo está en el directorio incorrecto o que todavía no ha recargado la configuración: los archivos de unidad que cree deben estar en /etc/systemd/system/. Una unidad enmascarada rechaza cualquier inicio hasta que sudo systemctl unmask myapp.service la desbloquee. Además, systemctl enable falla si la unidad no tiene una sección [Install], así que debe añadirle WantedBy=multi-user.target.

¿Y si el proceso terminó porque lo mataron y no porque fallara?

code=killed es distinto de code=exited. Algo terminó el proceso desde fuera. status=9/KILL suele indicar que intervino el OOM killer y, cuando ocurre, el journal identifica el proceso que seleccionó. Sin embargo, SIGKILL no indica quién lo envió: systemd también lo envía cuando un servicio que se está deteniendo ignora SIGTERM después de TimeoutStopSec=. Por eso, compruebe si había un proceso de detención o reinicio en curso antes de atribuir la causa a la memoria. Un límite que haya configurado usted produce el mismo efecto dentro del cgroup (grupo de control). Compruebe la memoria libre del host con free -m y revise la unidad en busca de un MemoryMax=. MemoryMax, CPUQuota y los demás límites de cgroup explica qué límite termina un proceso y cuál sólo reduce su velocidad.

status=15/TERM justo después de intentar iniciar el servicio suele indicar que systemd agotó el tiempo de espera del inicio y terminó el proceso, lo que remite de nuevo a Type=.

Dos hábitos que evitan la mayoría de estos fallos

Use rutas absolutas en todas partes. systemd no ejecuta su shell de inicio de sesión, por lo que no existen .bashrc ni .profile, y tampoco hay un entorno virtual activado. $PATH para un servicio del sistema es una lista integrada y corta que no incluye /opt ni los shims de un gestor de versiones del lenguaje. Escriba /usr/bin/python3 o /opt/myapp/venv/bin/python completos. command -v myapp en su shell muestra la ruta que debe copiar. La misma regla se aplica a WorkingDirectory=, EnvironmentFile= y a todas las rutas de ReadWritePaths=.

ExecStart= no es un shell. systemd divide la línea en palabras y llama directamente a execve(). Las tuberías, redirecciones, comodines, &&, las comillas invertidas y ~ no tienen ningún significado: llegan al programa como argumentos literales. ExecStart=/usr/bin/myapp --flag > /tmp/out.log entrega > y /tmp/out.log a myapp, que después termina con un error de uso que no parece relacionado con systemd. Cuando necesite funciones del shell, invoque un shell.

ExecStart=/bin/sh -c '/usr/bin/myapp --flag | /usr/bin/tee -a /var/log/myapp.log'

Sólo para generar la salida no necesita hacer eso. La salida del servicio se envía al journal de forma predeterminada, y StandardOutput=append:/var/log/myapp.log escribe en un archivo sin usar ningún shell.

La expansión de variables está limitada de la misma forma. $MYVAR y ${MYVAR} se sustituyen a partir de Environment=, EnvironmentFile= y de las pocas variables que systemd establece por sí mismo, como $USER. Además, se expanden especificadores como % y %i. No se expande nada del shell de inicio de sesión. $HOME sólo se establece cuando la unidad tiene User=, mediante el valor predeterminado de SetLoginEnvironment=. Por tanto, un servicio que se ejecuta como root sin User= no tiene $HOME, salvo que lo establezca. Un EnvironmentFile= tampoco es un script de shell: export no debe aparecer en él, sus reglas de comillas son distintas de las de bash y la ausencia de un archivo provoca un error fatal, a menos que anteponga - a la ruta.

Resolverlo en un servidor en producción

Lea el código, demuestre la causa, cambie una sola cosa y reinicie. Ese orden importa más que conocer cada número, porque evita acumular tres cambios especulativos y perder el control de cuál de ellos ayudó. El mismo procedimiento sirve para las unidades que no escribió usted. Un temporizador que nunca se ejecuta depende de un servicio que nunca se inició, así que depure primero el servicio: un temporizador de systemd y el servicio que activa falla exactamente de las formas anteriores, y el temporizador oculta la salida hasta que la solicita en el journal.

FAQ

¿Qué significa status=203/EXEC en systemctl status?

systemd configuró todo lo que solicitaba la unidad, pero la llamada execve() falló, por lo que el programa nunca se inició. Compruebe cuatro aspectos, en este orden: que la ruta de ExecStart= exista y sea absoluta, que el archivo tenga el bit de ejecución, que el shebang indique un intérprete existente en el PATH del servicio y que el archivo use finales de línea Unix. file muestra "with CRLF line terminators" en el último caso. Esto convierte el nombre del intérprete en /bin/bash\r y hace que el kernel rechace el archivo.

¿Por qué mi servicio se inicia y se detiene inmediatamente?

El archivo de unidad promete un comportamiento que el programa no tiene. Con Type=simple, systemd espera que el programa permanezca en primer plano. Por tanto, un daemon que se bifurca en segundo plano parece haber terminado en cuanto se bifurca. Con Type=forking, systemd espera a que termine el primer proceso. Por tanto, un programa en primer plano hace que el trabajo de inicio quede bloqueado hasta que se agota TimeoutStartSec=. Haga coincidir Type= con el comportamiento del programa. Si el programa ofrece una opción para ejecutarse en primer plano, úsela con el valor predeterminado Type=simple.

¿Cómo puedo ver el error real en lugar de la salida de estado resumida?

systemctl status muestra sólo las últimas líneas del journal y acorta las líneas largas. Ejecute journalctl -u myapp.service -b --no-pager para obtener todo lo que la unidad registró durante este arranque, añada -n 200 para conservar sólo las 200 líneas más recientes o canalice la salida a grep. Si la aplicación escribe su propio archivo de registro, léalo también, porque systemd sólo captura lo que el programa envía a la salida estándar y al error estándar.

¿Por qué mi unidad está inactiva sin mostrar ningún mensaje de error?

Lo más habitual es que una directiva Condition* la haya omitido. Estas comprobaciones son silenciosas: si una condición falla, el trabajo de inicio se marca como correcto. Ejecute systemctl show myapp.service -p ConditionResult y busque ConditionResult=no. Después, lea la línea del journal que identifica la comprobación. La otra causa habitual es que la unidad esté enmascarada. En ese estado rechaza cualquier inicio hasta que sudo systemctl unmask elimine la máscara.

¿Necesito ejecutar daemon-reload después de cada cambio en un archivo de unidad?

Sí, para cualquier modificación de un archivo de unidad o de un drop-in. sudo systemctl daemon-reload hace que systemd vuelva a leer los archivos del disco. Después, sudo systemctl restart myapp.service aplica los cambios al servicio en ejecución. No es necesario ejecutarlo después de systemctl edit, que vuelve a cargar los archivos automáticamente. Tampoco es necesario después de cambiar un archivo de configuración de la aplicación en lugar de un archivo de configuración de systemd.

¿Te resultó útil este artículo?

#systemd#troubleshooting#journalctl#exit-codes#linux-fundamentals