Apagados no limpios

Un cierre no limpio ocurre cuando Unraid detecta que el array no se detuvo correctamente antes de que el sistema se apagara. Esta situación puede desencadenar una parity check automática durante el próximo arranque para garantizar la integridad de los datos.

Recommendations para prevenir apagados no limpios

Tomar algunas medidas proactivas puede ayudarte a evitar o identificar apagados no limpios:

• Usa un SAI: Mantén tu servidor conectado a un Sistema de Alimentación Ininterrumpida (SAI) y configúralo para iniciar un apagado controlado cuando la energía de la batería sea baja.
• Intentar un apagado ordenado: Si su servidor no responde, presione brevemente el botón de encendido para activar un apagado seguro. No mantenga el botón presionado, ya que esto forzará un apagado duro y provocará un apagado no limpio.
• Enable persistent logging: Go to Settings → Syslog Server to activate logging that persists after a reboot. See Persistent logs (Syslog server) for more details.
• Adjuntar diagnósticos para soporte: Si ocurre un apagado no limpio, Unraid intentará guardar los diagnósticos en /log/diagnostics.zip en su dispositivo de flash. Adjunte este archivo a las publicaciones en el foro cuando busque ayuda.

UPS mejores prácticas de configuración

Un SAI bien configurado es tu mejor defensa contra apagados no limpios causados por pérdida de energía.

• Conecta el SAI vía USB a tu servidor Unraid.
• Enable UPS support in Settings → UPS Settings.
• Configurar tiempos de espera de apagado: Configure el SAI para que desencadene un apagado controlado antes de que la batería se agote. Ajuste los umbrales de "Tiempo restante de la batería" o "Nivel de carga de la batería" para proporcionar tiempo suficiente para que Unraid detenga el array y se apague de forma segura.
• Prueba tu configuración: Simula una pérdida de energía para asegurarte de que el SAI y Unraid respondan correctamente.

Consulte el plugin NUT para obtener una mayor compatibilidad con modelos UPS más avanzados o hardware no compatible.

Configuración de tiempos de apagado

Configurar correctamente los tiempos de espera de apagado es esencial para asegurar que su servidor Unraid pueda detener efectivamente todos los servicios, previniendo apagados no limpios, especialmente durante pérdidas de energía o mantenimiento. Cada componente de su sistema - VMs, contenedores de Docker, y el array general - tiene su propia configuración de tiempo de espera que puede ajustarse.

Pérdida de energía inesperada

Las interrupciones de energía son una de las principales razones de apagados no limpios. Protege tu sistema con un SAI (Sistema de Alimentación Ininterrumpida) configurado correctamente que pueda apagar automáticamente Unraid antes de que se agote la batería.

nota

Unraid admite la mayoría de las unidades UPS utilizando el protocolo apcupsd (APC y CyberPower suelen ser compatibles). Si tu UPS no es compatible, considera usar el complemento Network UPS Tools (NUT) de Community Applications.

Fallo de unidad flash

El estado de array se guarda en tu dispositivo USB. Si la unidad flash se vuelve inaccesible o entra en un estado de solo lectura, Unraid no puede actualizar el estado de apagado, incluso si el array se detiene correctamente. Esto resulta en un apagado incorrecto que se detecta en el próximo arranque.

Abrir sesiones de terminal

Unraid espera que todas las sesiones abiertas de terminal o SSH se cierren durante el apagado. Si estas sesiones permanecen activas y el temporizador de apagado expira, se produce un apagado forzado.

consejo

El plugin Dynamix Stop Shell puede cerrar automáticamente sesiones de bash o SSH que estén sin actividad, ayudando a asegurar un apagado ordenado. Sin embargo, tenga cuidado si hay operaciones de escritura en curso en el array.

---

Tiempo de espera para máquinas virtuales

Properly configuring shutdown timeouts is essential to ensure your Unraid server can stop all services effectively. This prevents unclean shutdowns, especially during power loss or maintenance. The most important step is to configure your VMs to hibernate instead of shutting down. This approach helps eliminate many timeout-related issues.

VM hibernation setup

Use VM hibernation

For the most reliable and fastest shutdowns, configure your VMs to hibernate instead of shutting down. This is especially important for Windows VMs but benefits all VM types.

We recommend using hibernation because it:

