Arrêts imprévus

Un arrêt inopiné se produit lorsque Unraid détecte que le array n'a pas été correctement arrêté avant que le système ne s'éteigne. Cette situation peut déclencher un parity check automatique lors du prochain démarrage pour garantir l'intégrité des données.

Recommendations pour prévenir les arrêts non propres

Prendre des mesures proactives peut vous aider à éviter ou à identifier les arrêts imprévus :

• Utilisez un onduleur : Gardez votre serveur connecté à un appareil d'alimentation sans interruption (UPS) et configurez-le pour initier un arrêt contrôlé lorsque l'alimentation de la batterie est faible.
• Tentez un arrêt en douceur : Si votre serveur ne répond pas, appuyez brièvement sur le bouton d'alimentation pour initier un arrêt sécurisé. Ne maintenez pas le bouton enfoncé, car cela provoquerait une coupure d'alimentation brutale et entraînerait un arrêt inopiné.
• Enable persistent logging: Go to Settings → Syslog Server to activate logging that persists after a reboot. See Persistent logs (Syslog server) for more details.
• Joindre des diagnostics pour le support : Si un arrêt non sécurisé se produit, Unraid tentera de sauvegarder les diagnostics dans /log/diagnostics.zip sur votre périphérique flash. Joignez ce fichier à vos publications dans le forum lorsque vous demandez de l'aide.

UPS meilleures pratiques de configuration

Un onduleur bien configuré est votre meilleure défense contre les arrêts imprévus dus à une perte d'alimentation.

• Connectez l'onduleur via USB à votre serveur Unraid.
• Enable UPS support in Settings → UPS Settings.
• Configurer les délais d'arrêt : Configurez l'onduleur pour déclencher un arrêt contrôlé avant que la batterie ne soit faible. Ajustez les seuils de « temps d'exécution restant de la batterie » ou « niveau de charge de la batterie » pour laisser suffisamment de temps à Unraid pour arrêter le array et pour éteindre en toute sécurité.
• Testez votre configuration : Simulez une perte de puissance pour garantir que l'onduleur et Unraid réagissent correctement.

Consultez le plugin NUT pour une compatibilité étendue avec des modèles UPS avancés ou du matériel non pris en charge.

Configurer les délais d'arrêt

La configuration appropriée des délais d'arrêt est essentielle pour garantir que votre serveur Unraid peut arrêter tous les services efficacement, évitant ainsi les arrêts inopinés, notamment en cas de panne de courant ou de maintenance. Chaque composant de votre système - VMs, conteneurs Docker, et le array global - a son propre paramètre de délai qui peut être ajusté.

Perte de puissance inattendue

Les interruptions de courant sont l'une des principales raisons des arrêts non propres. Protégez votre système avec un onduleur configuré correctement qui peut arrêter automatiquement Unraid avant que la batterie ne se décharge.

note

Unraid prend en charge la plupart des unités UPS utilisant le protocole apcupsd (APC et CyberPower sont généralement compatibles). Si votre UPS n'est pas pris en charge, envisagez d'utiliser le plugin Network UPS Tools (NUT) de Community Applications.

Défaillance du lecteur flash

Le statut de array est stocké sur votre dispositif USB. Si la clé USB devient indisponible ou passe en mode lecture seule, Unraid ne peut pas mettre à jour le statut d'arrêt, même si l'array s'arrête correctement. Cela entraîne la détection d'un arrêt incorrect au prochain démarrage.

Ouvrir des sessions terminal

Unraid attend que toutes les sessions terminales ou SSH ouvertes se ferment lors de l'arrêt. Si ces sessions restent actives et que le minuteur d'arrêt expire, un arrêt forcé se produit.

astuce

Le plugin Dynamix Stop Shell peut automatiquement fermer les sessions bash ou SSH persistantes, aidant ainsi à garantir une fermeture en douceur. Cependant, soyez prudent si des opérations d'écriture sont en cours sur le array.

---

Délai des machines virtuelles

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.
   • Cliquez sur Appliquer.

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.

Paramètre	Par défaut	When to increase	Où configurer
Délai d'arrêt de VM	60s	300s if not using hibernation and VMs crash	Paramètres → Gestionnaire de VM → Arrêt VM (Avancé)
Délai d'arrêt des conteneurs Docker	10s	30s if any containers are crashing when stopped	Paramètres → Docker (Avancé)
Délai d'arrêt général	90s	180s if you get unclean shutdowns, 300s+ with VMs	Paramètres → Paramètres disque → Délai d'arrêt

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)

Comment ça fonctionne:

• 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)

Comment ça fonctionne:

• 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 le temps imparti expire, les conteneurs sont arrêtés de force.

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.

précaution

• 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.