RecoveryMain

1. Overview

The RecoveryMain module provides the recovery-mode integration layer for BastionGuard Backup.

Recovery mode launches the standard graphical interface and keeps the normal backup, restore, configuration, and wizard functions available. The module does not implement a separate recovery interface and does not directly alter the snapshot engine.

Its responsibilities are limited to:

  • Detecting whether the system was started in BastionGuard recovery mode
  • Displaying a recovery warning dialog after the main application window becomes visible
  • Informing the user that backup and restore operations remain available

The module is implemented in Vala and uses GLib and GTK.

2. Recovery Mode Design

The recovery environment uses the normal MainWindow instead of a dedicated recovery-only window.

All standard functions remain available, including:

  • Creating a new backup from the currently running live system
  • Restoring an existing snapshot
  • Opening the guided configuration wizard
  • Configuring the backup device
  • Accessing the normal application settings

The operational difference between a normal start and a recovery start is the informational warning displayed when the graphical interface opens.

3. Namespace

All recovery-specific functions are grouped inside:

namespace BastionGuardRecovery

The namespace isolates recovery helpers from the main backup controller and graphical application classes.

The module exposes two principal functions:

  • is_recovery_boot() – detects the recovery boot parameter
  • show_recovery_banner() – displays the recovery-mode warning

4. Dependencies

The module imports:

using GLib;
using Gtk;

GLib is used to read the Linux kernel command line, while GTK provides the recovery warning dialog.

No additional BastionGuard-specific service or backend dependency is required by this module.

5. Recovery Boot Detection

5.1 is_recovery_boot()

public bool is_recovery_boot()

The is_recovery_boot() function determines whether the current Linux system was started using the BastionGuard recovery boot option.

The function reads:

/proc/cmdline

This virtual file contains the arguments passed to the Linux kernel by the bootloader.

5.2 Recovery Kernel Parameter

Recovery mode is identified through the following kernel parameter:

bastionguard.recovery=1

The function returns true when this value is present in the kernel command line:

return "bastionguard.recovery=1" in cmdline;

When the parameter is absent, the function returns false.

5.3 File Reading

The kernel command line is loaded through:

FileUtils.get_contents("/proc/cmdline", out cmdline);

The complete file contents are stored in the local cmdline string and inspected for the recovery marker.

5.4 Detection Error Handling

The file-reading operation is enclosed in a try/catch block:

try {
    string cmdline;
    FileUtils.get_contents("/proc/cmdline", out cmdline);
    return "bastionguard.recovery=1" in cmdline;
} catch {
    return false;
}

If /proc/cmdline cannot be read, recovery mode is considered inactive.

The function therefore uses a fail-safe default:

false

No exception is propagated to the application startup sequence.

6. Interaction with Live-System Detection

The recovery module does not directly modify the normal live-system detection logic.

Instead, the main application recognizes the recovery execution mode and prevents it from being treated as a restricted live session.

This distinction is important because a normal live environment may disable scheduled or system-modifying operations, while the recovery environment must permit both:

  • Snapshot creation
  • Snapshot restoration

The recovery boot parameter identifies the environment, while the main controller is responsible for enabling the corresponding operational behavior.

7. Recovery Banner

7.1 show_recovery_banner()

public static void show_recovery_banner(Gtk.Window parent)

The show_recovery_banner() function creates and presents a modal warning dialog.

The function receives the visible main application window as its parent:

Gtk.Window parent

Associating the dialog with the main window ensures that the warning remains attached to the BastionGuard interface.

7.2 Invocation Point

The function is intended to be called by the graphical application startup code after the main window has been displayed.

The expected startup sequence is:

  1. Initialize the BastionGuard application
  2. Create the normal MainWindow
  3. Display the main window
  4. Verify the recovery boot state
  5. Call show_recovery_banner()

Displaying the main window first prevents the warning from appearing without a visible parent interface.

8. GTK Message Dialog Configuration

The recovery banner is implemented with:

Gtk.MessageDialog

The dialog uses the following properties:

  • Parent: the main BastionGuard window
  • Dialog flags: Gtk.DialogFlags.MODAL
  • Message type: Gtk.MessageType.WARNING
  • Buttons: Gtk.ButtonsType.OK

The dialog is created through:

