Unclean shutdowns

An unclean shutdown happens when Unraid detects that the array was not properly stopped before the system powered off. This situation can trigger an automatic parity check during the next boot to ensure data integrity.

Recommendations to prevent unclean shutdowns

Taking some proactive steps can help you avoid or identify unclean shutdowns:

• Use a UPS: Keep your server connected to an Uninterruptible Power Supply (UPS) and set it up to initiate a controlled shutdown when battery power runs low.
• Attempt a graceful shutdown: If your server is unresponsive, briefly press the power button to trigger a safe shutdown. Do not hold the button down, as this will force a hard power off and lead to an unclean shutdown.
• Enable persistent logging: Go to Settings → Syslog Server to activate logging that persists after a reboot. See Persistent logs (Syslog server) for more details.
• Attach diagnostics for support: If an unclean shutdown occurs, Unraid will attempt to save diagnostics to /log/diagnostics.zip on your flash device. Attach this file to forum posts when you seek help.

UPS configuration best practices

A well-configured UPS is your best defense against unclean shutdowns caused by power loss.

• Connect the UPS via USB to your Unraid server.
• Enable UPS support in Settings → UPS Settings.
• Configure shutdown timeouts: Set the UPS to trigger a controlled shutdown before the battery runs low. Adjust the "Battery runtime left" or "Battery charge level" thresholds to provide enough time for Unraid to stop the array and power down safely.
• Test your configuration: Simulate a power loss to ensure the UPS and Unraid respond correctly.

Look into the NUT plugin for broader compatibility with more advanced UPS models or unsupported hardware.

Events That Cause Unclean Shutdowns

Understanding the main triggers for unclean shutdowns helps you prevent them. Explore the tabs below for details on each scenario.

Unexpected power loss

Power interruptions are one of the main reasons for unclean shutdowns. Protect your system with a properly configured UPS that can automatically shut down Unraid before the battery runs out.

note

Unraid supports most UPS units using the apcupsd Protocol protocol (APC and CyberPower are usually compatible). If your UPS isn't supported, consider using the Network UPS Tools (NUT) plugin from Community Applications.

Flash drive failure

The array status is stored on your USB flash device. If the flash drive becomes unavailable or enters a read-only state, Unraid cannot update the shutdown status, even if the array stops correctly. This results in an unclean shutdown being detected at the next boot.

Open terminal sessions

Unraid waits for all open terminal or SSH sessions to close during shutdown. If these sessions remain active and the shutdown timer expires, a forced shutdown occurs.

tip

The Dynamix Stop Shell plugin can automatically close lingering bash or SSH sessions, helping ensure a graceful shutdown. However, be cautious if there are ongoing write operations to the array.

---

Configuring shutdown timeouts

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

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.

Setting	Default	When to increase	Where to configure
VM shutdown timeout	60s	300s if not using hibernation and VMs crash	Settings → VM Manager → VM Shutdown (Advanced)
Docker container stop timeout	10s	30s if any containers are crashing when stopped	Settings → Docker (Advanced)
General shutdown timeout	90s	180s if you get unclean shutdowns, 300s+ with VMs	Settings → Disk Settings → Shutdown time-out

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)

How it works:

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

How it works:

• 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.
• If the timer expires, containers are force-stopped.

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.

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.