非正常关机

当 Unraid 检测到 array 没有在系统断电前正确停止时，就会出现不干净关机。这种情况可能会在下次启动时触发自动 parity check 以确保数据完整性。

Recommendations 防止不洁的关闭

采取一些主动的步骤可以帮助你避免或识别非正常关机：

• **使用不间断电源（UPS）：**确保服务器连接到UPS并设置在电池电量不足时自动关闭。
• **尝试优雅关闭：**如果您的服务器无响应，短按电源按钮以触发安全关闭。不要长按该按钮，因为这将强制硬关机并导致不洁关机。
• Enable persistent logging: Go to Settings → Syslog Server to activate logging that persists after a reboot. See Persistent logs (Syslog server) for more details.
• 附加诊断信息以获得支持： 如果发生非正常关机，Unraid 将尝试将诊断信息保存到您的闪存设备的 /log/diagnostics.zip 中。当您寻求帮助时，请将此文件附加到论坛帖子中。

UPS 配置最佳实践

配置良好的 UPS 是防止因掉电导致非正常关机的最佳防卫。

• 通过 USB 连接 UPS 到 Unraid 服务器。
• Enable UPS support in Settings → UPS Settings.
• **配置关机超时时间：**设置UPS以便在电池电量不足之前触发受控关机。调整“剩余电池运行时间”或“电池充电电平”阈值，以提供足够的时间让Unraid 停止array 并安全关机。
• 测试配置： 模拟掉电以确保 UPS 和 Unraid 的正确反应。

了解 NUT 插件，它可以更广泛地兼容更多高级 UPS 型号或未支持的硬件。

配置关机超时

Properly configuring shutdown timeouts is essential to ensure your Unraid server can stop all services effectively, preventing unclean shutdowns, particularly during power loss or maintenance. Each component of your system - VMs, Docker containers, and the overall array - has its own timeout setting that can be adjusted.

“意外的电源损失”

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.

备注

Unraid 支持大多数使用 apcupsd 协议 协议的 UPS 单元（APC 和 CyberPower 通常兼容）。如果您的 UPS 不受支持，建议使用来自社区应用程序的网络 UPS 工具（NUT）插件。

“闪存驱动器故障”

"array 状态存储在您的 USB 闪存设备上。如果闪存不可用或进入只读状态，Unraid 无法更新关机状态，即使 array 正确停止。这会导致在下次启动时检测出不干净关机。"

打开终端会话

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.

提示

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.

---

虚拟机超时时间

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.
   • 点击 应用。

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.

设置	默认值	When to increase	配置位置
VM 关机超时	60秒	300s if not using hibernation and VMs crash	Settings → VM Manager → VM Shutdown (Advanced)
Docker 容器停止超时时间	10秒	30s if any containers are crashing when stopped	Settings → Docker (Advanced)
通用关机超时时间	90秒	180s if you get unclean shutdowns, 300s+ with VMs	设置 → 磁盘设置 → 关机超时

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)

原理:

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

原理:

• 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.
• 如果定时器到期，容器将被强制停止。

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.

:::注意

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