var dlg = new Gtk.MessageDialog(
    parent,
    Gtk.DialogFlags.MODAL,
    Gtk.MessageType.WARNING,
    Gtk.ButtonsType.OK,
    "%s",
    message
);

8.1 Modal Behavior

The MODAL flag requires the user to acknowledge the recovery notice before returning to the main application window.

This ensures that the user understands that BastionGuard is running from the recovery environment before starting a backup or restore operation.

8.2 Warning Message Type

The dialog uses:

Gtk.MessageType.WARNING

This visually distinguishes the recovery notification from ordinary informational messages without presenting it as a fatal application error.

8.3 Dialog Button

The dialog provides a single confirmation button:

Gtk.ButtonsType.OK

No alternative action or cancellation choice is required because the dialog is informational and does not initiate a backup or restore operation.

9. Recovery Banner Content

The warning identifies the application state with:

BastionGuard™ — Modalità Recovery

The message explains that the operating system was started from the recovery environment and lists the functions that remain available.

The displayed actions are:

  • Crea – creates a backup from the running live system
  • Ripristina – restores an existing snapshot
  • Configurazione guidata – configures the backup device

The message also explains that shutdown and restart controls are available through the desktop context menu.

10. Dialog Title

The window title is explicitly configured as:

BastionGuard™ Recovery

The title is assigned through:

dlg.set_title("BastionGuard™ Recovery");

This title appears in the window decoration and identifies the dialog independently from its body text.

11. Dialog Presentation

After configuration, the dialog is displayed through:

dlg.present();

The function presents the dialog without starting a separate nested GTK event loop.

The surrounding graphical application remains responsible for GTK event processing and dialog lifecycle management.

12. User Workflow

The complete recovery-mode workflow is:

  1. The recovery bootloader adds bastionguard.recovery=1 to the kernel command line
  2. Linux exposes the parameter through /proc/cmdline
  3. is_recovery_boot() detects the parameter
  4. The normal BastionGuard Backup graphical interface starts
  5. The main application enables recovery-mode behavior
  6. show_recovery_banner() displays the warning
  7. The user acknowledges the dialog
  8. The user creates a backup, restores a snapshot, or opens the configuration wizard

13. Separation of Responsibilities

The recovery module does not perform backup or restore operations directly.

Responsibility is divided as follows:

  • RecoveryMain – detects recovery boot and displays the warning
  • AppGtk – initializes the graphical application and invokes the banner
  • MainWindow – exposes the normal backup and restore interface
  • Main – manages snapshots, repositories, devices, exclusions, backup, and restore operations

This design avoids duplicating the main application interface and backup logic inside the recovery environment.

14. Runtime Considerations

  • Non-invasive detection: recovery mode is detected by reading the kernel command line and does not modify system configuration.
  • Fail-safe behavior: an unreadable /proc/cmdline produces a normal non-recovery result.
  • Standard interface reuse: recovery mode uses the same MainWindow and controller as a normal application session.
  • Feature availability: backup and restore functions remain available instead of being disabled as they may be in an ordinary live session.
  • User acknowledgement: the modal dialog informs the user before recovery operations begin.
  • No direct privilege escalation: this module does not execute privileged commands or modify protected files.
  • No background threads: recovery detection and banner creation run synchronously during application startup.
  • No persistent state: the module does not write configuration files or store the detected recovery state.

15. Implementation Considerations

  • Exact parameter matching: detection depends on the literal bastionguard.recovery=1 value being present in /proc/cmdline.
  • Linux-specific implementation: the detection mechanism requires the Linux /proc virtual filesystem.
  • Startup integration: the caller must invoke the banner only after the main window has been created and presented.
  • Parent window requirement: show_recovery_banner() requires a valid Gtk.Window.
  • Dialog lifecycle: the function presents the dialog but does not explicitly connect a response handler or destroy the dialog.
  • Localization: the current dialog title and message are embedded directly in Italian and are not passed through a translation function.
  • Presentation-only module: recovery security and operational restrictions must be enforced by the main controller, not by this file.

16. Licensing

The source header identifies the module as part of the BastionGuard Backup fork and declares:

BastionGuard™
Copyright (C) 2025–2026 Calogero Scarnà
GPLv3

The module is distributed under the GNU General Public License version 3.

Published on:
Last updated on: