Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
81 lines (51 loc) · 2.56 KB

ARCHITECTURE.md

File metadata and controls

81 lines (51 loc) · 2.56 KB
Raw

add_updategrub-service Architecture

Purpose

add_updategrub-service installs a small systemd shutdown integration that performs a complete GRUB configuration regeneration before shutdown, reboot, or halt.

The project addresses the gap between snapshot creation and the next boot. Snapshot watchers or package-manager hooks may refresh GRUB at other times, but this service provides a final distribution-neutral regeneration at the shutdown boundary.

Installed Components

add_updategrub-service.sh
        |
        +-- installs /opt/snapper/bin/update-grub-shutdown.sh
        |
        +-- installs /etc/systemd/system/updategrub-shutdown.service
        |
        +-- reloads systemd and enables the service

The helper executes:

grub-mkconfig -o /boot/grub/grub.cfg

The service is a Type=oneshot unit ordered before shutdown.target, reboot.target, and halt.target and enabled by those targets.

Installation Model

The installer must run as a normal user. It requests sudo only for operations that modify system locations or systemd state.

Installation is repeatable:

  1. Create /opt/snapper/bin when needed.
  2. Replace the installed helper with the current embedded version.
  3. Replace the systemd unit with the current definition.
  4. Reload the systemd manager.
  5. Enable the unit.
  6. Verify that the unit is enabled.

No background process is started by the installer. The oneshot helper runs only through the shutdown, reboot, or halt targets.

Compatibility Model

Version 1.0.1 uses grub-mkconfig directly instead of the Debian-specific update-grub wrapper. The output remains /boot/grub/grub.cfg, which is the layout validated by this project.

Testing covers Debian, Ubuntu, Kubuntu, and CachyOS, representing Debian/Ubuntu-based and Arch-based systems. Version 1.0.1 was specifically regression-tested on Debian and CachyOS after the command change.

The tested CachyOS system also had an active grub-btrfsd service and a Pacman GRUB hook. The shutdown service installed and operated successfully alongside both.

Failure Behavior

Both the installer and generated helper use strict shell error handling. A failed grub-mkconfig invocation causes the oneshot service to fail instead of reporting a successful update.

The installer verifies that the unit is enabled and exits nonzero if enablement fails.

Project Structure

add_updategrub-service/
├── ARCHITECTURE.md
├── README.md
└── add_updategrub-service.sh

License

The source file declares GPL-3.0-or-later.