Shutdown Tester

A system shutdown testing tool for Linux with RTC wake alarm support. This tool safely performs automated system shutdowns with automatic power-on via RTC wake alarm, enabling unattended shutdown/power-on cycle testing.

Features

• Configurable shutdown count: Set the exact number of shutdown cycles to perform
• RTC wake alarm: Automatically powers on the system after shutdown using hardware RTC
• Configurable wake delay: Set how long the system stays powered off (default: 2 minutes)
• Desktop detection: Waits for the graphical desktop to be ready before counting down
• Multiple safety mechanisms:
  • Kill switch file to emergency halt shutdowns
  • Maximum uptime detection (assumes user intervention if exceeded)
  • Consecutive failure tracking
  • RTC alarm verification before each shutdown
  • Automatic service disable on completion or abort
• Persistent state: Tracks progress across shutdown/power-on cycles
• RTC test mode: Verify RTC wake functionality before starting tests

Requirements

• Linux system with systemd (tested on Pop!_OS)
• Hardware RTC with wake alarm support
• BIOS/UEFI setting: "RTC Alarm Power On" or "Wake on RTC" set to "By OS"
• Rust toolchain (for building)
• Root privileges (for installation and execution)

BIOS/UEFI Configuration

Before using this tool, you must configure your BIOS/UEFI:

1. Enter BIOS/UEFI setup (usually F2, F10, or Del during boot)
2. Find power management or wake settings
3. Look for "RTC Alarm Power On", "Wake on RTC Alarm", or similar
4. Set it to "By OS" or "Enabled"
5. Save and exit

Without this setting, the system will not automatically power on after shutdown.

Installation

Quick Install

# Clone or download the project
cd shutdown-tester

# Build the binary (as normal user)
./build.sh

# Install (as root)
sudo ./install.sh

Manual Build & Install

# Build the binary (as normal user)
cargo build --release

# Install (as root)
sudo ./install.sh

Manual Installation (Without Scripts)

# Create directories
sudo mkdir -p /etc/shutdown-tester
sudo mkdir -p /var/lib/shutdown-tester

# Install files
sudo cp target/release/shutdown-tester /usr/local/bin/
sudo cp config.toml.example /etc/shutdown-tester/config.toml
sudo cp shutdown-tester.service /etc/systemd/system/

# Set permissions
sudo chmod 755 /usr/local/bin/shutdown-tester
sudo chmod 644 /etc/shutdown-tester/config.toml
sudo chmod 644 /etc/systemd/system/shutdown-tester.service

# Reload systemd
sudo systemctl daemon-reload

Configuration

Edit /etc/shutdown-tester/config.toml to customize behavior:

[shutdown]
# Total number of shutdown cycles to perform
target_count = 10

# Seconds to wait after desktop is ready before triggering shutdown
wait_after_desktop_seconds = 25

[rtc]
# Time in seconds before RTC wake alarm powers on the system
# Default: 120 seconds (2 minutes)
wake_delay_seconds = 120

# RTC device to use (most systems use rtc0)
rtc_device = "rtc0"

[safety]
# Maximum uptime before assuming user intervention (aborts test)
max_uptime_before_abort_seconds = 300

# Enable the kill switch file feature
enable_kill_switch = true

# Maximum consecutive failed boots before aborting
max_failed_boots = 3

[desktop]
# Detection method: "graphical-target", "display-manager", "dbus-session", "custom-command"
detection_method = "graphical-target"

# Custom command (only if detection_method = "custom-command")
custom_ready_command = ""

# Additional delay after desktop detection
post_detection_delay_seconds = 5

[logging]
log_file = "/var/log/shutdown-tester.log"
log_level = "info"
use_journal = true

[state]
state_directory = "/var/lib/shutdown-tester"

Usage

Test RTC Wake Functionality (Recommended First Step)

sudo shutdown-tester test-rtc

This sets a 30-second wake alarm. You can then manually shut down to verify your system powers back on automatically.

Start a Shutdown Test

sudo shutdown-tester start

This will:

1. Verify RTC wake alarm support
2. Initialize the test state
3. Enable the systemd service
4. Begin the first shutdown after a 10-second countdown

Check Status

sudo shutdown-tester status

Shows current test progress, RTC configuration, safety status, and shutdown history.

Stop a Test

sudo shutdown-tester stop

Immediately stops the shutdown test, disables the service, and clears any pending RTC alarm.

Reset State

sudo shutdown-tester reset

Clears all state, history, and any pending RTC alarms.

Safety Mechanisms

1. Kill Switch

Create the file /etc/shutdown-tester/STOP to immediately halt all shutdowns:

sudo touch /etc/shutdown-tester/STOP

