140 lines
6.6 KiB
Markdown
140 lines
6.6 KiB
Markdown
---
|
|
gitea: none
|
|
include_toc: true
|
|
---
|
|
|
|
# 1. CISS.debian.installer
|
|
|
|
**Centurion Intelligence Consulting Agency Information Security Standard**<br>
|
|
*The CISS Debian Installer provides a fully automated and hardened installation process.*<br>
|
|
**Master Version**: 8.00<br>
|
|
**Build**: V8.00.000.2025.06.17<br>
|
|
|
|
# 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](../../var/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](../../lib/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](../../lib/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](../../lib/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](https://coresecret.eu/)**
|
|
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->
|