CISS.debian.installer/func/cdi_1000_helper/README/README_1080.md

---
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. [1080_helper_chroot.sh](../1080_helper_chroot.sh)
**Scope:** This note explains *what to use when* among
* `chroot_exec()`, 
* `chroot_script()`, and 
* `chroot_stdin()`.

## 2.1. When to use what
- **`chroot_exec (target, argv...)`** — *Simple, argv-style commands.*  
  Use it whenever you type a short command with discrete arguments (no shell features).  
  Examples from the updated user provisioning flow: `getent`, `groupadd`, `useradd`, `usermod`, `chsh`.

- **`chroot_script (target, "shell pipeline | redir && control-flow")`** — *Anything that needs a shell.*  
  Use it for pipelines, redirections, variable expansions, conditionals/loops, or tools that **expect** to run under a shell
  (e.g., `visudo` with `EDITOR=...`, `logrotate -d ... >> logfile`).

- **`chroot_stdin (target) <<'EOF' ... EOF`** — *Long, multi-line payloads without argv/ARG_MAX pain.*  
  Use it to stream robust, quoting-safe scripts via **stdin** (`bash -s`). Ideal for multi-line `awk`/`sed` edits, or any 
  content that would otherwise suffer from nested quoting or size limits if passed via `-c`. The helper sets up `bash -s` with 
  strict shell options; ones provide the payload on stdin.

All three helpers run with a *minimal, deterministic* environment via `env -i`, reintroducing only:
* `HOME`,
* `PATH`,
* `TERM`,
* `LANG/LC_ALL`, and 
* noninteractive APT settings. 
This ensures reproducibility and reduces the risk of ambient-environment leakage.

## 2.2. Design rationale

### 2.2.1. `chroot_exec()` — argv purity, preflight, the least overhead
**Best for:** idempotent system administration commands that do not require shell parsing.

**Key traits**
- **Preflight binary presence** with `which` inside the chroot before running the command — early, clear failure if a package 
  was not installed yet.
- **Sanitized environment** (`env -i` with a strict default PATH and essential variables) for deterministic behavior.
- **Straight argv execution** — no shell interpretation; no quoting games.

**When _not_ to use**  
If you need a pipe, a redirect, variable expansion, or inline control flow — switch to `chroot_script` 
(or `chroot_stdin` for long fragments).

### 2.2.2. `chroot_script()` — controlled shell, explicit `-c`
**Best for:** single-line pipelines and short shell snippets.

**Key traits**
- Launches `/bin/bash` with strict options: `errexit`, `errtrace`, `functrace`, `nounset`, `pipefail`, plus Bash options
  `inherit_errexit`, `failglob`, `lastpipe`. This makes subtle failures visible and prevents masked errors in pipelines.
- Same **minimal environment** as `chroot_exec()`.
- **Debug path**: on failure and if debugging flags are enabled, it drops into an interactive shell in the chroot for immediate
  triage.

**Trade-offs**
- The entire snippet becomes **one long argument** to `bash -c`. Very long or quote-dense payloads hit **`argv+env` limits** 
and are harder to lint. Prefer `chroot_stdin` for larger edits.

### 2.2.3 `chroot_stdin()` — robust multi-line scripts via `bash -s`
**Best for:** complex, multi-line payloads (Heredoc), quoting-heavy `awk`/`sed` programs, or anything beyond a small snippet.

**Key traits**
- Uses `bash -s` under the same strict shell options as `chroot_script`, but reads the script from **stdin**.
- Avoids **`argv`** size and **'ARG_MAX'** constraints entirely; ideal for longer program fragments.
- Greatly simplifies quoting: with a **single-quoted** heredoc (`<<'EOF'`) in the caller, you eliminate shell expansion 
  surprises and keep editors/IDEs happy.

## 2.3. Common foundation across all helpers
- **Minimal, controlled environment via `env -i`**, whitelisting only the necessities (`HOME`, `PATH`, `TERM`, `LANG/LC_ALL`, 
  noninteractive APT vars). This blocks noisy caller environments from leaking into the chroot and keeps behavior reproducible 
  across systems. 
- **Strict Bash modes** in the shell-based helpers — the effective default for the installer — to fail fast and surface latent 
  errors. 
- **Structured logging** for both success and failure paths, and an **interactive debug shell** when requested by the debug flags.

## 2.4. Decision guide
- **Is it a single command with clean argv?** → `chroot_exec`.
- **Is it a short shell line with redirection/pipe/env assignment?** → `chroot_script`.
- **Is it long, quote-heavy, or multi-line logic?** → `chroot_stdin` with a single-quoted heredoc.

If in doubt, start with `chroot_exec`. The moment you need a shell feature, jump to `chroot_script`. If your `-c` string grows
past comfort (readability, quoting, or length), upgrade to `chroot_stdin`.

## 2.5. Subtleties and gotchas (and how the helpers address them)
- **ARG_MAX and long `-c` strings:** `bash -c` places the entire script in `argv`. On typical Linux systems you effectively have
  ≈2 MiB for argv+env; very long strings or large environments hit `E2BIG`. `bash -s` (stdin) avoids this entirely.

- **Quoting pitfalls:** Nested single quotes within single-quoted strings become painful; Heredoc's with `<<'EOF'` (stdin) 
  eliminate accidental expansions and simplify review.

- **Locale-sensitive regex:** Always set `LC_ALL=C` for tools like `awk` to get predictable `[[:class:]]` semantics and bytewise
  collation in system config edits.

- **Partially writes / truncated files:** When editing files, write to a `*.new` and then `mv -f` only after `test -s` (non-empty)
  to guard against empty outputs in case of earlier errors.

- **Debug ergonomics:** The helpers integrate a conditional drop-in shell on failures when `VAR_CHROOT_DEBUG` (and related flags)
  is enabled, enabling immediate forensics inside the target environment.

## 2.6. Antipatterns (what to avoid)
- **Using `chroot_exec` for anything involving the shell.** That defeats the argv-only contract and will either fail or behave unexpectedly.
- **Packing large scripts into `-c` strings.** Hard to quote, hits argv limits, and clutters process lists. Prefer stdin.
- **Relying on the caller’s ambient environment.** The helpers intentionally use `env -i` to avoid such a leakage; do not
  reintroduce it unless you must.

# 3. Appendix — Helper signatures & guarantees
- **`chroot_exec(target, argv...)`**
  - Preflights the binary using `which` inside the chroot; fails early if missing.
  - Runs with a minimal, deterministic environment.

- **`chroot_script(target, "code", [loglevel])`**
  - Executes `bash -c "code"` under strict bash options; minimal environment; rich failure logging and optional interactive debug.

- **`chroot_stdin(target, "marker", [loglevel]) <<'EOF' ... EOF`**
  - Executes `bash -s` under strict bash options; minimal environment; same debug path; payload read from stdin, avoiding 
    argv/ARG_MAX issues.

---
**[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 -->