The tool checks for this file before every shutdown.

2. Maximum Uptime Check

If the system has been running longer than max_uptime_before_abort_seconds (default: 300 seconds / 5 minutes), the tool assumes a user is actively using the system and aborts the test.

3. RTC Alarm Verification

Before each shutdown, the tool:

• Sets the RTC wake alarm
• Verifies the alarm was successfully programmed
• Only proceeds with shutdown if verification passes

4. Consecutive Failure Tracking

If the system fails to complete a power-on cycle multiple times (defined by max_failed_boots), the test is automatically aborted.

5. Automatic Service Disable

When a test completes (successfully or via abort), the systemd service is automatically disabled.

How It Works

1. Start: User runs shutdown-tester start
2. Initialize: Tool creates state file, enables systemd service
3. First Shutdown: System shuts down after 10-second countdown
4. RTC Wake: Hardware RTC powers on the system after configured delay
5. Boot Detection: On boot, systemd runs the service after graphical target
6. Desktop Wait: Tool waits for desktop to be ready
7. Countdown: Tool waits configured seconds (default: 25)
8. Shutdown: System shuts down if safety checks pass
9. Repeat: Steps 4-8 repeat until target count is reached
10. Complete: Service disables itself, test marked complete

Files and Directories

Path	Description
/usr/local/bin/shutdown-tester	Main executable
/etc/shutdown-tester/config.toml	Configuration file
/etc/shutdown-tester/STOP	Kill switch file (create to stop)
/var/lib/shutdown-tester/state.json	Persistent state
/etc/systemd/system/shutdown-tester.service	Systemd service
/var/log/shutdown-tester.log	Log file
/sys/class/rtc/rtc0/wakealarm	RTC wake alarm interface

Troubleshooting

System doesn't power back on

1. Verify BIOS/UEFI setting is "By OS" for RTC alarm
2. Test RTC functionality: sudo shutdown-tester test-rtc
3. Check if wakealarm interface exists: ls -la /sys/class/rtc/rtc0/wakealarm
4. Manually test: echo 0 > /sys/class/rtc/rtc0/wakealarm && echo $(($(date +%s) + 60)) > /sys/class/rtc/rtc0/wakealarm

Test won't start

1. Check you're running as root: sudo shutdown-tester start
2. Verify config file exists: cat /etc/shutdown-tester/config.toml
3. Check for existing test: sudo shutdown-tester status
4. Test RTC support: sudo shutdown-tester test-rtc

Shutdowns stopped unexpectedly

1. Check for kill switch: ls -la /etc/shutdown-tester/STOP
2. Check status for reason: sudo shutdown-tester status
3. Check journal logs: journalctl -u shutdown-tester.service

Want to abort immediately

Multiple options:

# Option 1: Use the stop command
sudo shutdown-tester stop

# Option 2: Create kill switch file
sudo touch /etc/shutdown-tester/STOP

# Option 3: Disable the service directly
sudo systemctl disable shutdown-tester.service

# Option 4: Clear RTC alarm manually
echo 0 | sudo tee /sys/class/rtc/rtc0/wakealarm

System stuck in shutdown loop - Pop!_OS (systemd-boot)

If you can't get to the desktop fast enough:

1. At boot, access systemd-boot menu (repeatedly tap Space on boot)
2. Boot from a live USB or recovery
3. Mount the OS partition
4. Create the kill switch: touch /path/to/mount/etc/shutdown-tester/STOP
5. Reboot normally

System stuck in shutdown loop - Ubuntu (GRUB)

1. At boot, access GRUB menu
2. Edit boot entry, add systemd.unit=rescue.target
3. Boot into rescue mode
4. Run: systemctl disable shutdown-tester.service
5. Or create: touch /etc/shutdown-tester/STOP
6. Reboot normally

Uninstallation

# Use the uninstall script
sudo ./uninstall.sh

# Or manually:

# Stop any active test
sudo shutdown-tester stop

# Disable and remove service
sudo systemctl disable shutdown-tester.service
sudo rm /etc/systemd/system/shutdown-tester.service
sudo systemctl daemon-reload

# Remove files
sudo rm /usr/local/bin/shutdown-tester
sudo rm -rf /etc/shutdown-tester
sudo rm -rf /var/lib/shutdown-tester

Differences from Reboot Tester

Feature	Reboot Tester	Shutdown Tester
Power state	System restarts	System powers off completely
Wake method	N/A (continuous power)	RTC hardware alarm
BIOS setup	Not required	Required (RTC Alarm = By OS)
Power cycle	Warm reboot	Cold boot
Use case	Test reboot stability	Test power-off/on cycles

License

This tool is provided as-is for system testing purposes. Use at your own risk.