BackupPage

1. Overview

The BackupPage.cpp file is a GTKmm backup and recovery page implementation in BastionGuard.

Builds the backup/recovery interface, validates recovery artifacts and /boot capacity, launches privileged recovery scripts, streams subprocess output into the UI, and manages progress and result states.

The documentation below is generated from the supplied source and covers its API surface, runtime responsibilities, data flow, filesystem or command interactions, concurrency model, and security considerations.

2. Source Inventory

  • Original path: backup/BackupPage.cpp
  • Language: C++
  • Source type: .cpp
  • Line count: 584
  • SHA-256: 2d4776b1f4a788fd75b79dc58ed8a42c1c57f9342128cdd2c90aab1525bc1b68

3. Dependencies

The file declares the following compile-time dependencies:

Project

  • BackupPage.hpp
  • sys/statvfs.h
  • sys/wait.h

GTK/GLib

  • glibmm/spawn.h
  • glibmm/i18n.h
  • glibmm/fileutils.h
  • glibmm/main.h
  • giomm.h

C/C++ Runtime

  • sstream
  • iomanip
  • memory
  • thread

4. Types and Public Contract

No standalone class, structure, or enumeration is declared directly in this file.

5. API and Method Inventory

The following functions or methods are implemented in this file:

  • BackupPage::BackupPage() – Implements the operation represented by this API.
  • BackupPage::~BackupPage() – Releases callbacks, threads, timers, or other owned runtime state.
  • BackupPage::buildBackupTab() – Constructs the corresponding GTK interface section.
  • BackupPage::buildGrubTab() – Constructs the corresponding GTK interface section.
  • sigc::mem_fun(*this, &BackupPage::onBuildRecovery)); btnBox->append(buildRecoveryButton); installGrubButton.set_label(_("⬆ Installa voce GRUB")); installGrubButton.get_style_context()->add_class("suggested-action"); installGrubButton.signal_clicked().connect( sigc::mem_fun(*this, &BackupPage::onInstallGrub)); btnBox->append(installGrubButton); removeGrubButton.set_label(_("🗑 Rimuovi voce GRUB")); removeGrubButton.get_style_context()->add_class("destructive-action"); removeGrubButton.signal_clicked().connect( sigc::mem_fun(*this, &BackupPage::onRemoveGrub)); btnBox->append(removeGrubButton); box->append(*btnBox); return box; } // --------------------------------------------------------------------------- // Log section // --------------------------------------------------------------------------- Gtk::Widget* BackupPage::buildLogSection() – Implements the operation represented by this API.
  • BackupPage::updateRecoveryStatus() – Refreshes recovery-image, GRUB-entry, and free-space indicators.
  • BackupPage::setResult(bool success, const std::string& msg) – Displays a success or error result state.
  • BackupPage::onBuildRecovery() – Handles the on build recovery user-interface action.
  • BackupPage::onInstallGrub() – Handles the on install grub user-interface action.
  • BackupPage::onRemoveGrub() – Handles the on remove grub user-interface action.
  • BackupPage::runAsyncStreaming(const std::string& cmd, bool show_success) – Runs a shell command asynchronously and streams both output channels.
  • BackupPage::logSafe(const std::string& msg) – Appends a log message on the GTK main thread with lifetime protection.
  • fmtSize(guint64 bytes) – Formats a byte count for user-facing display.

6. Functional Architecture

Recovery Artifacts and Paths

  • Recovery root: /boot/bastionguard-recovery.
  • SquashFS image: /boot/bastionguard-recovery/live/filesystem.squashfs.
  • Kernel image: /boot/bastionguard-recovery/vmlinuz.
  • GRUB entry: /etc/grub.d/42_bastionguard-recovery.
  • Build and install helpers are loaded from /usr/share/bastionguard-backup/scripts.

Capacity and State Validation

  • Requires at least 2 GiB of free space on /boot before recovery-image construction.
  • Uses statvfs() to calculate available capacity.
  • Checks image, kernel, and GRUB-entry presence and reports their state in markup labels.

Asynchronous Command Streaming

  • Runs commands through /bin/bash -c with separate stdout and stderr pipes.
  • Streams both channels into a monospace GTK log panel.
  • Uses a pulsing progress bar while the child process is active.
  • Uses child-watch and IO callbacks, then restores button sensitivity and refreshes recovery status.

7. Operational Flow

  1. Construct the backup and recovery widgets.
  2. Inspect current recovery image, kernel, GRUB entry, and available boot-partition space.
  3. Launch the requested backup or privileged recovery operation.
  4. Stream subprocess output into the log panel while updating progress.
  5. Interpret the child exit status, restore controls, and refresh the visible state.

8. Filesystem and External Command Surface

Referenced Absolute Paths

  • /bin/bash
  • /boot
  • /boot/bastionguard-recovery
  • /boot/bastionguard-recovery/live/filesystem.squashfs
  • /boot/bastionguard-recovery/vmlinuz
  • /etc/grub.d/42_bastionguard-recovery
  • /usr/bin/bastionguard-backup-launcher
  • /usr/share/bastionguard-backup/scripts/build-recovery-squashfs.sh
  • /usr/share/bastionguard-backup/scripts/install-grub-entry.sh

Commands or Security Primitives Referenced

  • bash
  • ip
  • pkexec
  • sh
  • statvfs
  • update-grub

9. Concurrency and Lifecycle

  • Uses GLib idle callbacks to update GTK from the main thread.
  • Uses GLib timers for progress, deferred actions, polling, or cache readiness.
  • Uses a lifetime guard so delayed callbacks do not access a destroyed widget.

10. Security Considerations

  • Recovery build, GRUB installation, and GRUB removal cross a privilege boundary through pkexec.
  • Scripts and GRUB paths must remain administrator-controlled because they are executed or modified with elevated privileges.
  • Child-process output is treated as diagnostic text and is not interpreted as markup.

11. Implementation Considerations

  • The implementation should remain synchronized with the matching header declarations.
  • Authorization cancellation and missing Polkit support must be surfaced as normal operation failures.
  • All pipe channels and child PIDs must be closed on both normal completion and error paths.

12. Licensing and Branding

The source is distributed under the project license declared by the associated BastionGuard source module.

The source header identifies BastionGuard™ as a trademark and states that the name and branding are not licensed under the GPL.

The software is provided without warranty, including implied warranties of merchantability or fitness for a particular purpose.

Published on:
Last updated on: