feat(root02): author Linux Administration & Networking

Adds all 6 ROOT 02 modules (Linux system administration, storage & filesystems, the Networking Mental Model, Linux network inspection, DNS & HTTP, Linux troubleshooting) — 37 activities, each with a real lesson, demonstration/guided exercise, knowledge check, hands-on Lab, and reflection. The Networking Mental Model module (M3) gets deliberately extra depth per its "critical module" designation, with no lab by design — conceptual mastery via knowledge check and guided exercise, matching root-05-m00's own precedent. Adds 6 new hands-on Linux/networking scenarios plus 2 MCQs: linux-service-inspection (inspects the platform's own real nginx without touching it — a genuinely safe, real service-inspection target that avoids ever risking the Lab's own connectivity), linux-service-lifecycle (start/ verify/stop a fully controllable service), linux-storage-inspection, linux-network-inspection (ip/ss/getent/curl, each framed as answering one specific diagnostic question), linux-dns-http-diagnosis (a genuine DNS-resolves-but-wrong-port failure, diagnosed and fixed), and linux-troubleshooting-framework (a real missing-config-file failure, resolved via the RootNode Observe/Evidence/Hypothesis/Test/Repair/Validate/Prevent framework). All tested end-to-end via the real scenario-validation API, including negative tests confirming they fail when unsolved. Wires rootnode-linux-networking-assessment (2 required + 4 random-draw scenarios) using the existing Phase 3B assessment engine. Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-08-26 17:07:46 -05:00
parent b6516a74db
commit e007bcf000
39 changed files with 1752 additions and 0 deletions
@@ -0,0 +1,63 @@
+# Linux Troubleshooting
+
+## The RootNode troubleshooting framework
+
+Every module in ROOT 02 has been building toward this: a repeatable, disciplined process for
+diagnosing ANY Linux-level failure, not just the specific ones you've already seen.
+
+```
+OBSERVE
+  ↓
+GATHER EVIDENCE
+  ↓
+FORM HYPOTHESIS
+  ↓
+TEST
+  ↓
+REPAIR
+  ↓
+VALIDATE
+  ↓
+PREVENT
+```
+
+## Each step, and why skipping it costs you later
+
+- **Observe** — what's the actual, specific symptom? Not "it's broken" — the exact error, the
+  exact command that failed.
+- **Gather evidence** — logs, process state, listening ports, config content — the raw facts,
+  collected BEFORE guessing at a cause.
+- **Form hypothesis** — based on the evidence (not a guess made before looking), what's the most
+  likely cause?
+- **Test** — check whether your hypothesis is actually true, ideally without yet making changes
+  that could mask the real problem.
+- **Repair** — make the minimal change that addresses the CONFIRMED cause, not a broad "try
+  everything" fix.
+- **Validate** — confirm the original symptom is actually gone, with real evidence, not
+  assumption.
+- **Prevent recurrence** — what would stop this from happening again? Skipping this step is how
+  teams end up fixing the exact same incident repeatedly.
+
+## Why "skip straight to fixing" costs you
+
+Jumping straight from OBSERVE to REPAIR (skipping evidence and hypothesis) means you're guessing
+— sometimes you'll get lucky, but you won't have LEARNED anything transferable, and you risk
+"fixing" a symptom while leaving the actual cause untouched, guaranteeing a repeat. Every command
+from Modules 1, 2, and 4 IS the "gather evidence" step, made concrete.
+
+## Instructor Notes
+
+**Lesson goal:** Consolidate every command this course taught into ONE disciplined process,
+directly matching the identical framework `root-10-m03-troubleshooting-framework` teaches at the
+Kubernetes level — introduced here first, at the Linux level, so it already feels familiar by
+then.
+
+**Approximate timing:** 15 minutes read; 10 minutes live.
+
+**Common misconception to watch for:** treating this as a rigid checklist to recite rather than
+an actual habit — the value only shows up when it's applied under a real, unfamiliar failure
+(this module's Lab).
+
+**Discussion question:** "Describe a time you fixed something without understanding WHY it
+broke. Did it come back?" (Real personal examples land this lesson better than abstract
+description.)
@@ -0,0 +1,64 @@
+# Demonstration: Every Step, In Order, On a Real Failure
+
+## OBSERVE
+
+A startup script fails: `/srv/demo/start.sh` exits with an error. That's the specific, concrete
+symptom — not "the service is down."
+
+## GATHER EVIDENCE
+
+```
+$ /srv/demo/start.sh
+FATAL: config file not found: /srv/demo/config/settings.conf
+```
+
+The script's own error message IS the evidence — no guessing required.
+
+## FORM HYPOTHESIS
+
+The config file at that exact path doesn't exist. That's the specific, testable hypothesis —
+not "something's misconfigured."
+
+## TEST
+
+```
+$ ls /srv/demo/config/
+ls: cannot access '/srv/demo/config/': No such file or directory
+```
+
+Confirmed — the directory itself doesn't exist yet, not just the file.
+
+## REPAIR
+
+```
+$ mkdir -p /srv/demo/config
+$ echo "mode=production" > /srv/demo/config/settings.conf
+```
+
+The minimal fix for the CONFIRMED cause — not a broader "reinstall everything" overcorrection.
+
+## VALIDATE
+
+```
+$ /srv/demo/start.sh
+Started with config: mode=production
+```
+
+The original symptom is gone, confirmed with real output, not assumption.
+
+## PREVENT RECURRENCE
+
+A real prevention step here: the script should probably check for and create its config
+directory on first run, or the deployment process should ensure the config exists before the
+service ever starts — naming this explicitly is what separates a real fix from a lucky one.
+
+## Instructor Notes
+
+**Demo goal:** Show all seven steps applied in strict order to one concrete, realistic failure
+— the exact structure this module's Lab requires students to repeat themselves.
+
+**Approximate timing:** 10 minutes live.
+
+**Common mistake to watch for:** skipping straight to REPAIR (creating the file) without first
+articulating the hypothesis and testing it — even when the fix seems obvious, naming the
+hypothesis explicitly is the habit this module is building.
@@ -0,0 +1,41 @@
+# Knowledge Check: Linux Troubleshooting
+
+---
+
+**1. What's the difference between OBSERVE and GATHER EVIDENCE?**
+
+*Answer:* OBSERVE names the specific symptom (what actually failed, precisely). GATHER EVIDENCE
+collects the raw facts (logs, config, process/port state) needed to understand WHY, before
+guessing at a cause.
+
+---
+
+**2. Why does FORM HYPOTHESIS come before TEST, rather than jumping straight to REPAIR?**
+
+*Answer:* A hypothesis is a specific, falsifiable guess at the cause based on evidence already
+gathered — testing it BEFORE repairing confirms you're about to fix the right thing, rather than
+making a change that might not address the actual cause at all.
+
+---
+
+**3. A fix works, but the same failure happens again a week later. Which framework step was
+most likely skipped?**
+
+*Answer:* PREVENT RECURRENCE — the immediate symptom was resolved, but whatever allowed the
+underlying cause to occur in the first place was never addressed.
+
+---
+
+**4. Why is "repair the minimal confirmed cause" better than "try several things until it
+works"?**
+
+*Answer:* A minimal, confirmed repair means you actually know what fixed it and can prevent
+recurrence deliberately. Trying multiple things at once means even success leaves you unable to
+say WHICH change mattered — and unable to reliably prevent the same failure next time.
+
+## Instructor Notes
+
+**Facilitation:** Question 3 is a good real-world check-in — ask if anyone has a personal
+example of a fix that didn't actually stick.
+
+**Approximate timing:** 5 minutes.
@@ -0,0 +1,30 @@
+# Guided Exercise: Write Your Hypothesis Before You Look at the Answer
+
+This is a paper exercise — commit to a full framework pass before touching the Lab.
+
+## Your task
+
+You're told: "A script that's supposed to write a `ready` marker file isn't creating it, and
+exits with a non-zero code." Before running anything, write out, specifically:
+
+1. What's your OBSERVE statement (the precise symptom, not "it's broken")?
+2. What EVIDENCE would you gather first, and with what command?
+3. What's ONE specific, testable hypothesis (not "something's wrong with it")?
+
+## A worked shape to check yourself against
+
+1. Observe: "Script X exits non-zero and does not create file Y."
+2. Evidence: redirect both stdout and stderr to a file and read it —
+   `script.sh > log 2>&1; cat log` — the script's own error output is almost always the fastest
+   evidence source for a startup failure.
+3. Hypothesis (once you've actually read the error): something SPECIFIC the error names —
+   e.g. "the script requires a file at path X that doesn't currently exist" — not a vague
+   restatement of the symptom.
+
+## Instructor Notes
+
+**Facilitation:** The value here is entirely in getting students to write a hypothesis
+SPECIFIC and FALSIFIABLE enough that they could be proven wrong — "something's misconfigured"
+fails that bar; "the config file at this exact path is missing" passes it.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced.
@@ -0,0 +1,31 @@
+# Reflection: This Is the Same Framework You'll Use for the Rest of ROOT_
+
+## Reflection questions
+
+1. Which framework step did you personally find easiest to skip or rush through in this
+   module's Lab? Why do you think that step specifically tempts shortcuts?
+2. You've now used this exact seven-step framework — Observe, Gather Evidence, Form Hypothesis,
+   Test, Repair, Validate, Prevent Recurrence — at the Linux level. Where do you expect to use
+   it again?
+
+## Real Ops takeaway
+
+**This entire course, from Module 1's five-question service checklist through Module 5's
+failure-category taxonomy, was building toward this one repeatable discipline.** You'll meet
+this exact framework again, formally named, in ROOT 10 — applied to Kubernetes instead of raw
+Linux. Having already practiced it here means ROOT 10 won't be teaching you a new skill, just
+retargeting a skill you already have.
+
+This module — and ROOT 02 — is complete. Continue to ROOT 03: Git & Collaborative Development.
+
+## Instructor Notes
+
+**Discussion questions for a live classroom:** question 1 tends to surface "Prevent Recurrence"
+and "Form Hypothesis" (jumping straight to a guessed fix) as the two most commonly admitted
+shortcuts — worth normalizing as a real, common temptation rather than a personal failing.
+
+**Approximate timing:** 8-10 minutes live discussion; 5 minutes self-paced writing.
+
+**Milestone note:** this is the last module of ROOT 02 — consider a short recap connecting all
+six modules (services → storage → networking model → inspection tools → DNS/HTTP → framework)
+before moving to ROOT 03.