Add optional Wake-on-LAN and remote shutdown support for backup repositories

[borg-codex-bot]

Goal

Add optional Wake-on-LAN and remote shutdown support for backup repositories. This should allow a backup job to wake a remote repository host, wait until the repository is reachable, run the backup, and optionally shut the host down again after a successful run.

Background

Some users keep backup targets on a separate NAS, Unraid server, or other remote host that is normally powered off. Today Borg Backup UI can fail clearly when the repository is unreachable, but it cannot help with powering the target on before a scheduled backup.

Borg Backup UI should support this as an explicit job-level feature. It must not silently treat every unreachable repository as a Wake-on-LAN target.

Proposed UX

Add a job-level section, for example Remote host control, in the wizard/edit flow.

Suggested fields:

• Enable remote host control
• Host identifier, for example backup-nas-01
• Wake-on-LAN enabled
• MAC address
• Optional broadcast address or network interface
• Wait time after sending WOL
• Maximum wait time until host/repository is reachable
• Reachability check mode:
  • Ping host
  • TCP port check, for example SSH port 22
  • Repository path reachable
  • Borg repository readable
• Optional shutdown after successful backup
• Optional shutdown command via SSH
• SSH host
• SSH user
• SSH key path
• Optional shutdown on failed backup, default off

The UI should make clear that shutdown is only attempted when this job woke the host itself.

Recommended implementation phases

Phase 1: Wake before backup

• Add job metadata for remote host control.
• Send Wake-on-LAN magic packet before the backup when enabled.
• Wait and retry reachability checks before starting Borg.
• Fail the job with a clear error if the host or repository does not become reachable.
• Log all steps without exposing secrets.
• No automatic shutdown in this phase.

Phase 2: Optional shutdown after successful backup

• Add SSH-based shutdown after a successful backup.
• Only shut down the host if the current job woke it.
• Default behavior: do not shut down after failed backups.
• Log shutdown success/failure clearly.
• Surface shutdown warnings in UI/history.

Phase 3: Shared remote host coordination

• Support a shared host identifier for multiple jobs.
• Add locking/reference tracking so one job cannot shut down a host while another job using the same host is running.
• Consider pending scheduled jobs before shutdown if practical.

Technical analysis

Wake-on-LAN can be implemented without external dependencies by sending a UDP magic packet from Python. Configuration should stay in the job metadata.

Shutdown should be more conservative. SSH is the most portable approach already aligned with repository workflows. Passwords should not be used directly; key-based SSH is preferred. Any secret material must use the existing secret handling model.

Reachability checks should be layered and explicit. A ping-only check is not enough to prove a Borg repository is usable. For remote filesystem targets, path checks may be enough. For SSH/Borg repositories, a Borg-level check gives the best signal but is slower.

The backup runtime must track whether it actually sent WOL for this job. Shutdown must depend on that runtime state, not only on static configuration.

Risks and safeguards

• Do not power off a host that was already running before the job started.
• Do not power off a shared host while another job is using it.
• Do not retry forever; use explicit timeouts.
• Do not hide WOL/shutdown failures.
• Do not log SSH secrets, tokens, passwords, or private key material.
• Keep the feature opt-in per job.

Acceptance criteria

• A job can be configured to send Wake-on-LAN before backup.
• The job waits until the selected reachability check succeeds or times out.
• If the target remains unreachable, the backup fails with a clear message.
• WOL steps are visible in logs.
• Optional SSH shutdown can be configured after successful backup.
• Shutdown is only attempted if the job woke the host itself.
• Secrets are not written to normal config files and are never logged.
• Multiple jobs using the same remote host can be protected from unsafe shutdown behavior, at least by a documented lock/host-id mechanism.

Open questions

• Should Phase 1 only support local path repositories, or also SSH repositories immediately?
• Which reachability check should be the default?
• Should shutdown be hidden until Wake-on-LAN is configured?
• Should this feature live in the wizard only, or also on the Storage page for profile-level defaults?

[borg-codex-bot]

Deferred to the post-publication phase. This feature needs a separate design and implementation pass because Wake-on-LAN and remote shutdown affect external systems.

[borg-codex-bot]

Architecture and implementation analysis

Analysis date: 2026-07-17
Analyzed baseline: main at commit 15c1f5b
Stable version at analysis time: v2026.07.16.1604

This comment records the agreed analysis so that the architecture and safety decisions do not have to be reconstructed later.

Assessment

This is not a small isolated feature. It affects job execution, canonical storage metadata, SSH handling, concurrency, runtime recovery, UI, migrations, exports, support bundles, logging, and documentation.

The current architecture already provides useful foundations:

