Por qué systemd no reinicia tu servicio
Restart= solo supervisa el proceso principal: un hijo muerto puede pasar inadvertido en el mismo cgroup. Revisa Type=, los límites y el journal.
La respuesta breve: las políticas de reinicio de systemd supervisan un proceso
Las políticas de reinicio de systemd supervisan un proceso por unidad: el proceso principal. Restart= lee el estado de salida de ese proceso y de los comandos breves que systemd ejecuta directamente a su alrededor, como ExecStartPre=, ExecStartPost= y ExecReload=. No lee nada más. El grupo de control de una unidad puede contener veinte procesos; uno de ellos puede terminar y la unidad seguir active (running) porque el proceso principal continúa activo. Para systemd no se ha producido ningún fallo, por lo que no se reinicia nada.
systemd sí conoce los demás procesos. Los termina cuando se detiene la unidad, cuenta su memoria dentro de los límites de la unidad, les aplica la cuota de CPU de la unidad y los muestra en systemctl status. Simplemente nunca lee su estado de salida. La lógica de reinicio y el cgroup son dos cosas distintas, y gran parte de esta guía trata sobre la diferencia entre ambas.
Qué contiene el cgroup y qué lee la lógica de reinicio
Un cgroup (grupo de control) es un objeto del kernel que contiene un conjunto de procesos. Cada unidad de servicio tiene uno, con el nombre de la unidad. Un proceso no puede salir de él. Los procesos hijo heredan el cgroup de su proceso padre, y un proceso sin privilegios no puede trasladarse a otro cgroup. Por eso systemd puede limpiar un daemon que crea procesos dos veces, algo que los scripts de init antiguos nunca podían hacer de forma fiable.
Observe ambos datos en paralelo:
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Restart -p RestartUSec myapp.servicesystemd-cgls muestra todos los procesos de la unidad. MainPID es el único número que lee la política de reinicio. Cuando esos dos valores no coinciden con su modelo mental, esa discrepancia es el fallo. MainPID=0 significa que systemd no tiene un proceso principal del que leer un estado de salida. Aun así, sigue realizando el seguimiento del cgroup, por lo que detecta cuándo desaparece el último proceso que contiene. Hasta entonces, la lógica de reinicio no tiene ningún estado de salida que evaluar.
Existe una excepción real a la regla del proceso principal. Si el asesino de procesos por falta de memoria del kernel termina cualquier proceso dentro del cgroup de la unidad, systemd lo detecta porque supervisa el archivo memory.events del cgroup. OOMPolicy= decide qué ocurre después, y su valor predeterminado es stop: se detiene toda la unidad, el resultado se registra como oom-kill y eso cuenta como un fallo, por lo que se activa Restart=on-failure. El journal lo indica claramente.
myapp.service: A process of this unit has been killed by the OOM killer.
myapp.service: Failed with result 'oom-kill'.Por tanto, un proceso hijo terminado por falta de memoria sí detiene la unidad, mientras que el mismo proceso hijo que termina por un fallo de segmentación no lo hace. Si establece límites de memoria para una unidad, consulte cómo se aplican MemoryMax y CPUQuota al cgroup de una unidad antes de ajustar la política de reinicio, porque esas dos funciones interactúan aquí y en ningún otro punto.
Cómo elige Type= el proceso principal
Type= en la sección [Service] no sólo controla el orden de inicio. Es la regla que decide qué PID (identificador de proceso) se convierte en MainPID. Esto equivale a decidir qué Restart= puede ver.
Type=simplees el valor predeterminado. El proceso que systemd bifurca desdeExecStart=es el proceso principal. systemd marca la unidad como iniciada inmediatamente, antes de saber siexecfuncionó. Un error tipográfico en la ruta del binario produce un trabajo de inicio correcto y, después,Main process exited, code=exited, status=203/EXECun momento más tarde.Type=execse comporta comosimple, pero el trabajo de inicio espera hasta queexechaya finalizado correctamente. Así, el error tipográfico anterior se convierte en un fallo de inicio real. Requiere systemd 240 o posterior. Ubuntu 20.04 y posteriores, y Debian 12, lo incluyen, pero Ubuntu 18.04, que sigue cubierto mediante Ubuntu Pro, incluye systemd 237 y no lo admite. Cuando esté disponible, prefiera este valor frente asimple.Type=forkingespera que el proceso deExecStart=bifurque un daemon en segundo plano y después termine. systemd espera a que termine el proceso padre y, a continuación, busca el daemon real. ProporcionePIDFile=. Sin este valor,GuessMainPID=(activado de forma predeterminada) sólo funciona cuando queda exactamente un proceso en el cgroup. Si quedan dos,MainPIDpermanece0.Type=notifyindica que el servicio llama asd_notify(3)y envíaREADY=1cuando puede atender tráfico. También puede enviarMAINPID=para entregar a systemd otro proceso que supervisar. ConType=notify,NotifyAccess=se establece enmain, a menos que elija otro valor. Por tanto, una notificación enviada por un proceso hijo se ignora y el journal muestra el PID desde el que se envió.Type=oneshotno tiene un proceso principal permanente. La unidad pasa a estar inactiva en cuanto terminaExecStart=, a menos que establezcaRemainAfterExit=yes. Aquí se rechazanRestart=alwaysyRestart=on-success, con el mensajeService has Restart= set to either always or on-success, which isn't allowed for Type=oneshot services. Refusing.. Se aceptan los demás valores, incluidoon-failure.
Conviene memorizar dos errores de Type=forking, porque cada uno deja una unidad que parece averiada sin una causa visible:
myapp.service: Can't open PID file /run/myapp.pid (yet?) after start: No such file or directory
myapp.service: New main PID 4711 does not belong to service, and PID file is not owned by root. Refusing.El primero significa que el daemon escribe su archivo PID en otra ubicación o lo escribe después de que systemd lo haya buscado. El segundo significa que el archivo PID identifica un proceso fuera del cgroup de la unidad. systemd se niega a adoptarlo porque, de otro modo, un archivo PID modificable permitiría hacer que systemd enviara señales a cualquier proceso del sistema.
Por qué un script envoltorio oculta la terminación de sus procesos secundarios
Esta es la estructura que plantea la pregunta del título.
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
waitLa unidad es Type=simple, por lo que el proceso principal es el shell. wait sin argumentos no devuelve el control hasta que todos los procesos secundarios terminan. Mate el proceso de trabajo y el shell seguirá esperando al proceso web. Por tanto, el shell no termina, MainPID tampoco termina y Restart= nunca se consulta. El cgroup contiene ahora un proceso menos, systemctl status muestra el árbol reducido y la unidad sigue en estado active (running). systemd no supervisa los cambios de ese árbol.
Una segunda versión del mismo error es más silenciosa:
ExecStart=/bin/sh -c 'export APP_ENV=production; /usr/local/bin/myapp'El proceso principal es el shell, no myapp. En systemctl stop, systemd envía SIGTERM al proceso principal, y un shell que espera a un proceso secundario en primer plano no reenvía la señal. La detención tarda entonces todo TimeoutStopSec, 90 segundos de forma predeterminada, y termina así:
myapp.service: State 'stop-sigterm' timed out. Killing.
myapp.service: Killing process 4711 (myapp) with signal SIGKILL.La solución es exec. Escriba exec /usr/local/bin/myapp y el shell será sustituido por el programa. Así, MainPID será el programa y las señales llegarán a él. Mejor aún, elimine el shell y use Environment= o EnvironmentFile= en la unidad. Tenga en cuenta que este error queda oculto cuando la cadena -c contiene un solo comando, porque bash y dash optimizan ambos ese caso y lo convierten en un exec directo. Añada un segundo comando a la cadena y el shell seguirá ejecutándose delante del programa.
Reprodúzcalo en un VPS de prueba en dos minutos
Guarde el envoltorio anterior como /usr/local/bin/two-children.sh, hágalo ejecutable con chmod +x y sustituya las dos rutas de programa por sleep 3600. Asigne una unidad al script con Type=simple y Restart=on-failure. Después, ejecute systemctl daemon-reload e inícielo. Ejecute systemd-cgls --unit two-children.service y anote los tres PID: el shell y sus dos procesos secundarios. Mate uno de los procesos secundarios con sudo kill <pid>. Compruebe de nuevo la unidad. El árbol tiene un proceso menos, el estado sigue siendo active (running) y el journal no muestra nada nuevo. Ahora ejecute sudo kill -9 <shell pid>. La unidad falla, el proceso secundario superviviente se limpia porque KillMode=control-group es el valor predeterminado y el journal muestra Scheduled restart job, restart counter is at 1.
Vocabulario completo de Restart= y cuándo es mejor on-failure que always
Restart= acepta uno de siete valores. La diferencia clave es qué se considera una salida limpia. systemd considera limpia la salida con el código 0, cualquier código incluido en SuccessExitStatus= y, para todos los tipos excepto Type=oneshot, las señales SIGHUP, SIGINT, SIGTERM y SIGPIPE. Todo lo demás, incluidas SIGKILL y SIGSEGV, se considera una salida incorrecta.
noes el valor predeterminado. La unidad nunca se reinicia por sí sola. Por eso, una unidad sin una líneaRestart=termina en el primer fallo y permanece detenida.on-successreinicia la unidad sólo después de una salida limpia.on-failurereinicia la unidad después de un código de salida distinto de cero, una señal incorrecta, un tiempo de espera al iniciar o detener la unidad, o la expiración del watchdog.on-abnormalreinicia la unidad después de una señal incorrecta, un tiempo de espera o la expiración del watchdog, pero nunca después de una salida normal con un código distinto de cero.on-abortreinicia la unidad sólo después de una señal incorrecta, es decir, después de un fallo.on-watchdogreinicia la unidad sólo cuando expiraWatchdogSec=.alwaysreinicia la unidad después de todos los casos anteriores, incluida una salida limpia con estado 0.
on-failure es el valor predeterminado adecuado para un daemon de ejecución prolongada. Recupera el servicio después de un fallo y deja sin reiniciar un exit 0 deliberado. always corresponde a un programa que termina limpiamente por motivos ajenos a su control, como un cliente de túnel que devuelve 0 cuando se desconecta el extremo remoto. El coste de always es que oculta errores: un servicio que se inicia, lee un archivo de configuración dañado, registra el error y termina con 0 simplemente vuelve a iniciarse. Con el intervalo predeterminado de 100 milisegundos, pronto alcanza el límite de frecuencia de inicio descrito más abajo y termina en estado fallido con start-limit-hit. Con un RestartSec= suficientemente largo para no superar ese límite, entra en un bucle indefinido. El único indicio es que aumenta el contador de reinicios.
SuccessExitStatus= cambia la separación entre salidas limpias e incorrectas. Borg termina con 1 cuando hay advertencias y con 2 cuando hay errores. Por eso, una unidad de backup sin SuccessExitStatus=1 se marca como fallida cada vez que omite un archivo ilegible. RestartPreventExitStatus= enumera los códigos que impiden un reinicio incluso con always. Es la forma correcta de indicar que un programa no debe volver a iniciarse. RestartForceExitStatus= hace lo contrario. Un trabajo de backup debe ejecutarse en una unidad Type=oneshot controlada por un temporizador, no en un bucle de reinicio. el par de servicio y temporizador que ejecuta un trabajo según un horario muestra la estructura que debe copiar.
Hay una advertencia sobre las pruebas. Si detiene el servicio con un kill <pid> simple, envía SIGTERM, que está incluido en la lista de salidas limpias. Por eso Restart=on-failure no hace nada y puede concluir que la configuración está dañada. Use kill -9 <pid> o systemctl kill -s SIGKILL myapp.service en su lugar. Recuerde también que ningún valor de Restart= se ejecuta después de systemctl stop ni cuando la unidad se detiene porque desaparece una dependencia BindsTo= o PartOf=. Un trabajo de detención no es un fallo.
RestartSec y el valor predeterminado de 100 milisegundos
RestartSec= es la pausa entre la detención de la unidad y el siguiente inicio por parte de systemd, y el valor predeterminado es de 100 milisegundos. Compruebe qué valor ha cargado realmente la unidad:
systemctl show -p RestartUSec -p StartLimitIntervalUSec -p StartLimitBurst myapp.serviceUna unidad que no haya definido este valor muestra RestartUSec=100ms, a menos que alguien haya cambiado DefaultRestartSec= en /etc/systemd/system.conf, que es el origen de un valor no definido. Este valor predeterminado es adecuado para un servicio que falla una vez y vuelve a iniciarse. Es incorrecto para un servicio que no puede iniciarse en absoluto, porque el primer inicio y los cuatro reinicios caben en bastante menos de un segundo si el programa falla inmediatamente, y eso consume los cinco inicios que permite el límite de tasa descrito a continuación. Para cualquier servicio que espere a una base de datos, un montaje o una ruta de red, establezca RestartSec=5s o un valor superior.
A fecha de octubre de 2026, systemd 254 y las versiones posteriores también ofrecen RestartSteps= y RestartMaxDelaySec=, que aumentan el retraso desde RestartSec= hasta un límite máximo a lo largo de ese número de intentos. Ubuntu 24.04 incluye systemd 255 y dispone de estas opciones. Debian 12 incluye systemd 252 y no las ofrece, aunque bookworm-backports incluye systemd 254. Los retrasos crecientes son la opción adecuada cuando la dependencia puede permanecer inactiva durante mucho tiempo.
Qué significa realmente "start request repeated too quickly"
Este es el estado que muchos lectores interpretan como que systemd se rinde de forma arbitraria. En realidad, es un contador. La regla es la siguiente: si una unidad se inicia más de StartLimitBurst= veces dentro de StartLimitIntervalSec=, systemd se niega a iniciarla de nuevo y la deja en estado failed. Los valores predeterminados son 5 inicios en 10 segundos.
El journal muestra la secuencia:
myapp.service: Scheduled restart job, restart counter is at 5.
myapp.service: Start request repeated too quickly.
myapp.service: Failed with result 'start-limit-hit'.
Failed to start myapp.service - My application.y systemctl start responde con la corrección ya preparada:
Job for myapp.service failed because start of the service was attempted too often. See "systemctl status myapp.service" and "journalctl -xeu myapp.service" for details. To force a start use "systemctl reset-failed myapp.service" followed by "systemctl start myapp.service" again.systemctl reset-failed myapp.service borra el contador y el estado failed. Sin este comando, un systemctl start simple seguirá siendo rechazado hasta que transcurra la ventana de StartLimitIntervalSec=, y los reinicios automáticos permanecerán desactivados hasta que algo vuelva a iniciar la unidad. Los inicios manuales también cuentan para el límite, por lo que varias ejecuciones impacientes de systemctl restart mientras edita un archivo de configuración pueden activarlo sin que se produzca ningún fallo del proceso.
La parte que induce a error: start-limit-hit nunca indica por qué fallaba el servicio. Sólo indica que falló repetidamente y en poco tiempo. La causa real aparece en las líneas anteriores del journal.
Ambos ajustes pertenecen a la sección [Unit]. Encontrará ejemplos que los colocan en [Service], una ubicación que las versiones antiguas de systemd aceptaban. Ahí empieza la confusión. Escríbalos en [Unit] y después pida a systemd que muestre lo que cargó con systemctl show, porque el valor cargado es el único que cuenta.
[Unit]
Description=My application
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Type=exec
ExecStart=/usr/local/bin/myapp
Restart=on-failure
RestartSec=10sEsto permite cinco intentos para la unidad dentro de una ventana de cinco minutos antes de que systemd se rinda. StartLimitIntervalSec=0 desactiva por completo el límite, y debe tener claro qué implica: un servicio que nunca puede iniciarse volverá a intentarlo indefinidamente y escribirá una entrada en el journal cada vez. Los valores predeterminados para todo el sistema se encuentran en /etc/systemd/system.conf como DefaultStartLimitIntervalSec= y DefaultStartLimitBurst=.
Hay otro ajuste relacionado que requiere una advertencia. StartLimitAction= decide qué ocurre cuando se alcanza el límite y acepta valores como reboot, reboot-force y poweroff. El valor predeterminado es none, que marca la unidad como failed y no modifica el estado de la máquina. En un VPS remoto, poweroff significa que el equipo permanecerá apagado hasta que abra la consola del proveedor.
Solución uno: un proceso por unidad
Esta es la respuesta en casi todos los casos. Si deben ejecutarse dos programas, escriba dos unidades. Cada una tendrá un proceso principal real, un estado de salida real y su propia política de reinicio. También tendrá registros, límites de recursos y contadores de reinicio independientes, que es lo que necesita a las tres de la mañana.
Exprese la relación entre las unidades en los archivos de unidad, no en un script de shell.
After=sólo ordena el inicio. No indica nada sobre los errores.Requires=inicia la otra unidad junto con esta y detiene esta unidad si la otra se detiene explícitamente.BindsTo=esRequires=más el caso que le interesa: esta unidad se detiene cuando la otra se detiene por cualquier motivo, incluido un fallo. Combínelo conAfter=, o el orden no estará definido.PartOf=propaga la detención y el reinicio hacia las dependencias, de modo quesystemctl restart myapp.targetalcanza todas las unidades que seanPartOf=de ella.Upholds=(systemd 249 y versiones posteriores, es decir, Ubuntu 22.04 y posteriores) mantiene en ejecución la unidad indicada: si se detiene, systemd la inicia de nuevo. Está sujeta al mismo límite de frecuencia de inicio que cualquier otra unidad.
Un worker que nunca debe ejecutarse sin su servidor API y que systemd mantiene activo mientras la API esté disponible:
# /etc/systemd/system/myapp-api.service
[Unit]
Description=myapp API server
Wants=network-online.target
After=network-online.target
Upholds=myapp-worker.service
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp serve
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target# /etc/systemd/system/myapp-worker.service
[Unit]
Description=myapp background worker
BindsTo=myapp-api.service
After=myapp-api.service
StartLimitIntervalSec=120
StartLimitBurst=5
[Service]
Type=exec
User=myapp
ExecStart=/usr/local/bin/myapp worker
Restart=on-failure
RestartSec=5sEl worker no tiene una sección [Install] y nunca se habilita manualmente. La unidad de la API lo incorpora mediante Upholds=, por lo que systemctl enable --now myapp-api.service es el único comando que debe ejecutar. Recargue la configuración y compruebe qué configuración ha creado systemd para el conjunto:
sudo systemctl daemon-reload
systemd-analyze verify /etc/systemd/system/myapp-worker.service
systemctl list-dependencies myapp-api.servicesystemd-analyze verify no muestra ninguna salida cuando el archivo es válido. Cualquier salida indica un problema, normalmente una clave que systemd no reconoce en la sección donde la escribió o una dependencia de una unidad que no existe.
Corrección dos: Type=notify, para que systemd conozca algo más que un PID
Si el programa admite el protocolo de notificaciones de systemd, úselo. Con Type=notify, el servicio indica a systemd cuándo está listo. Así, el orden de inicio es real y no depende de suposiciones. También puede enviar MAINPID= para indicar a systemd cuál es el proceso relevante, en lugar de señalar al proceso lanzador.
WatchdogSec= es la parte que justifica el esfuerzo. Configúrelo y el servicio deberá enviar WATCHDOG=1 mediante sd_notify(3) al menos con esa frecuencia. Cuando dejan de llegar los mensajes, systemd termina el servicio con SIGABRT y lo marca como fallido. Por tanto, Restart=on-failure o Restart=on-watchdog lo inicia de nuevo. Esta es la única forma integrada de reiniciar un proceso que sigue activo pero está bloqueado. Ninguna política basada en el código de salida puede detectar esa situación.
[Service]
Type=notify
NotifyAccess=main
ExecStart=/usr/local/bin/myapp serve
WatchdogSec=30s
Restart=on-failure
RestartSec=5sUna activación del watchdog aparece en el journal como myapp.service: Watchdog timeout (limit 30s)!, seguida de la terminación del proceso. Si, en cambio, la unidad permanece en activating (start) hasta que se agota TimeoutStartSec, READY=1 no llegó o no se contabilizó. Puede que el programa no admita el protocolo. También puede que NotifyAccess=main rechace una notificación enviada por un proceso hijo; el journal informa de ello con ambos PID. Otra posibilidad es que un proceso auxiliar enviara el mensaje y terminara antes de que systemd pudiera determinar a qué unidad pertenecía. Ese último mensaje se ignora incluso con NotifyAccess=all. La corrección debe hacerse en el programa: debe llamar a sd_notify_barrier() antes de que termine el proceso auxiliar.
Para el software que expone un endpoint HTTP de comprobación de estado, pero no admite sd_notify, las opciones correctas son una unidad de temporizador pequeña que consulte el endpoint y llame a systemctl restart, o dejar que un runtime de contenedores realice las comprobaciones. Para eso existen las comprobaciones de estado de Compose y su comportamiento de reinicio.
Solución tres: un supervisor dentro de la unidad, sólo cuando no hay alternativa
Algunos programas se distribuyen realmente como un conjunto de procesos controlados por un lanzador que no se puede dividir. En ese caso, se ejecuta un supervisor dentro de la unidad y se acepta la consecuencia: systemd supervisa al supervisor, el supervisor supervisa todo lo demás y la política de reinicio queda repartida en dos archivos.
La forma más habitual de este patrón es un runtime de contenedores. Una unidad de docker compose o podman sigue exactamente este modelo: la política de reinicio de cada contenedor se define en el archivo de Compose y la unidad de systemd sólo mantiene activo el runtime. Si ese es su caso, la unidad que inicia una pila de Compose durante el arranque muestra la versión funcional e incluye el motivo por el que Type=oneshot con RemainAfterExit=yes suele ser lo correcto en ese contexto.
El cgroup sigue siendo útil. Todo lo que inicia el supervisor permanece dentro del cgroup de la unidad, por lo que MemoryMax=, CPUQuota= y la limpieza al detenerse siguen abarcando todo el árbol de procesos. Sólo se delega la decisión de reinicio.
Independientemente del supervisor que elija, no configure Restart=always en la unidad externa y una política de reinicio agresiva dentro de ella sin analizar las consecuencias. Dos capas de lógica de reinicio, cada una con su propio retroceso, producen un servicio que entra en ciclos de reinicio durante minutos y un journal que no explica el motivo.
ExitType=cgroup no significa «reiniciar cuando muera cualquier proceso»
ExitType= (systemd 250 y versiones posteriores, por lo que Ubuntu 24.04 y Debian 12 lo incluyen) es la opción que aparece al buscar este problema, pero hace lo contrario de lo que su nombre sugiere. El valor predeterminado, ExitType=main, significa que el servicio se considera detenido cuando termina el proceso principal. ExitType=cgroup significa que el servicio se considera en ejecución hasta que termina el último proceso del cgroup.
Por tanto, ExitType=cgroup hace que una unidad sea menos sensible a la terminación de un proceso, no más. Es la opción adecuada para un programa que crea su proceso de trabajo real y termina el proceso padre sin escribir un archivo PID, situación en la que Type=forking no puede encontrar el daemon. Es la opción incorrecta para el fallo descrito aquí.
No existe ningún valor Restart= que signifique «reiniciar la unidad cuando muera cualquier proceso del cgroup». Si necesita ese comportamiento, debe usar un proceso por unidad. Si no puede dividir el programa y controla el script envoltorio, la opción más cercana es wait -n, que retorna en cuanto termina el primer proceso hijo:
#!/bin/bash
/usr/local/bin/myapp-web &
/usr/local/bin/myapp-worker &
wait -n
exit 1Ahora, la terminación de cualquier proceso hijo hace que el envoltorio termine con un estado distinto de cero, por lo que Restart=on-failure actúa. Es una solución de compromiso, no una corrección. Seguirá teniendo un único contador de reinicios para dos programas, un único flujo de registros y ninguna forma de reiniciar por separado la parte que falla.
Cómo inspeccionar lo que ocurrió realmente
Cuatro comandos, en este orden.
systemctl status myapp.service
systemd-cgls --unit myapp.service
systemctl show -p MainPID -p NRestarts -p Result -p ExecMainStatus myapp.service
journalctl -u myapp.service -b -o short-precisesystemctl status muestra el estado, el PID principal y el árbol de cgroups en una sola pantalla. Una unidad en buen estado muestra Active: active (running) y una línea Main PID: que identifica el proceso esperado. Si el árbol inferior incluye procesos que no reconoce o falta alguno que sí debería estar, ya tiene la respuesta.
systemd-cgls --unit muestra el mismo árbol sin truncarlo. Esto empieza a ser importante cuando una unidad mantiene más de unos pocos procesos.
systemctl show proporciona datos legibles por máquina. NRestarts= es el contador de reinicios. Es la forma más rápida de distinguir un servicio que se ha reiniciado cuarenta veces de otro que permanece activo desde el arranque. Result= contiene el último motivo del fallo: exit-code, signal, timeout, oom-kill, watchdog o start-limit-hit. ExecMainStatus= es el estado de salida sin procesar del último proceso principal.
El journal contiene la secuencia. Estas son las tres líneas que debe buscar:
myapp.service: Main process exited, code=exited, status=1/FAILURE
myapp.service: Failed with result 'exit-code'.
myapp.service: Scheduled restart job, restart counter is at 1.code=exited, status=N significa que el programa eligió devolver N, por lo que el fallo está en el programa o en su configuración. code=killed, signal=SEGV significa que se bloqueó. code=killed, signal=TERM normalmente significa que otro proceso le pidió que se detuviera. Esto no es un fallo y no activará Restart=on-failure. code=dumped significa que dejó un archivo core. coredumpctl list se lo mostrará cuando systemd-coredump esté instalado.
En más de una máquina, NRestarts es el dato que conviene recopilar periódicamente. Una unidad cuyo contador aumenta cada día está fallando cada día, aunque nadie lo haya detectado. Cuando administra más de dos o tres equipos, una forma coherente de ejecutar un comando en todos los servidores convierte esa suposición en un informe.
FAQ
¿Por qué systemctl indica que mi servicio está activo cuando el proceso ha terminado?
systemd supervisa un proceso por unidad de servicio, el proceso principal, y Restart= sólo lee el estado de salida de ese proceso. Todo lo demás que inicia la unidad permanece en el mismo cgroup. systemd terminará esos procesos cuando la unidad se detenga, pero nunca supervisa si terminan por su cuenta. Ejecute systemctl show -p MainPID myapp.service y compare el número con systemd-cgls --unit myapp.service. Si el proceso que terminó aparece en el árbol, pero no está MainPID, systemd se comportó exactamente como está diseñado. La solución consiste en usar un proceso por unidad y definir la relación mediante BindsTo= y Upholds= entre las unidades.
¿Qué significa «start request repeated too quickly»?
Significa que la unidad se inició más de StartLimitBurst= veces dentro de StartLimitIntervalSec=. El valor predeterminado es 5 inicios en 10 segundos, por lo que systemd dejó de intentarlo. Es un límite de frecuencia y no indica por qué fallaba el servicio. Por tanto, lea las líneas anteriores del journal. Borre el estado con systemctl reset-failed myapp.service y corrija el fallo subyacente. Si el servicio espera a que algo lento se inicie, aumente RestartSec=, porque el intervalo predeterminado de 100 milisegundos consume los cinco intentos en menos de un segundo.
¿Debo usar Restart=always o Restart=on-failure?
Use on-failure en casi todos los casos. Reinicia el servicio después de un fallo, una salida distinta de cero, un tiempo de espera o un aviso del watchdog, pero no reinicia el servicio después de un exit 0 deliberado. Use always sólo cuando el programa termine correctamente por motivos que no puede controlar, como un cliente que devuelve 0 cuando su peer se desconecta. El problema de always es que un servicio que lee una configuración dañada, registra un error y termina con 0 se inicia una y otra vez. Con el intervalo predeterminado, pronto fallará con start-limit-hit. Con un RestartSec= más largo, puede entrar en un bucle indefinido, mientras NRestarts aumenta en systemctl show como único síntoma visible.
¿Por qué terminar manualmente mi proceso no activa un reinicio?
Porque, para todos los tipos excepto Type=oneshot, systemd considera SIGHUP, SIGINT, SIGTERM y SIGPIPE salidas correctas, y un kill <pid> normal envía SIGTERM. Con Restart=on-failure, una salida correcta no es un fallo, por lo que nada se reinicia y parece que la configuración está dañada cuando no lo está. Pruebe con kill -9 <pid> o systemctl kill -s SIGKILL myapp.service, que producen una terminación incorrecta y sí activan la política. La misma regla explica por qué systemctl stop nunca interfiere con la política de reinicio.
¿Dónde se configuran StartLimitIntervalSec y StartLimitBurst?
En la sección [Unit]. La documentación antigua y las versiones antiguas de systemd los situaban en [Service], por lo que los ejemplos copiados no coinciden entre sí. No suponga cuál acepta su versión. Después de systemctl daemon-reload, pregunte a systemd qué ha cargado con systemctl show -p StartLimitBurst -p StartLimitIntervalUSec myapp.service y considere esos valores como la referencia válida. systemd-analyze verify /etc/systemd/system/myapp.service detecta las claves que systemd no reconoce y no muestra nada cuando el archivo es correcto.