CISS.debian.installer/docs/man/ERROR_HANDLING.md

Table of Contents

• 1. CISS.debian.installer
• 2. Global Environment and Error Handling in CISS.debian.installer
• 2.1. Overview
• 2.2. bash.var.sh
• 2.2.1. Purpose
• 2.2.2. Execution Settings
• 2.2.3. Paradigm
• 2.3. 0060_trap_err.sh
• 2.3.1. Purpose
• 2.3.2. Key Functionalities
• 2.3.3. Design Considerations
• 2.4. 0070_trap_exit.sh
• 2.4.1. Purpose
• 2.4.2. Behavior Summary
• 2.4.2.1. trap_exit_zero()
• 2.4.2.2. trap_exit_non_zero()
• 2.4.3 Integration Notes
• 2.5. 0080_trap_int.sh
• 2.5.1. Purpose
• 2.5.2. Core Mechanism
• 2.5.2.1. trap_int()
• 2.5.2.2. restart_dialog()
• 2.5.3. Security and UX Considerations
• 2.6. Security and Best Practices
• 2.7. Summary

1. CISS.debian.installer

Centurion Intelligence Consulting Agency Information Security Standard
The CISS Debian Installer provides a fully automated and hardened installation process.
Master Version: 8.00
Build: V8.00.000.2025.06.17

2. Global Environment and Error Handling in CISS.debian.installer

2.1. Overview

This document outlines the core mechanisms responsible for global Bash environment configuration, error trapping, signal handling, and structured diagnostics in the CISS.debian.installer. These foundational components ensure that the installer operates in a predictable, robust, and audit-friendly manner, even under adverse conditions.

2.2. bash.var.sh

2.2.1. Purpose

Defines the global shell behavior and enforces rigorous execution semantics. This file is sourced early in the setup pipeline and governs how the shell reacts to unexpected states, variable misuses, and subshell propagation.

2.2.2. Execution Settings

The following Bash options are set to enforce secure and fail-fast behavior:

• errexit (set -e): Immediately aborts execution on non-zero exit status.
• errtrace (set -E): Ensures that ERR traps are inherited in functions and subshells.
• functrace (set -T): Allows DEBUG and RETURN traps to be inherited as well.
• ignoreeof: Prevents accidental termination via Ctrl-D on interactive shells.
• nounset (set -u): Fails on use of undeclared variables.
• pipefail: Propagates the first failing command's exit code in pipelines.
• noclobber (set -C): Disallows overwriting of existing files via output redirection.

2.2.3. Paradigm

All scripts and modules in the CISS.debian.installer framework operate under the principle of deterministic failure and exhaustive state introspection. The defined options anticipate and actively prevent common scripting failures due to overlooked conditions or shell misbehavior.

2.3. 0060_trap_err.sh

2.3.1. Purpose

Implements the trap_err() handler invoked automatically upon any uncaught error (ERR). It is designed to distinguish runtime anomalies precisely, log them comprehensively, and expose them to the console and log system.

2.3.2. Key Functionalities

• Captures the failing command, line number, function, and script context.
• Records full environmental metadata: UID, EUID, hostname, Git commit, resource state, and Bash version information.
• Generates separate diagnostic artifacts:
  • LOG_ERR for the error summary,
  • LOG_DBG and LOG_TRC for verbose debug/trace logs (conditionally),
  • LOG_VAR for the differential variable dump (if debugging is enabled).
• Provides structured output both to file and to stderr, with color coding for visual inspection.
• Outputs a stack trace via print_stacktrace() for post-mortem debugging.

2.3.3. Design Considerations

• The function uses trap - DEBUG ERR INT TERM to prevent a reentrant trap firing during the error handler itself.
• Integrates gracefully with dialog-driven user interfaces (e.g., dialog_box_cleaner, dialog_gauge_cleaner).
• Evaluates VAR_DEBUG_TRACE and VAR_DEBUG_TRAP to determine the scope of runtime introspection.

2.4. 0070_trap_exit.sh

2.4.1. Purpose

Defines trap_exit(), a comprehensive exit handler for any script termination—whether normal (exit 0) or due to a fatal error. Notably, it complements trap_err() by catching unbound variable errors that bypass ERR.

2.4.2. Behavior Summary

2.4.2.1. trap_exit_zero()

• Triggered upon a successful script exit.
• Logs positive confirmation including runtime and debug log paths if available.
• Initiate cleanup routines.
• Outputs user guidance and donation links (non-critical aesthetic footer).

2.4.2.2. trap_exit_non_zero()

• Triggered upon abnormal termination where ERRTRAP is not set, e.g., due to an unbound variable.
• Captures a broad spectrum of diagnostic data similar to trap_err().
• Ensures that the cause (such as an unset variable) is clearly hinted.
• Invokes final cleanup and prints the complete diagnostic suite with full metadata.

2.4.3 Integration Notes

• Cleans up dialog UIs on abnormal exit.
• Isolates early trap context via local read-only declarations to avoid overwriting.
• Ensures that debug logs and variable states are flushed before exit.

2.5. 0080_trap_int.sh

2.5.1. Purpose

Provides signal handling for SIGINT (Ctrl+C), with a dialog-safe mechanism that prevents unintended termination. This is crucial for headless or semi-automated deployments with interactive components.

2.5.2. Core Mechanism

2.5.2.1. trap_int()

• Captures INT signals.
• Pauses for user confirmation (timeout after 16 seconds).
• Either gracefully aborts or resumes the script, depending on user input or timeout.
• Integrates with the dialog subsystem, cleaning UI artifacts prior to action.

2.5.2.2. restart_dialog()

• Reinitialized the dialog interface after an interrupted run if the user chooses to continue.
• Restores traps post-resumption to ensure robustness.

2.5.3. Security and UX Considerations

• Prevents accidental termination of long-running installations.
• Avoids data corruption due to mid-script interrupts.
• Enhances user control without compromising automation logic.

2.6. Security and Best Practices

• Immutable trap guards: Traps are explicitly unset before being reassigned to ensure deterministic behavior and prevent recursive invocation.
• Subshell inheritance: Use of errtrace and functrace ensures traceability even in nested scripts or background processes.
• Fail-fast philosophy: The combination of set -Ceuo pipefail with trap integration guarantees that misconfigurations or runtime anomalies are never silently ignored.
• Interactive safety net: Signal handling introduces it a user-verifiable fail-safe for recovery or re-entry.

2.7. Summary

These core components of the CISS.debian.installer provide a robust, secure, and transparent execution environment. The Bash environment is tightly constrained to fail predictably and verbosely, while the trap handlers furnish a rich diagnostic infrastructure, indispensable for debugging and secure automation. Signal interception and dialog integration round off a cohesive control architecture, ensuring resilience in interactive and automated deployments alike.

---

no tracking | no logging | no advertising | no profiling | no bullshit