• Jobs reference repositories through repository_key.
• Repositories reference storage targets through storage_key.
• Resource locking and stale-lock detection already exist.
• SSH transport options are constructed centrally.
• Job phases, live logs, and controlled cancellation already exist.
• Docker and VM recovery is persisted and visible in system health.

No framework, database, or directory-layout change is required.

Recommended ownership of configuration

Do not duplicate host credentials and network details in every job.

The physical remote-host configuration belongs to the storage target in storages.json. A job should only contain its policy for the selected storage target.

Suggested storage metadata:

{
  "remote_host_control": {
    "enabled": true,
    "host_identifier": "backup-nas-01",
    "wol": {
      "mac": "AA:BB:CC:DD:EE:FF",
      "broadcast": "192.168.1.255",
      "port": 9
    },
    "readiness": {
      "mode": "tcp",
      "host": "192.168.1.50",
      "port": 22,
      "initial_delay_seconds": 5,
      "poll_interval_seconds": 5,
      "timeout_seconds": 300
    },
    "shutdown": {
      "enabled": true,
      "preset": "unraid"
    }
  }
}

Suggested per-job policy:

{
  "remote_host_policy": {
    "enabled": true,
    "wake_before_backup": true,
    "shutdown_after_success": true,
    "shutdown_after_failure": false
  }
}

A stable host_identifier must be shared by all storage targets that represent the same physical host.

Recommended execution order

1. Acquire the normal job/repository locks and a shared remote-host:<host_identifier> lock.
2. Perform local checks that can fail without waking the remote system, including source-path and parity checks.
3. Perform a lightweight reachability check.
4. If the host is already reachable, record woken_by_this_run=false. The host must not be shut down later.
5. If the host is unreachable and WOL is enabled, persist runtime state before sending the magic packet.
6. Send the WOL packet and wait for the configured TCP service until the timeout expires.
7. Run the existing authoritative repository preflight or SMB mount after the service is reachable.
8. Stop configured Docker containers and VMs.
9. Run Borg create and configured repository maintenance.
10. Recover Docker containers and VMs.
11. Unmount SMB, if applicable.
12. Shut down the host only if the backup succeeded and the current run woke it.
13. Release the remote-host lock and finish the job.

The current runner mounts SMB before some local preflight checks. Host-controlled targets require a bounded reordering in api/wizard_runner.py: local preflight, remote host preparation, mount/repository preflight, workload stop, Borg, recovery, unmount, optional shutdown.

Reachability defaults

Use TCP as the default readiness method instead of ICMP ping:

• SSH storage: configured SSH port
• SMB storage: TCP port 445
• Ping: optional only

Ping can be blocked while the required service is available. Repeated Borg info calls should not be used as the wake-up polling loop. The normal repository preflight remains the final usability check.

Recommended defaults:

• Initial delay: 5 seconds
• Poll interval: 5 seconds
• Maximum wait: 300 seconds

Shutdown safety

The central safeguard is mandatory:

A host may only be shut down when the current job run previously woke that host.

Additional rules:

• If the host was already online, never shut it down.
• After a failed or cancelled backup, leave the host online by default.
• A shutdown failure must not convert a successful backup into a failed backup. Report a warning and preserve the successful backup result.
• Use SSH keys only. Do not add password-based remote shutdown.
• Reuse existing SSH host/user/key metadata where possible.
• An SMB target needs a reference to an SSH management profile because SMB credentials cannot power off the host.
• Do not offer arbitrary shell commands in the normal UI. Prefer allow-listed presets such as Unraid and generic systemd Linux. An advanced custom command should only be considered after an explicit separate decision.
• Strictly validate MAC addresses, ports, host identifiers, and timing ranges.

Concurrency

Extend the existing resource-lock system with:

remote-host:<host_identifier>

This lock must remain held from the reachability check until shutdown or final cleanup. It prevents two jobs from waking or shutting down the same physical host concurrently, including jobs that use different repositories or storage profiles.

For the initial implementation, a second simultaneous job should be skipped or rejected with a clear message. A new queue or transaction architecture is not required.

A later optimization may keep a host online for consecutive scheduled jobs, but that is not required for the safe first implementation.

Crash and recovery behavior

Persist a remote-host runtime entry before sending WOL. If Borg Backup UI or Unraid restarts after waking the host:

• Do not automatically shut down the remote host after restart.
• Show a system-health warning that the remote host may have been left online by an interrupted run.
• Allow the administrator to acknowledge the warning after checking the host.

Automatically powering off after an application restart is unsafe because the application can no longer prove that no other user or service is using the remote system.

UI placement

Settings / storage profiles