• Saves VM state instantly - No waiting for the guest OS to shut down.
• Prevents data loss - No risk of interrupting updates or unsaved work.
• Avoids timeout issues - Hibernation is nearly instantaneous.
• Faster recovery - VMs resume exactly where they left off.

Shutdown can be problematic because:

• Windows may display dialog boxes ("Save this document?") that halt the shutdown indefinitely.
• Windows updates can take 10+ minutes during shutdown.
• If the timeout expires, Unraid force-kills the VM, potentially corrupting in-progress Windows updates, unsaved documents, application data, and file systems in the guest OS.

Critical requirement: Ensure the QEMU Guest Agent is installed in the VM for hibernation to function correctly.

To enable VM hibernation:

Windows VMs

1. Download QEMU Guest Agent:

   • Go to the VirtIO drivers download page.
   • Download the latest virtio-win.iso file.

2. Install in Windows VM:

   • Mount the virtio-win.iso to your VM.
   • Run the installer from the mounted ISO.
   • Install both VirtIO drivers AND QEMU Guest Agent.
   • Restart the VM.

3. Configure in Unraid:

   • Go to your VM settings in the VMs tab.
   • Set Shutdown Action to Hibernate.
   • Haga clic en Aplicar.

Linux VMs

1. Install QEMU Guest Agent:

# Ubuntu/Debian
sudo apt install qemu-guest-agent

# CentOS/RHEL/Fedora
sudo yum install qemu-guest-agent
# or
sudo dnf install qemu-guest-agent

2. Enable the service:

   sudo systemctl enable qemu-guest-agent
   sudo systemctl start qemu-guest-agent

3. Configure in Unraid:

   • Set Shutdown Action to Hibernate in your VM settings.

Appliance VMs

Some VMs, like Home Assistant, don't allow the installation of additional software. For these:

• Keep Shutdown Action set to Shutdown.
• Use longer timeout values (see timeout recommendations below).
• Consider the risks of force-killing these VMs during updates.

Why appliance VMs are different

Appliance VMs are designed to run specific software and often don't allow the installation of additional packages, such as QEMU Guest Agent. This means hibernation isn't available, so you'll need to rely on proper timeout configuration.

Now to verify your hibernation works, start your VM and open some applications. Then stop it from Unraid. When you start it again, it should resume with all applications still open.

Guest Agent is critical

Without the QEMU Guest Agent installed, hibernation may not work properly. In that case, the VM will revert to shutdown mode, consuming the full timeout period.

Timeout configuration

In this section, we’ll cover how to configure timeouts for various systems and processes. This information is important to ensure that your VMs and Docker containers shut down gracefully without data loss.

Configuración	Defecto	When to increase	Dónde configurar
Tiempo de espera para apagado de VM	60s	300s if not using hibernation and VMs crash	Configuración → Gestor de VM → Apagado de VM (Avanzado)
Tiempo de espera para detener contenedor Docker	10s	30s if any containers are crashing when stopped	Configuración → Docker (Avanzado)
Tiempo de espera general de apagado	90s	180s if you get unclean shutdowns, 300s+ with VMs	Configuración → Configuración de Disco → Tiempo de espera para apagado

When to increase timeouts

If you're experiencing unclean shutdowns or containers that crash during shutdown, consider increasing the general shutdown timeout to 180 seconds (or 300+ seconds if you have multiple VMs). This gives services more time to shut down gracefully.

Shutdown sequence

When shutting down, the process happens in the following order:

1. VM shutdown: This involves three stages, and each one can take up to the VM timeout:

   • Stage 1: Resume any paused VMs
   • Stage 2: Hibernate VMs that are set up for hibernation
   • Stage 3: Shut down any remaining VMs

   All VMs in each stage are processed at the same time, meaning the total shutdown time can be calculated as: VM timeout × 3.

2. Docker containers stop: All containers will stop simultaneously (total time = Docker timeout).

3. Other services: This includes tasks like LXC containers and third-party plugins, which usually take a few seconds.

4. Array shutdown: Drives need to be unmounted and data synced; this typically takes 15-30 seconds.

Calculate your general shutdown timeout

Formula: Your general shutdown timeout should be greater than:

(VM timeout × 3) + (Docker timeout) + (Other services) + 15-30 seconds

Example: If we follow the formula, it would look like this: (300 × 3) + 30 + 10 + 30 = 970 seconds (over 16 minutes).

Recommended: At least 180 seconds (3 minutes) at minimum and 300+ seconds (5+ minutes) if you have multiple VMs or complex containers.

If all your VMs are set to hibernate rather than shutting down, then the VM timeout is less critical since hibernation is nearly immediate. You could use a lower VM timeout (for example, 60-120 seconds) as a backup for any VMs that don’t support hibernation.

Detailed configuration guide

This section provides in-depth information about configuring timeouts for different system components. Each timeout setting works together to ensure your server shuts down gracefully without data loss.

VM Timeouts

Where to set: Settings → VM Manager → VM Shutdown (enable Advanced view)

Cómo funciona:

• VMs go through three shutdown stages, each consuming the full VM timeout
• All VMs in each stage are processed simultaneously
• Total VM shutdown time = VM timeout × 3

Common issues:

• Windows update interruptions: Updates during shutdown can be corrupted if timeout expires.
• Unsaved work: Dialog boxes asking to save documents can halt shutdown indefinitely.
• Hibernation failures: VMs without QEMU Guest Agent may fail to hibernate and use full timeout.

VM timeout recommendations

• Primary recommendation: Configure VMs to hibernate instead of shutting down (requires QEMU Guest Agent).
• If VMs crash during shutdown: Increase timeout to 300 seconds (5 minutes) for Windows VMs.
• Windows updates: Set Windows to install updates at startup rather than during shutdown.
• Test your setup: Manually stop your VMs to confirm they shut down or hibernate within the timeout period.

No safe timeout without hibernation

Without hibernation and QEMU Guest Agent, there isn't a truly safe timeout for Windows VMs. Dialog boxes or ongoing update installations could render any timeout inadequate, leading to forced shutdowns and data corruption risk.

Docker Timeouts

Where to set: Settings → Docker (enable Advanced view)

Cómo funciona:

• Containers are stopped in parallel, so total time equals the Docker stop timeout.
• Most containers stop within 10 seconds, but some may need more time.
• Complex containers with large databases or ongoing operations might require additional time.
• Si el temporizador expira, los contenedores se detienen forzosamente.

Docker timeout recommendations

• The default 10 seconds works well for most containers.
• If containers are crashing when stopped: Increase timeout to 30 seconds.
• Monitor your containers during shutdown to identify any that consistently need more time.

General Timeouts

Where to set: Settings → Disk Settings → Shutdown time-out

UPS considerations (most critical factor):

• Your UPS must provide enough runtime to complete the full shutdown sequence before battery runs out.
• For manual shutdown, you can set longer timeouts since you control when shutdown starts.
• With power outage shutdown, your timeout is limited by UPS battery life.
• Test your UPS by simulating a power outage to ensure your server shuts down cleanly with time to spare.

General timeout recommendations

• If you get unclean shutdowns: Increase to 180 seconds (3 minutes) for systems without VMs.
• For systems with VMs: Use 300+ seconds (5+ minutes) if not using hibernation.
• If using hibernation: 180-300 seconds is usually sufficient.
• Ensure timeouts are not longer than what your UPS can support during a power outage.

Third-party Services

LXC containers: The LXC plugin has its own timeout setting for stopping containers. Like Docker containers, LXC containers typically stop within a few seconds, but some may require more time. Check the LXC plugin settings for the container stop timeout and include this timeout in your general shutdown timeout calculation.

Other services: Some plugins or custom services may have their own shutdown procedures. Refer to the plugin documentation for specific timeout settings and incorporate them into your calculations.

Updated formula with third-party services:

(VM timeout × 3) + (Docker timeout) + (LXC/other timeouts) + 15-30 seconds

Dynamix Stop Shell plugin: If you frequently use SSH or terminal sessions, open sessions can prevent clean shutdowns because Unraid waits for them to close before proceeding.

The Dynamix Stop Shell plugin helps by automatically closing lingering bash or SSH sessions when the array is stopped, ensuring a timely shutdown.

You can install it from Community Applications (search for "Dynamix Stop Shell").

When to use the plugin

• If you regularly have terminal sessions open.
• To prevent forgotten SSH sessions from delaying shutdown.
• For automated cleanup during shutdown.

:::precaución

• Be cautious if you have scripts or processes running in terminal sessions.
• Ensure no critical write operations are in progress before shutdown.
• The plugin will forcefully close sessions, which could interrupt work. :::