Add a Remote host control section to relevant SMB and SSH storage profiles:

• Enable remote-host control
• Host display name / stable host identifier
• MAC address
• Broadcast address and UDP port
• Readiness method, host, port, and timeout
• SSH management profile for shutdown
• Operating-system shutdown preset
• Test reachability
• Test WOL with an explicit confirmation because it changes an external system state

Job wizard

After selecting a configured remote storage target, show only policy controls:

• Wake target before backup
• Shut down target after successful backup
• Advanced and disabled by default: shut down after failure

Show a read-only summary of the selected host and readiness method. Do not duplicate MAC, SSH, or network fields in the job.

If the storage target has no remote-host configuration, show a link or guidance to the relevant Settings page.

Jobs, history, and live log

Expose clear phases and messages:

• Checking target host
• Sending Wake-on-LAN
• Waiting for target host
• Target host is ready
• Shutting down target host
• Shutdown failed
• Target left online after backup failure or cancellation

Record initial reachability, whether WOL was sent, readiness duration, shutdown attempt, and shutdown result. Never log secrets or private-key contents.

Cancellation behavior

Add explicit phases such as:

• waking_remote_host
• waiting_remote_host
• shutting_down_remote_host

Cancellation may be accepted while waking or waiting. Cancellation must be disabled while final recovery or remote shutdown is being completed.

If a cancellation occurs after WOL, run the normal local recovery and leave the remote host online unless a later explicitly approved policy says otherwise.

Migration and compatibility

Existing jobs and storage targets must remain disabled for this feature by default. The feature must never activate silently.

If the storage schema is increased, provide an idempotent migration that:

• backs up affected files,
• preserves every existing storage and job,
• adds only disabled/default metadata,
• writes the migration ID, timestamps, affected objects, actions, and sanitized errors to the migration audit log,
• succeeds without duplicate changes when run again.

Also update:

• profile and secret export/import,
• job export/import,
• support bundle generation,
• factory reset,
• system-health checks,
• German and English quick help,
• German and English user manuals.

Support bundles must pseudonymize MAC addresses, host/IP values, SSH users, and sensitive paths where applicable.

Expected error behavior

Situation	Expected behavior
Invalid or unreachable MAC/broadcast target	Fail before Docker/VM stop
Host does not become ready	Timeout with a clear user-facing error
Repository remains unavailable	Existing repository preflight fails normally
Backup fails	Host remains online by default
User cancels	Perform local recovery and leave host online
Shutdown fails	Backup remains successful, add warning/audit entry
Host was already online	Never shut it down
Second job targets the same host	Reject or skip with a clear host-lock message

Required tests

Automated tests:

• MAC validation and exact magic-packet bytes
• Broadcast and port validation
• TCP readiness retries, timeout, and cancellation
• Host already online: no WOL and no shutdown
• Host offline plus successful backup: exactly one shutdown attempt
• WOL timeout: no Docker/VM stop and no Borg execution
• Failed/cancelled backup: no shutdown by default
• Shutdown failure: warning while preserving backup success
• Shared host lock blocks unsafe overlap
• Stale host-lock recovery
• SSH command construction is injection-safe
• No secrets in logs or support bundles
• Migration success, idempotence, and failure behavior
• Import/export round trips
• API authentication and role checks

Manual tests on real hardware:

• Offline target: wake, backup, recover workloads, shut down
• Already-online target: backup and remain online
• Wrong MAC or blocked broadcast: clean timeout
• Slow SSH/SMB service startup
• Invalid SSH key or insufficient shutdown permission
• Two jobs for the same host
• User cancellation in each supported phase
• Docker/VM recovery before remote shutdown
• At least one SMB target and one SSH target

WOL and remote shutdown cannot be considered fully verified through mocks alone. A real Unraid/NAS test is required before stable promotion.

Recommended delivery structure

Keep issue #89 as the umbrella and implement it through these bounded subtasks:

1. Canonical storage/job model, migration, and Settings UI
2. WOL runtime, readiness checks, phases, and live status
3. SSH shutdown, audit trail, and recovery behavior
4. Shared host locking and concurrency tests
5. Export/import, support bundle, documentation, and full regression tests

Recommended initial product decisions:

• Support SMB and SSH storage targets first.
• Store host configuration on the storage target and policy on the job.
• Use TCP as the default readiness check.
• Shut down only after a successful backup.
• Shut down only if the same run woke the host.
• Do not allow arbitrary shutdown commands in the normal UI.
• Do not automatically shut down a host after an application restart.
• Do not build a complex job queue in the first version.

This feature should receive multiple test-channel iterations and explicit real-hardware approval before stable promotion.