Appendix A — Glossary

Chapter TL;DR: Look up an unfamiliar term here, read the plain explanation first, then follow its chapter links to see where it affects a real choice.

You do not need to learn this page before starting. Each entry gives a plain explanation, the practical detail, a common mistake, and links back to the chapters that use it.

How to use this appendix#

TL;DR: Follow a term link when a decision depends on unfamiliar language, read the plain explanation first, and use the chapter backlinks to see the concept in practice.

The glossary is an appendix, not a prerequisite exam. The ELI5 line is enough for orientation. Read the operational detail before approving a change involving that term. Search aliases, commands, and acronyms directly in this page. A definition explains the model; the linked chapter and current primary documentation still govern a real implementation.

ashift#

TL;DR: ashift is the permanent sector-alignment choice recorded when a ZFS vdev is created.

Operational detail. ashift=12 represents 4 KiB alignment and is a common default for 4 KiB-native and 512e disks. A bridge or drive may report 512-byte logical sectors while the media writes larger units. Record logical and physical geometry and the evidence supporting the value before pool creation.

Why it matters / common trap. The choice cannot be casually corrected after data arrives. Trusting one reported field or copying ashift=13 from another build can impose long-lived performance or capacity costs.

Used in: Storage + identity, Field kit

AUTH_SYS, RPCSEC_GSS, and AUTH_GSS#

TL;DR: These are NFS identity models: AUTH_SYS trusts client-reported numeric IDs, while GSS/Kerberos modes authenticate principals cryptographically.

Operational detail. With AUTH_SYS, a compromised client root can usually impersonate permitted nonzero UIDs. RPCSEC_GSS with Kerberos can authenticate principals; krb5i adds integrity and krb5p also encrypts traffic.

Why it matters / common trap. Root squashing does not make an arbitrary AUTH_SYS client trustworthy. Use stronger authentication when client-root impersonation is unacceptable.

Used in: Storage + identity

fsync, file locking, and atomic rename#

TL;DR: These are filesystem guarantees applications use to make writes durable, coordinate users, and replace files safely.

Operational detail. Databases may assume low-latency fsync, reliable locks, and same-filesystem atomic operations. Test the actual local, SMB, NFS, sync, or WAN path against application requirements.

Why it matters / common trap. A mount that accepts files can still be unsafe for a live database; generic sync and WAN filesystems often violate hidden assumptions.

Used in: Storage + identity, Services

home.arpa, .local, and mDNS#

TL;DR: Use home.arpa for private home DNS; .local belongs to multicast DNS and can behave inconsistently as a unicast zone.

Operational detail. Keep host names separate from movable service aliases and ensure private questions stay with the home resolver.

Why it matters / common trap. .local has special multicast behavior on common clients, causing surprising resolution conflicts.

Used in: Start here, Network + power, Services, Field kit

tmux terminal multiplexer#

TL;DR: tmux keeps terminal sessions running independently of one SSH connection and lets an operator detach and reconnect later.

Operational detail. Name sessions by task, record the host and user, retain command transcripts separately, and use panes sparingly during risky work. A reconnecting operator should inspect the current prompt, process state, and logs before typing.

Why it matters / common trap. tmux improves continuity but is not a scheduler, audit log, or guarantee that a command survives reboot. Reattaching to the wrong host or stale privileged shell can make an otherwise correct command destructive.

Used in: Control host, Linux foundation, Operations, Field kit

Access-control list (ACL; POSIX ACL; Windows ACL; security.NTACL)#

TL;DR: An ACL is a detailed guest list that says exactly which people or programs may read, change, or enter a file or directory.

Operational detail. Basic Unix permissions describe an owner, a group, and everyone else. POSIX ACLs add named users and groups. Windows ACLs use security identifiers (SIDs); Samba may preserve them in extended attributes such as security.NTACL. Backups and migrations must preserve ACLs, extended attributes, numeric UID/GID ownership, and SID mappings.

Why it matters / common trap. A restored file can contain the right bytes while granting the wrong access. Matching Unix usernames alone does not preserve Windows permissions.

Used in: Storage + identity, Services, Field kit

ACME and DNS-01#

TL;DR: ACME automatically obtains and renews certificates; DNS-01 proves domain control by placing a temporary DNS record.

Operational detail. A public or private certificate authority can expose an ACME service. DNS-01 supports wildcard certificates and does not require a public web server, but its automation credential can change DNS. Restrict that credential to the required zone and record types, or delegate only the _acme-challenge subtree.

Why it matters / common trap. Certificate automation can quietly turn a narrow web-service credential into broad domain-control authority. Do not place a full DNS-account credential on an application server merely because setup instructions make that easy.

Used in: Network + power, Services

Active vs enabled#

TL;DR: Active means a service runs now; enabled means it is configured to start later, usually during boot.

Operational detail. The states are independent: a service can be running but disabled, or enabled but currently failed. Inspect both, validate the service itself, and test again after reboot.

Why it matters / common trap. “It works now” does not prove it will return after power loss. “Enabled” does not mean healthy.

Used in: Linux foundation, Services, Operations

Agent approval mode, permission mode, auto-approve, full access, and sandbox#

TL;DR: Approval mode decides when tools pause for confirmation; a sandbox decides what those tools can actually reach.

Operational detail. Once the agent runs inside a dedicated account and workspace, with narrow target credentials, tested filesystem and network boundaries, explicit stop conditions, and prepared recovery, a low-friction approval mode can let it finish ordinary authorized work without constant prompts. Record the exact client/version, mode, sandbox, writable roots, network policy, and denial tests; retest after material updates because product names and behavior change.

Why it matters / common trap. “Run freely” should mean fewer confirmation dialogs inside already-enforced handcuffs. It must not mean administrator access, unrestricted reach, or permission to cross a new destructive boundary. Full bypass belongs only in a disposable isolated environment.

Used in: Before the agent, Control host, Field kit

Agent roles: observer, operator, deployer, and reviewer#

TL;DR: Seeing, coordinating, changing, and independently checking are different jobs and should not share all credentials.

Operational detail. Give each role only the identities and data it needs. An observer should not inherit deployment authority; a reviewer should receive a sanitized packet without homelab credentials or mutation tools. Separate roles by operating-system account or stronger isolation when their credentials must not be mutually readable.

Why it matters / common trap. Role names in a prompt—or credentials stored under one Unix account—do not create separation. Any process able to read all credentials can use all their authority.

Used in: Before the agent, Control host, Storage + identity, Services

Agent, coding agent, and LLM operator#

TL;DR: An agent is an LLM application that can use tools such as files, shells, Git, browsers, or APIs to complete multi-step work.

Operational detail. The model proposes and chooses actions, while its client exposes tools. Accounts, credentials, filesystem permissions, and network policy determine what those actions can affect. Treat an agent as a fast junior operator, not as an authority source.

Why it matters / common trap. A careful prompt can improve behavior but cannot contain a mistaken or compromised agent. Real boundaries must be enforced outside the conversation.

Used in: Start here, Before the agent, Control host, Field kit

AHCI#

TL;DR: AHCI is a standard controller mode that lets the operating system interact directly with ordinary SATA drives.

Operational detail. For software-defined storage, AHCI or a true HBA/JBOD path generally exposes individual device identity and errors more honestly than motherboard “RAID” modes. Record the selected firmware mode before installing the OS or creating a pool.

Why it matters / common trap. Changing controller mode later can prevent boot. Hidden controller RAID can obscure the individual disks that ZFS needs for diagnosis and repair.

Used in: Linux foundation, Storage + identity

API, token, and scope#

TL;DR: An API is a program-facing control surface; a token is its credential, and scope limits the actions that credential may perform.

Operational detail. Record the endpoint, allowed verbs and objects, owner, expiry, rotation, revocation, and both allowed and denied tests. Prefer purpose-built read-only or narrowly typed roles over general administrator tokens.

Why it matters / common trap. “API access” does not mean read-only access. A status endpoint and an administrator session may use the same API and credential unless the service enforces a distinction.

Used in: Before the agent, Control host, Services, Field kit

Append-only, immutability, WORM, and object lock#

TL;DR: These mechanisms let a routine writer add history while preventing it from changing or deleting protected older history.

Operational detail. Append-only usually constrains one credential or endpoint. WORM means “write once, read many”; object lock can enforce retention on stored object versions. Keep pruning authority separate and test that the routine source and agent cannot delete data or shorten retention.

Why it matters / common trap. A field saying append_only: true is not enforcement. The backend must deny deletion, and a storage administrator may still be able to erase or withhold the underlying data.

Used in: Storage + identity, Operations, Field kit

Application consistency and quiescing#

TL;DR: Quiescing coordinates or pauses writers so a copy represents one usable moment rather than a mixture of before and after.

Operational detail. Databases may require an application export, transaction checkpoint, or documented stop/flush sequence before a filesystem snapshot or backup. Record and test the exact method.

Why it matters / common trap. A storage snapshot can be internally valid while application data is incomplete. Backup command success does not prove restoration.

Used in: Storage + identity, Services, Operations, Field kit

Atomic install, sealed release, and TOCTOU#

TL;DR: Install one reviewed set of bytes as a unit, and prevent those bytes from changing between review and privileged use.

Operational detail. Render the complete candidate, review it, record digests, copy it into a new root-owned agent-non-writable location, verify ownership and digests there, rerun native validation, and install only from that location. TOCTOU means “time of check to time of use.”

Why it matters / common trap. Validating an agent-writable file and later passing its path to a privileged command leaves a gap in which bytes, a symlink target, an include, or the environment can change.

Used in: Before the agent, Control host, Storage + identity, Services, Field kit

Authentication vs authorization#

TL;DR: Authentication asks “who are you?”; authorization asks “what may you do?”

Operational detail. Reachability is a third question: a device may be reachable but reject login, or authenticate a user while denying a particular operation. Test each layer separately.

Why it matters / common trap. A valid login is not administrator authority, and an unreachable service has not necessarily proved an authorization rule.

Used in: Before the agent, Network + power, Storage + identity, Services

Automatic security updates and unattended-upgrades#

TL;DR: Install supported distribution security patches automatically, but schedule and recover reboots deliberately.

Operational detail. Report failed update jobs and pending reboots, preserve console/direct-cable recovery, and give every third-party repository or downloaded installer its own ownership and update policy.

Why it matters / common trap. Disabling updates accumulates exposure; automatically rebooting every update can interrupt services or strand an encrypted or misconfigured host.

Used in: Linux foundation, Operations

Backup retention, forget, and prune#

TL;DR: Retention chooses which backup snapshots remain; forgetting removes their references, and pruning later reclaims unreferenced repository data.

Operational detail. Define daily, weekly, monthly, and exceptional hold periods from recovery needs and capacity. Preview policy results, protect recent and known-good restore points, serialize repository maintenance, and retain logs of what policy removed.

Why it matters / common trap. A typo in scope, host, tag, or retention policy can expire the wrong history. prune is materially destructive and may be expensive; do not combine an unreviewed policy change and irreversible reclamation into one opaque step.

Used in: Storage + identity, Operations

Backup, snapshot, replica, synchronization, and hot remote storage#

TL;DR: These mechanisms solve different problems; only a backup combines independent history with a proved restore.

Operational detail. A snapshot is a point-in-time view on the same storage system. A replica is another currently usable copy. Synchronization propagates current changes. Hot remote storage stays directly usable elsewhere. A backup has independent history and a defined restore procedure.

Why it matters / common trap. Mirrors, snapshots, replicas, and sync can preserve or propagate deletion, ransomware, corruption, or mistakes. A second copy is not automatically a backup.

Used in: Start here, Storage + identity, Operations, Field kit

Bare metal, virtual machine (VM), and hypervisor#

TL;DR: Bare metal runs directly on hardware; a VM is a software-created computer running under a hypervisor.

Operational detail. VMs are useful for isolation, disposable tests, and reproducible recovery, but still depend on the hypervisor host, storage, networking, and boot path. Record whether a service is an appliance, VM, or ordinary host workload.

Why it matters / common trap. A VM is not independent of its physical host, and adding a hypervisor solely for one application creates another control plane to recover.

Used in: Linux foundation, Services, Operations

Bind mount, named volume, and tmpfs#

TL;DR: Containers can receive an explicit host path, Docker-managed persistent storage, or temporary memory-backed storage.

Operational detail. Bind mounts are easy to inventory and include in host backup policy. Named volumes require supported export and restore procedures. tmpfs is for bounded disposable data. Use long bind syntax with create_host_path: false when a missing source must stop deployment.

Why it matters / common trap. Short bind syntax can create an empty local directory when the real disk or NFS mount is absent, allowing writes onto the wrong filesystem.

Used in: Linux foundation, Services

Blast radius, failure domain, and single point of failure (SPOF)#

TL;DR: These terms describe what fails together and how much else one failure or mistake can harm.

Operational detail. Map shared hosts, disks, controllers, credentials, networks, UPS outlets, rooms, providers, and administrative accounts. Separation is useful only when components do not secretly share the same failure.

Why it matters / common trap. Two replicas on one machine, power supply, administrator account, or UPS may look redundant while failing together.

Used in: Start here, Before the agent, Network + power, Storage + identity, Operations

Block device, raw disk, and durable disk ID#

TL;DR: A block device is the disk-like object below filesystems; a durable ID is safer than a changeable name such as /dev/sdb.

Operational detail. Record model, serial, WWN/EUI, /dev/disk/by-id, controller path, signatures, and physical bay in the human-controlled map. Reconcile them immediately before erasure or topology change.

Why it matters / common trap. Short Linux device names can change after reboot or cable movement. “The empty disk” is not a destructive target.

Used in: Linux foundation, Storage + identity, Field kit

Boot chain: BIOS, UEFI, EFI system partition, Secure Boot, and bootloader#

TL;DR: The boot chain is the sequence that takes a powered-off computer from firmware to a running operating system.

Operational detail. Modern installs normally use UEFI, an EFI system partition, and a bootloader. Secure Boot verifies permitted boot components. Record the chosen mode and state.

Why it matters / common trap. Changing firmware boot mode can make an installed bootloader disappear. Passing a reboot does not prove a cold boot after AC loss.

Used in: Linux foundation, Operations, Field kit

Break-glass identity#

TL;DR: A break-glass identity is a human-only emergency login that survives normal SSO, cloud, or automation failure.

Operational detail. Keep it local, independently recoverable, and tested with the relevant network or service offline. Store its recovery reference outside the system it is meant to recover.

Why it matters / common trap. A recovery account that needs the failed identity provider, DNS, password prompt, or agent is not a recovery account. Do not give it to unattended tooling.

Used in: Before the agent, Control host, Network + power, Services

Caddy, reverse proxy, and ingress#

TL;DR: A reverse proxy is a front desk for web traffic; Caddy can route standard web ports to private application backends.

Operational detail. One host-level ingress can own ports 80/443, certificates, and routing while backends bind to loopback. Validate and atomically reload its complete configuration.

Why it matters / common trap. A reverse proxy centralizes exposure but is not authorization. LAN-reachable backend ports can bypass its controls.

Used in: Services, Operations

Carrier-grade NAT (CGNAT) and double NAT#

TL;DR: CGNAT or double NAT places another translating router upstream, often preventing ordinary inbound port forwarding.

Operational detail. Compare the router WAN address with an independently observed public address. A private or 100.64.0.0/10 WAN address that differs from the public result suggests upstream NAT.

Why it matters / common trap. Home-router port forwarding may be correct yet unreachable. Do not infer CGNAT merely because a Tailscale interface also uses shared-address space.

Used in: Network + power, Field kit

Cattle vs pet#

TL;DR: A cattle host is rebuilt from external records; a pet host depends on preserving undocumented unique state.

Operational detail. A replaceable host needs off-host desired state, separated recoverable data, reissuable identities and secrets, and a rehearsed rebuild.

Why it matters / common trap. Calling a server “cattle” does not make it disposable. If nobody has rebuilt it, restored its data, or documented manual steps, it remains a pet.

Used in: Linux foundation, Operations

Certificate authority (CA), public-key infrastructure (PKI), certificate, and TLS#

TL;DR: A CA signs service identity cards; TLS uses them to authenticate a server and encrypt a connection.

Operational detail. PKI includes roots, intermediate issuers, leaf certificates, trust distribution, private keys, renewal, revocation, and recovery. A private CA serves private names; a public CA serves intentionally public names trusted by ordinary clients.

Why it matters / common trap. TLS does not decide who may use a service, replace VPN policy, or make a public application safe. Public issuance can disclose names through Certificate Transparency.

Used in: Start here, Network + power, Services

Checksum, hash, digest, and SHA-256#

TL;DR: A digest is a short fingerprint of exact bytes; SHA-256 is one common algorithm used to make it.

Operational detail. Use digests for installation media, reviewed configuration artifacts, immutable container images, and evidence manifests. Record the expected value independently and recheck the privileged source.

Why it matters / common trap. Matching bytes are not automatically safe, correctly configured, or from a trustworthy publisher.

Used in: Control host, Linux foundation, Storage + identity, Services, Field kit

CMR vs SMR#

TL;DR: CMR and SMR are hard-drive recording methods with different sustained-write and rewrite behavior.

Operational detail. SMR overlaps tracks to increase density and may behave poorly during heavy rewrites or rebuilds. Record the technology for each HDD or mark it unknown; evaluate the exact model and workload.

Why it matters / common trap. A disk can look normal during light use but struggle during resilvering. Interface and capacity alone do not prove suitability.

Used in: Storage + identity, Field kit

Cold boot, reboot, and AC-power return#

TL;DR: Restarting a running machine, starting from no power, and recovering when utility power returns are different tests.

Operational detail. Firmware settings, encryption unlock, local login, network availability, and service startup may differ. Record what starts automatically and how readiness is gated.

Why it matters / common trap. Passing reboot does not prove recovery after a long outage; a machine may wait in firmware or for disk unlock.

Used in: Control host, Linux foundation, Network + power, Operations

Cold spare#

TL;DR: A cold spare is a tested replacement disk stored offline until a specific failure needs it.

Operational detail. Label it and record which vdevs it can replace by size, sector geometry, interface, and fit. Recheck it periodically without treating it as active capacity.

Why it matters / common trap. A shelf spare provides no current redundancy, and an untested or undersized spare may be useless during recovery.

Used in: Storage + identity

Consolidated human-run command packet#

TL;DR: One small reviewed script or equivalent transaction should contain every foreseeable human-only command for a bounded change and require one invocation.

Operational detail. It names the host, user, shell, working directory, sealed inputs, preconditions, dependency closure, shell/Python/regex tests, native validators, consumer and denial tests, evidence capture, prepared rollback, and stop conditions.

Why it matters / common trap. Drip-fed commands chain the user to a terminal, hide dependency failures, and make “run that again” ambiguous. A script that mutates state without testing the outcome merely automates discovering failure in production.

Used in: Start here, Before the agent, Control host, Linux foundation, Network + power, Storage + identity, Services, Field kit

Container authority: rootful, rootless, Docker socket, and docker group#

TL;DR: Control of a rootful Docker daemon is usually control of the host, even when exposed through a socket or group membership.

Operational detail. The socket can create containers that mount host files or request broad privilege. Rootless mode reduces host privilege but changes port, cgroup, device, and UID/GID behavior.

Why it matters / common trap. A read-only mount of /var/run/docker.sock does not make its API observational. Do not grant it merely for inventory or updates.

Used in: Linux foundation, Services, Operations

Container bridge network#

TL;DR: A bridge network is a private software network joining containers on one host, usually with NAT for outbound traffic.

Operational detail. Give each Compose project its own network. Mark backend-only networks internal: true when members need no external route, and test egress separately from published inbound ports.

Why it matters / common trap. “No published port” does not stop a compromised container from reaching the Internet or local management devices.

Used in: Services

Container, image, Compose service, and Compose project#

TL;DR: An image is packaged software, a container is a running instance, a service is its declaration, and a project groups related services.

Operational detail. Compose also declares networks, mounts, secrets, health checks, dependencies, and restart policy. Render the complete model before review and use explicit project/file/environment arguments during privileged execution.

Why it matters / common trap. A container is not a tiny VM, a backup, or proof that an application is ready and usable.

Used in: Start here, Services, Operations

Context compaction, handoff, durable continuity, and transcript retention#

TL;DR: Chat can be shortened or lost, so preserve complete original records and a compact verified handoff outside the conversation.

Operational detail. Retain bring-up and later sysadmin transcripts with timestamps, targets, client/model, integrity manifest, and searchable index. Keep decisions, desired state, changes, validators, prepared rollback, and exact next action in versioned records; Git issues/history are preferred for durable decisions, but an indexed append-only archive is a valid start. Re-observe live state after resuming.

Why it matters / common trap. A runbook can drift and a summary can omit rejected approaches or failed validation. Conversation history is evidence of original intent, not current truth or authority.

Used in: Before the agent, Control host, Operations, Field kit

Control plane, data plane, and management plane#

TL;DR: The control plane decides configuration, the data plane carries ordinary work, and the management plane exposes administrative controls.

Operational detail. A VPN control service distributes identity/policy while peer traffic may flow directly. A cluster control plane schedules workloads while application traffic follows other paths. Keep management interfaces private and independently recoverable.

Why it matters / common trap. Losing coordination can block new connections even while existing traffic flows. Publishing a management surface as ordinary application traffic exposes disproportionate authority.

Used in: Start here, Control host, Network + power, Services, Operations

Copy-on-write (CoW)#

TL;DR: Copy-on-write preserves old blocks and writes changes elsewhere, making fast snapshots possible.

Operational detail. ZFS snapshots initially consume little space, then grow as live data diverges while they retain older blocks. CoW supports history and consistency mechanisms but not an independent copy.

Why it matters / common trap. An instant snapshot is not free forever or safe from pool loss.

Used in: Storage + identity

Credential, secret, key, token, and credential reference#

TL;DR: These prove identity, unlock data, or authorize operations; a reference records where recovery material belongs without exposing its value.

Operational detail. Record owner, issuer, consumer, scope, expiry, rotation, revocation, unattended-start behavior, and recovery. Keep values out of Git, chat, shell history, broad environment variables, and model-readable evidence.

Why it matters / common trap. A private repository is still readable by its tools. Mode 0600 does not hide a key from every process running as its owner.

Used in: Before the agent, Control host, Network + power, Storage + identity, Services, Field kit

Cross-model review#

TL;DR: Give identical sanitized facts to independent models, archive their answers before cross-sharing, and resolve disagreement with evidence.

Operational detail. Reviewers receive no mutation tools, credentials, private-network route, or another reviewer’s conclusion. Select an appropriate model/reasoning effort and record quota size. Exactly one separately authorized operator writes.

Why it matters / common trap. Agreement is not proof when models may repeat the same stale source. Screen-control automation does not exist merely because a workflow says “send”; permission and test it before need, with manual attach/paste as fallback.

Used in: Before the agent, Control host, Field kit

Daemon, service, systemd unit, timer, drop-in, and target#

TL;DR: These are background processes and the declarations that control when, how, and in what order they run.

Operational detail. Systemd units describe services, mounts, timers, dependencies, and boot milestones. Use supported drop-ins rather than editing vendor files; inspect effective configuration, distinguish active from enabled, retain prior-boot logs, and test after reboot.

Why it matters / common trap. A manually restarted process can hide missing boot policy or dependency ordering. Package updates may overwrite edits to vendor unit files.

Used in: Linux foundation, Services, Operations

Dataset, storage pool, and vdev#

TL;DR: A ZFS pool is the whole storage system, a vdev is one redundancy building block, and a dataset is a policy/filesystem boundary.

Operational detail. ZFS stripes across top-level vdevs, so losing one top-level data vdev can lose the pool. Datasets can carry different snapshot, quota, encryption, ACL, and mount policies while sharing capacity.

Why it matters / common trap. Adding one bare disk to mirrored vdevs can remove effective redundancy. A dataset is not physically separate capacity unless quotas or reservations enforce it.

Used in: Start here, Storage + identity, Field kit

Deduplication#

TL;DR: Deduplication stores identical data blocks only once, at a potentially substantial memory and metadata cost.

Operational detail. ZFS dedup adds long-lived resource and recovery complexity. Ordinary compression is the baseline; enable dedup only for a measured and sized workload.

Why it matters / common trap. Dedup is not free capacity and is not the same mechanism as backup-level deduplication.

Used in: Storage + identity

Default deny and fail closed#

TL;DR: Block anything not explicitly allowed, and stop when a safety dependency or check is missing.

Operational detail. Apply these principles to firewalls, VPN grants, agent approvals, mount preflights, secret loading, backup completeness, and deployment validation. Test at least one forbidden path.

Why it matters / common trap. Successful allowed behavior does not prove a boundary. Convenience fallbacks such as creating an absent mount directory or bypassing an unavailable approval can silently widen authority.

Used in: Before the agent, Linux foundation, Network + power, Storage + identity, Services

Dependency graph and dependency closure#

TL;DR: A dependency graph shows what relies on what; a dependency closure contains every input needed to interpret or install one configuration.

Operational detail. Map service, storage, DNS, identity, network, power, and recovery dependencies. Render complete configuration closures so privileged validation cannot discover an unreviewed include, variable, or .env file later.

Why it matters / common trap. Hidden or circular dependencies break recovery—for example, a VPN needing DNS that can only be repaired through that VPN.

Used in: Start here, Control host, Network + power, Services, Field kit

Desired state, observed state, and last-known-good state#

TL;DR: Keep separate records for what should exist, what exists now, and the most recent state that actually passed its tests.

Operational detail. Timestamp each with evidence. After a pause, alert, handoff, or compaction, re-observe the facts required by the next action before mutation.

Why it matters / common trap. A Git file, runbook, dashboard, or transcript can be right about yesterday and wrong about now.

Used in: Before the agent, Control host, Operations, Field kit

Destructive authorization#

TL;DR: Destructive work needs a fresh human-protected approval bound to one exact live target and operation.

Operational detail. Bind it to serial/WWN, by-id, host, pool GUID, physical bay, existing signatures, preservation choice, backup/restore evidence, window, expiry, and expected postcondition. Reverify immediately before use.

Why it matters / common trap. Inventory, an old chat approval, or “empty disk” is not standing permission to erase. Any mismatch must stop execution.

Used in: Storage + identity, Field kit

DHCP, lease, pool, and reservation#

TL;DR: DHCP assigns network settings; a reservation gives known hardware a stable address from one authoritative service.

Operational detail. Keep one DHCP authority. Reserve stable infrastructure addresses centrally where possible, and keep unavoidable host statics outside the dynamic pool.

Why it matters / common trap. Two DHCP servers or a static address inside the pool can produce intermittent failures that look like DNS or firewall defects.

Used in: Start here, Linux foundation, Network + power, Field kit

Direct-IP and direct-Ethernet recovery path#

TL;DR: A labeled cable and fixed addresses let the control Mac reach a server without router, Wi-Fi, DHCP, DNS, VPN, or Internet.

Operational detail. Reserve a collision-free non-routed subnet with no gateway, DNS server, or search domain. Bind the recovery NIC by MAC address, constrain SSH, pin the host key, and drill reboot and route cleanup.

Why it matters / common trap. “Connect directly” is not a recovery path unless the cable, adapter, addresses, firewall, keys, and successful test already exist.

Used in: Start here, Linux foundation, Network + power, Field kit

DNS, resolver, upstream resolver, A record, AAAA record, and reverse record#

TL;DR: DNS translates names; A records return IPv4, AAAA records return IPv6, and reverse records map addresses back to names.

Operational detail. Distinguish the client resolver, authoritative private records, and upstream recursion. Private and public answers may come from different views. Preserve direct-IP recovery.

Why it matters / common trap. A public resolver advertised as Pi-hole's “secondary” cannot answer private names and may be chosen unpredictably.

Used in: Start here, Network + power, Operations, Field kit

Dynamic DNS (DDNS)#

TL;DR: Dynamic DNS updates a public name when a residential public address changes.

Operational detail. It is useful for intentional publication or a plain WireGuard endpoint. Managed outbound-established overlays generally do not require it.

Why it matters / common trap. A public name does not make CGNAT reachable, and descriptive names can disclose metadata.

Used in: Network + power

Egress vs ingress#

TL;DR: Ingress enters a system; egress leaves it, and both need separate IPv4 and IPv6 policy.

Operational detail. A service may expose no inbound listener yet retain broad outbound reach to the Internet or management LAN. Test both directions.

Why it matters / common trap. “Nothing is published” does not stop a compromised process from probing infrastructure or exfiltrating mounted data.

Used in: Before the agent, Control host, Network + power, Services

Encryption at rest, full-disk encryption, dataset encryption, and FileVault#

TL;DR: Encryption protects stored bytes with a key, but may trade theft protection against unattended reboot and recovery.

Operational detail. Full-disk encryption may require a human before networking starts. Dataset encryption can align different keys with different data classes. Keep recovery keys outside the protected machine and its backup.

Why it matters / common trap. Disabling encryption for convenience sacrifices theft protection; enabling it without a drilled unlock path turns outages into visits.

Used in: Control host, Linux foundation, Storage + identity, Field kit

EUI, WWN, UUID, and GUID#

TL;DR: These durable identifiers name hardware, filesystems, or pools more reliably than transient device names.

Operational detail. Combine the correct layer's ID with the human-only physical bay, cable, controller, and serial map. Reconcile against live state.

Why it matters / common trap. No single ID proves which physical disk a person will pull, and stale inventory can still be wrong.

Used in: Linux foundation, Storage + identity, Field kit

Exposure class#

TL;DR: An exposure class says exactly who can reach a service and which path is used for administration.

Operational detail. The guide uses intentional public, LAN/VPN, VPN-only, independent recovery, and documented mixed exceptions. Record listeners, sources, authentication, metadata, and outside denial tests.

Why it matters / common trap. “Internal” is too vague; IPv6, all-interface binds, or a shared public admin/user endpoint can defeat the intention.

Used in: Start here, Network + power, Services, Field kit

ext4#

TL;DR: ext4 is a common Linux filesystem with broad rescue-tool support and a straightforward role as the guide's OS-disk default.

Operational detail. Its journal helps restore consistent metadata after a crash. Data checksumming, redundant repair, snapshots, and pooling are separate decisions handled elsewhere.

Why it matters / common trap. Journaling is not redundancy or backup. Unneeded LVM, encryption, or ZFS-root layers complicate recovery.

Used in: Linux foundation, Storage + identity

Extended attribute (xattr)#

TL;DR: An extended attribute stores small metadata attached to a file beyond its name, contents, owner, group, and basic mode bits.

Operational detail. ACLs, macOS metadata, Linux capabilities, security labels, and application tags may use xattrs. Confirm that the source filesystem, network protocol, copy tool, archive format, and backup restore all preserve the namespaces the workload needs.

Why it matters / common trap. A byte-for-byte file copy can still lose behavior when xattrs or ACLs disappear. Uncritically preserving security-sensitive attributes across hosts can also grant capabilities or labels that were not intended in the destination.

Used in: Linux foundation, Storage + identity, Operations, Field kit

File ownership, Unix mode, 0600, chmod, and chown#

TL;DR: Unix owner, group, and mode bits control basic file access; chmod and chown change them.

Operational detail. Mode 0600 permits only the owner under ordinary checks. ACLs may add rules; root and processes running as the owner can still access the file.

Why it matters / common trap. 0600 does not hide a credential from the agent running as that account. Recursive 777 or ownership changes destroy policy.

Used in: Control host, Storage + identity, Services

Filesystem, partition, volume, mount, and mountpoint#

TL;DR: These are different layers from disk subdivision through the directory where stored files become visible.

Operational detail. Verify source, filesystem type, options, and mount identity with tools such as findmnt. Declare local and network mount dependencies before workloads start.

Why it matters / common trap. An empty directory remains when its intended filesystem is absent, allowing an application to write to the OS disk.

Used in: Linux foundation, Storage + identity, Services

Firewall, stateful firewall, source-constrained rule, and UFW#

TL;DR: A firewall controls traffic; a stateful, source-constrained rule admits only intended sources and their expected replies.

Operational detail. Cover IPv4 and IPv6, preserve an independent management path, inspect listeners, and test both allowed and denied sources. Docker traffic needs separate verification.

Why it matters / common trap. The broadband router does not constrain flat-LAN peers, and container-published ports may bypass an expected UFW path.

Used in: Linux foundation, Network + power, Services, Operations

Firmware, BIOS, and baseboard management controller (BMC)#

TL;DR: Firmware runs below the operating system; a BMC adds powerful hardware-level management and power control.

Operational detail. Record exact model/version, stable power, changed settings, source, recovery procedure, and AC-return behavior. Keep BMC access private and independently credentialed.

Why it matters / common trap. Firmware rollback may be impossible, and an exposed BMC bypasses the main OS firewall.

Used in: Linux foundation, Network + power, Operations

Forced SSH command#

TL;DR: A forced SSH command makes one key run a fixed server-side program instead of receiving an arbitrary shell.

Operational detail. Pair it with source restrictions and disabled TCP, agent, X11, and PTY forwarding. The program is root-owned, validates inputs, emits bounded redacted output, and receives bypass tests.

Why it matters / common trap. Calling a general shell “observer” does not make it read-only; forwarding can turn a narrow login into a route elsewhere.

Used in: Before the agent, Control host, Linux foundation

FreeIPA, LDAP, Active Directory (AD/AD DS), and Kerberos#

TL;DR: These systems centralize identities and authentication, but add DNS, time, backup, and recovery dependencies.

Operational detail. LDAP stores directory data; Kerberos issues cryptographic tickets. FreeIPA combines Linux-oriented directory, Kerberos, host, policy, and certificate services; Active Directory provides a Windows domain. Preserve numeric IDs during migration.

Why it matters / common trap. Web SSO does not align UID/GID, authenticate NFS, or domain-join Windows clients. Centralization for one convenience can create a large failure domain.

Used in: Start here, Storage + identity, Services

Git repository, working tree, diff, commit, remote, push, and revert#

TL;DR: Git records versioned text intent and history; it is not a backup for databases, household files, or secrets.

Operational detail. The working tree is editable, a diff shows changes, a commit records a checkpoint, push copies commits to a remote, and revert creates an auditable undo commit. Use small coherent commits and scan staged content for secrets.

Why it matters / common trap. A private remote remains readable by its authorized tools and does not restore application data.

Used in: Start here, Control host, Linux foundation, Field kit

Graceful shutdown, quiescing, and load shedding#

TL;DR: Stop writes cleanly and shed lower-priority load so essential control and networking last until the end of battery runtime.

Operational detail. Measure real application quiesce, filesystem flush, host shutdown, and remaining UPS runtime under the accepted load. Shut the coordinator down last.

Why it matters / common trap. Fixed timings copied from another rack ignore battery age, workload, and dependency order.

Used in: Network + power, Storage + identity, Services, Operations

Grant, authority, and enforcement point#

TL;DR: A grant records human permission; authority is the real ability to act, and an independent enforcement point decides whether the action proceeds.

Operational detail. Verify grant ID, issuer, integrity, validity window, target, verbs, attempt limits, and revocation. An agent-written work order can reference but cannot create or expand it.

Why it matters / common trap. Permission in chat or Git is prose unless the target or human privilege boundary enforces it. Urgency does not manufacture authority.

Used in: Before the agent, Control host, Network + power, Storage + identity, Services, Operations, Field kit

Group Policy#

TL;DR: Group Policy centrally configures Windows users and computers joined to Active Directory.

Operational detail. It can manage security settings, software behavior, and account policy, but brings domain controllers, DNS, replication, backup, and recovery requirements.

Why it matters / common trap. It is useful for real centralized Windows management, not merely to simplify one SMB login.

Used in: Storage + identity

Hard link#

TL;DR: A hard link is another filename for the same underlying file and cannot cross filesystem boundaries.

Operational detail. Media downloaders and importers need consistent same-filesystem paths for hard linking and atomic moves.

Why it matters / common trap. Separate mounts that look tidy can force full copies and break atomic imports.

Used in: Services

Hardware burn-in#

TL;DR: Burn-in stresses and observes recycled hardware before trusting it with important work or data.

Operational detail. Exercise memory, CPU, temperatures, throttling, NICs, storage ports, cables, controllers, and power-return behavior. Preserve SMART/NVMe results and kernel errors as evidence.

Why it matters / common trap. Hardware stable under light desktop use may fail under server load. Restart loops must not conceal memory, thermal, link, or firmware faults.

Used in: Linux foundation, Network + power

HBA, JBOD, hardware RAID, and fake RAID#

TL;DR: HBA/JBOD paths expose individual disks; hardware or fake RAID combines or hides them behind a controller volume.

Operational detail. ZFS should see disk identity, errors, sector behavior, and redundant copies directly. Record controller firmware, ports, cables, cooling, cache behavior, and serial visibility.

Why it matters / common trap. Controller RAID can hide failing members or misleadingly report success; even a passive HBA needs proper airflow.

Used in: Linux foundation, Network + power, Storage + identity

Headroom, quota, and reservation#

TL;DR: Headroom is spare capacity, a quota caps use, and a reservation guarantees capacity to one dataset or workload.

Operational detail. Include growth, snapshot churn, restore workspace, and operating margin. Bound caches, downloads, transcodes, and restore staging; reserve space only when required.

Why it matters / common trap. A nearly full pool can remain online but become slow and hard to recover; excess reservations create artificial scarcity.

Used in: Storage + identity, Services, Field kit

Health check, readiness check, liveness check, and startup check#

TL;DR: These answer different questions: started, ready for traffic, still functioning, or still within normal startup.

Operational detail. Docker health is observational and does not by itself restart a running unhealthy container. Kubernetes probes affect different lifecycle decisions and need separate thresholds.

Why it matters / common trap. A process can run while the service is unusable; aggressive liveness can repeatedly kill a slow but recoverable application.

Used in: Services, Operations

Heartbeat, dead-man check, black-box monitoring, and white-box monitoring#

TL;DR: These reveal absence, user-visible failure, or internal trouble from different vantage points.

Operational detail. Put at least one monitor outside the home failure domain. Use outbound authenticated heartbeats for private outcomes and external protocol checks for deliberately public services. Monitors receive no remediation authority.

Why it matters / common trap. An internal dashboard cannot report its own, router, ISP, or total power failure. Green process metrics do not prove user success.

Used in: Network + power, Operations, Field kit

High availability (HA), quorum, and single point of failure (SPOF)#

TL;DR: HA means surviving named failures; quorum is the majority a distributed control system needs to decide safely.

Operational detail. Three k3s servers may give control-plane quorum, yet storage, ingress, router, UPS, room, account, and application state remain separate failure domains.

Why it matters / common trap. “HA” without the exact failure survived is marketing. Multiple containers do not make one database or uplink redundant.

Used in: Storage + identity, Operations

Host networking and network namespace#

TL;DR: A network namespace gives a workload its own network view; host networking shares the machine's interfaces, addresses, and ports.

Operational detail. Bridge networking normally supplies separation and explicit port publication. Host mode may be needed for a discovery-heavy application but requires a recorded exception and listener/firewall tests.

Why it matters / common trap. Host networking is not just a performance switch; it widens what a workload can reach and expose.

Used in: Services, Operations

Host-key fingerprint#

TL;DR: An SSH host-key fingerprint identifies the server, not the person connecting to it.

Operational detail. Verify the first fingerprint through a console or recovery record, pin it, and record intentional rebuild changes.

Why it matters / common trap. Accepting an unknown changed key during an incident can connect to the wrong or intercepted host.

Used in: Control host, Linux foundation, Network + power, Field kit

Hot remote storage#

TL;DR: Hot remote storage stays directly usable elsewhere; it is not automatically a backup.

Operational detail. Name the authoritative writer, cache/replica/sync role, offline-write policy, conflicts, consistency, latency, bandwidth, and credential behavior. Run applications near live databases where possible.

Why it matters / common trap. Sync can propagate deletion or ransomware, and WAN filesystems may violate locking and latency assumptions.

Used in: Storage + identity

I/O and IOPS#

TL;DR: I/O is data moving into or out of storage; IOPS measures how many separate input/output operations happen each second.

Operational detail. Large sequential media transfers and small random database or VM operations stress storage differently. Mirrors commonly provide better random I/O and pairwise growth, while wider parity layouts may provide better sequential capacity efficiency.

Why it matters / common trap. Total terabytes and headline transfer speed do not describe a workload. A layout optimized for large media files may behave poorly for databases, VMs, or many concurrent small operations.

Used in: Storage + identity, Services

Identity provider (IdP), single sign-on (SSO), OpenID Connect (OIDC), multi-factor authentication (MFA), and passkey#

TL;DR: An identity provider lets one account authenticate to multiple services; OIDC is a common web-login protocol, MFA adds another factor, and a passkey is a phishing-resistant credential.

Operational detail. Preserve local break-glass accounts for recovery, test identity-provider outages, and keep infrastructure identities separate from provider logins. Native OIDC integration usually handles sessions, logout, groups, APIs, and mobile clients better than generic proxy authentication.

Why it matters / common trap. Web SSO does not align Unix UID/GID ownership, authenticate NFS, or replace SMB identities. Making DNS, VPN, backup recovery, or the identity provider itself depend exclusively on SSO creates circular recovery.

Used in: Start here, Before the agent, Control host, Network + power, Storage + identity, Services

Identity: UID, GID, POSIX principal, and service account#

TL;DR: A UID identifies a Unix user, a GID identifies a group, and files store those numbers rather than the friendly names shown on screen.

Operational detail. Allocate non-overlapping numeric ranges for people, groups, services, agents, directories, and subordinate container IDs. Preserve the same principal numbers on every host that accesses shared files, and restore identity before mounting recovered data read-write.

Why it matters / common trap. If the same number means Plex on one host and a child on another, NFS and restored files cannot recover the human intention. Matching names with different numbers does not fix ownership.

Used in: Start here, Linux foundation, Storage + identity, Services, Field kit

Image tag vs image digest#

TL;DR: A container-image tag is a movable human-readable label; a digest identifies exact immutable image content.

Operational detail. Record a meaningful version tag for provenance and pin the deployed image by publisher digest. Before changing it, read release and migration notes, resolve the new digest without starting it, and preserve the previous release and application recovery point.

Why it matters / common trap. Tags such as latest, stable, or public can silently begin referring to different bytes. A digest fixes content but does not prove that the image is safe or compatible.

Used in: Services, Operations, Field kit

Incident grouping, deduplication, inhibition, and silence#

TL;DR: These mechanisms combine repeated alerts, suppress predictable child symptoms, or temporarily mute known maintenance noise.

Operational detail. An incident should retain a stable identity, affected outcome, start and latest-observed times, parent dependency, acknowledgement, action, and resolution condition. When the whole site is unreachable, inhibit derivative DNS, host, and application alerts.

Why it matters / common trap. Four alerts caused by one failed router are one incident, not four independent emergencies. A silence must not hide an unresolved failure after its maintenance reason expires.

Used in: Network + power, Operations, Field kit

Interface, network interface card (NIC), and MAC address#

TL;DR: A network interface is the operating-system view of a network port; a NIC is the hardware, and its MAC address is a link-layer identifier.

Operational detail. Record driver, negotiated speed, physical port label, addresses, and MAC. Use MAC matching for stable DHCP reservations and recovery-interface naming, while keeping exact household topology in the protected identity map.

Why it matters / common trap. Linux interface names can change when hardware moves. A MAC address is useful for local identification but is neither a secret credential nor harmless public metadata.

Used in: Linux foundation, Network + power, Field kit

IOMMU#

TL;DR: An IOMMU controls how hardware devices access memory, supporting safer virtualization and device assignment.

Operational detail. Enable CPU virtualization and IOMMU in firmware when the exact platform supports them reliably, but defer installing a hypervisor or passing devices through until a workload requires it.

Why it matters / common trap. IOMMU support does not make arbitrary GPU, disk-controller, USB, or network-device access safe. Device passthrough can give a workload authority outside ordinary container or VM boundaries.

Used in: Linux foundation, Services

IP address, subnet, prefix, route, and default gateway#

TL;DR: An IP address identifies a network interface, a subnet or prefix describes a local address range, and a route tells traffic where to go.

Operational detail. The default gateway is the catch-all route for destinations not reached more specifically. A direct-recovery network deliberately has fixed addresses but no gateway, DNS server, or search domain so it cannot attract ordinary Internet traffic.

Why it matters / common trap. Assigning an address does not prove that replies take the intended path. Overlapping VPN, LAN, container, and recovery subnets can cause intermittent or misleading routing failures.

Used in: Linux foundation, Network + power, Field kit

IPv4, IPv6, and RFC 1918 private addressing#

TL;DR: IPv4 and IPv6 are two Internet addressing systems; RFC 1918 defines familiar private IPv4 ranges used inside homes.

Operational detail. Inventory addresses, routes, DNS resolvers, listeners, and firewall behavior for both families. Globally scoped IPv6 does not imply permission, and the router should reject unsolicited inbound traffic unless an explicit rule allows it.

Why it matters / common trap. A design can be secure over IPv4 while accidentally exposed or bypassing Pi-hole over IPv6. IPv4 NAT's incidental inbound barrier must not be mistaken for a general firewall policy.

Used in: Control host, Linux foundation, Network + power, Services, Field kit

Journal, filesystem journaling, and journalctl#

TL;DR: A filesystem journal helps recover consistent metadata after a crash; the systemd journal stores structured service and boot logs.

Operational detail. Use journalctl to inspect one service, the current boot, and the previous boot. Configure persistent retention sufficient for diagnosis without allowing logs to fill the OS disk.

Why it matters / common trap. These are two different kinds of journal. Filesystem journaling does not preserve application history or prove data integrity, and current service output may omit the failure that occurred before reboot.

Used in: Linux foundation, Operations

Just in time (JIT)#

TL;DR: Just-in-time design adds a component, record, or permission when a real consumer needs it, not merely because it may be useful someday.

Operational detail. Defer private CA, VLAN, NFS, SSO, PDU switching, GPU, Kubernetes, and other complexity until an observed requirement reaches their entry gate. Prepare prerequisites early only when delaying them would make later recovery expensive.

Why it matters / common trap. Speculative infrastructure creates update, backup, credential, and recovery work before it produces value. Deferral is disciplined option preservation, not neglect.

Used in: Start here, Network + power, Storage + identity, Services, Field kit

k3s embedded etcd and quorum#

TL;DR: etcd stores Kubernetes control-plane state; quorum means a majority of its members must agree.

Operational detail. An embedded-etcd k3s control plane requires at least three server nodes and an odd count for high availability. Back up the datastore and retain the original server token needed to decrypt bootstrap data.

Why it matters / common trap. One k3s server plus one agent adds workload capacity but leaves a control-plane single point of failure. Three servers still do not make application data or ingress highly available.

Used in: Operations

Kerberos, keytab, and service principal#

TL;DR: Kerberos issues time-limited tickets proving identities; a service principal names a service, and a keytab stores its machine credential.

Operational detail. Kerberos depends heavily on correct DNS, synchronized time, identity lifecycle, protected keys, and recovery. It can authenticate NFS users cryptographically and underpins FreeIPA and Active Directory environments.

Why it matters / common trap. A keytab is a powerful unattended credential, not ordinary configuration. Adding Kerberos to solve one password inconvenience creates a directory, time, DNS, backup, and recovery commitment.

Used in: Storage + identity, Services

Key expiry, rotation, and revocation#

TL;DR: Expiry ends a credential automatically, rotation replaces it, and revocation invalidates it deliberately.

Operational detail. Record owner, target, scope, lifetime, renewal path, loss response, and revocation test. For overlay systems, distinguish revoking an enrollment key from removing the already-enrolled machine identity.

Why it matters / common trap. A durable unattended key can strand a remote server when it expires, while a non-expiring key increases theft exposure. Deleting one credential does not necessarily revoke every identity it created.

Used in: Before the agent, Control host, Network + power, Services, Field kit

Keyboard-video-mouse console (KVM), PiKVM, BMC, and out-of-band management#

TL;DR: Out-of-band management provides console or power control below the ordinary operating system and SSH path.

Operational detail. Keep the console device on protected power and reachable only through the VPN or local recovery network. Use separate read-only and power credentials, disable unnecessary terminal or virtual-media features, and require interlocks for reset or hard power.

Why it matters / common trap. A web KVM or BMC can expose firmware, boot media, credentials, and destructive power controls. A cloud-dependent smart plug on the same failed Wi-Fi is not out-of-band recovery.

Used in: Network + power, Operations, Field kit

Kubernetes and k3s: cluster, server, agent, node, Pod, controller, and reconciliation#

TL;DR: Kubernetes continually compares declared state with reality and creates, replaces, or moves workloads; k3s is a compact Kubernetes distribution.

Operational detail. A cluster contains nodes. Server nodes run the control plane, agent nodes run workloads, Pods are workload units, and controllers reconcile them. Migrate only after multi-host placement or Compose toil becomes a recurring measured problem.

Why it matters / common trap. Kubernetes can restart a container elsewhere but cannot make a single database, NFS mount, storage server, router, or household uplink resilient. Generated manifests are not an operating model.

Used in: Start here, Services, Operations

Kubernetes CNI and NetworkPolicy#

TL;DR: The CNI implements cluster networking; NetworkPolicy declares which traffic workloads may send and receive.

Operational detail. Apply default-deny ingress and egress, then permit DNS and named dependencies. Verify that the installed k3s CNI or policy controller actually enforces both directions using disposable allowed and denied probes.

Why it matters / common trap. A stored NetworkPolicy object is not proof of enforcement. Unsupported egress policy can leave workloads able to reach the Internet, management LAN, or other namespaces.

Used in: Operations

Kubernetes security: namespace, RBAC, service account, Secret, admission, and Pod Security Standards#

TL;DR: These mechanisms divide cluster resources and control what users and workloads may request or access.

Operational detail. Separate namespaces by trust, apply the restricted Pod Security profile, use narrow service accounts, disable automatic token mounting where unnecessary, keep secret values outside the model, and reject host paths, privileged containers, host namespaces, and unapproved devices at admission.

Why it matters / common trap. Permission to create a Pod may indirectly grant access to its service account, mounted Secrets, host paths, devices, or node features. Namespace-scoped RBAC alone is not containment.

Used in: Operations

LAN vs WAN#

TL;DR: The LAN is the local home network; the WAN side connects the router toward the provider and Internet.

Operational detail. Inventory both separately, including LAN settings, WAN address class, upstream equipment, IPv6 delegation, and filtering. Tier 0 recovery should continue when WAN is disconnected.

Why it matters / common trap. A WAN failure should not remove local administration; router WAN DNS is not the same as DNS advertised to LAN clients.

Used in: Start here, Linux foundation, Network + power, Field kit

Least privilege#

TL;DR: Least privilege gives each identity only the paths, verbs, targets, time, and reachability its job needs.

Operational detail. Separate human, agent, service, backup, retention, and recovery identities; test both allowed work and forbidden attempts; make revocation independent.

Why it matters / common trap. A narrow role name cannot constrain broad sudo, Docker-socket access, shared administrator tokens, or a human SSH identity.

Used in: Before the agent, Control host, Linux foundation, Network + power, Storage + identity, Services

Lights-out operation#

TL;DR: Lights-out operation means routine work and ordinary failures can be handled without visiting the equipment.

Operational detail. It requires tested remote entry, power behavior, observable state, graceful shutdown, recovery credentials, and independent paths around failed services.

Why it matters / common trap. It does not mean every failure is remotely recoverable or that an agent may hard-cycle equipment whenever software looks unhealthy.

Used in: Start here, Control host, Network + power, Operations

Linux distribution, LTS, APT repository, PPA, package pin, and release channel#

TL;DR: These define the supported operating-system family and where versioned packages and updates come from.

Operational detail. Prefer a supported LTS and official repositories. Record each third-party source's owner, signing-key fingerprint, supported releases, update path, removal procedure, and chosen pin/channel.

Why it matters / common trap. Every new source can execute privileged code during updates. “Stable” and “latest” are moving labels, not reproducible versions.

Used in: Linux foundation, Services, Operations, Field kit

Listener, port, socket, and protocol#

TL;DR: A listener waits for connections, a port identifies a network endpoint, a socket is a communication endpoint, and a protocol defines the conversation.

Operational detail. Record bind address, transport, consumers, permitted sources, authentication, and denial tests. Unix sockets such as Docker's may expose control without a TCP port.

Why it matters / common trap. “Port 443” does not prove TLS or safe authentication; a process may listen on every interface when loopback was intended.

Used in: Linux foundation, Network + power, Services, Operations

Log rotation and persistent logs#

TL;DR: Persistent logs survive reboot; rotation bounds the disk space and history they consume.

Operational detail. Retain prior-boot evidence, bound Docker logging, and keep complete bring-up/sysadmin transcripts in separate searchable records where practical.

Why it matters / common trap. Volatile logs erase the cause during reboot, while unlimited logs can fill the OS disk.

Used in: Control host, Linux foundation, Services, Operations

Logical Volume Manager (LVM)#

TL;DR: LVM adds flexible logical storage between physical disks or partitions and filesystems.

Operational detail. It can resize and separate OS volumes but adds volume groups, logical volumes, allocation policy, and another recovery layer.

Why it matters / common trap. An unnecessary thin or undersized logical volume can fill while unused physical capacity exists elsewhere.

Used in: Linux foundation, Storage + identity

Loopback (127.0.0.1 and ::1)#

TL;DR: Loopback is networking that remains inside one machine.

Operational detail. Bind web backends to IPv4 and, where used, IPv6 loopback; let ingress own LAN-facing ports and verify the backend is unreachable externally.

Why it matters / common trap. Omitting a host address from a container port mapping commonly binds every interface and bypasses the reverse proxy.

Used in: Services

Mac vs MAC address#

TL;DR: A Mac is an Apple computer; a MAC address is a network-interface identifier.

Operational detail. Spell out “MAC address” when both meanings occur nearby; use it for interface matching and reservations while treating it as sensitive topology data.

Why it matters / common trap. “Mac ID” can ambiguously refer to hardware, network interface, account, or computer.

Used in: Control host, Linux foundation, Network + power, Field kit

Maintenance window and change freeze#

TL;DR: A maintenance window permits bounded disruptive work; a change freeze blocks nonessential changes.

Operational detail. Record start, expiry, affected tiers, owner, rollback, recovery path, and notification expectations. Freeze risky platform work before travel.

Why it matters / common trap. “Tonight” is not a bounded window, and an old window or handoff is not standing permission.

Used in: Linux foundation, Network + power, Storage + identity, Services, Operations, Field kit

Manifest, desired state, source of truth, and authoritative copy#

TL;DR: A manifest records intended configuration; the source of truth is the one place authoritative for a decision or writable dataset.

Operational detail. Version manifests, render target configuration from them, compare against live state, and name one authoritative writable copy for remote data.

Why it matters / common trap. A manifest may be stale and does not apply itself; two writable sources of truth create unsafe conflicts.

Used in: Control host, Network + power, Storage + identity, Services, Operations

Migration, cutover, and soak period#

TL;DR: Migration copies and verifies, cutover redirects consumers, and the soak period watches the new path while preserving rollback.

Operational detail. Keep the source authoritative during initial copy, quiesce writers, switch a representative client first, test, and retain the source unchanged.

Why it matters / common trap. Migration is not a move; deletion flags, early source reuse, or two writers can consume rollback.

Used in: Storage + identity, Services, Operations

Mirror#

TL;DR: A mirror stores equivalent copies of each block on multiple disks within one vdev.

Operational detail. A two-way mirror can usually continue after either member fails and grows by adding another mirror pair; replace members one at a time.

Why it matters / common trap. A mirror protects against some disk failures, not deletion, ransomware, fire, theft, controller mistakes, or pool destruction.

Used in: Start here, Storage + identity

Model-safe view, opaque ID, and human-only identity map#

TL;DR: A model-safe view preserves useful facts while replacing exact household or hardware identifiers with stable placeholders.

Operational detail. Keep serials, WWNs, MACs, WAN addresses, and account IDs outside agent-readable ACLs; resolve destructive targets locally or with explicit provider consent.

Why it matters / common trap. Sanitization fails if the raw map remains in an agent-readable sibling directory, Git history, or chat attachment.

Used in: Control host, Storage + identity, Field kit

Model, reasoning or thinking effort, workload size, quota, buffet subscription, and API billing#

TL;DR: Choose model capability and reasoning effort for the job, and describe expected usage as tiny, small, medium, large, or XL.

Operational detail. Show users quota/reset feedback during onboarding, discuss plan adequacy before long work, prefer subscription allowance, and treat separately billed API use as explicit exception.

Why it matters / common trap. One agent with an unsuitable model, effort, or free quota can stall halfway through challenging infrastructure work.

Used in: Before the agent, Control host, Field kit

Mount ordering: _netdev, nofail, RequiresMountsFor=, Requires=, and After=#

TL;DR: These systemd declarations describe when storage is ready and which services must wait for it.

Operational detail. _netdev marks network dependence, nofail permits boot, and unit dependencies stop workloads until required mounts and probes succeed.

Why it matters / common trap. nofail does not make it safe to write into the empty directory beneath a missing mount.

Used in: Linux foundation, Storage + identity, Services

Multicast and service discovery#

TL;DR: Multicast lets devices announce or discover services among nearby peers without knowing each address first.

Operational detail. Printer, media, and automation discovery may depend on it; guest networks, VLANs, VPNs, and bridges may block it deliberately.

Why it matters / common trap. Broadly bridging networks to “fix” discovery can erase intended isolation.

Used in: Network + power, Services

NAT, port forwarding, UPnP, NAT-PMP, and PCP#

TL;DR: NAT translates addresses, port forwarding maps inbound traffic deliberately, and UPnP/NAT-PMP/PCP can create mappings automatically.

Operational detail. Disable automatic mapping by default, inventory forwards, and add only intentional public exceptions with external tests; handle IPv6 separately.

Why it matters / common trap. A compromised household device can publish a service that policy intended to keep private.

Used in: Network + power, Services

NetBIOS name, SID, passdb, tdbsam, and group mapping#

TL;DR: These are parts of Samba's Windows-facing identity state beyond ordinary Unix usernames.

Operational detail. Record the machine name/SID, passdb backend and backup, persistent paths, and Windows-to-Unix group mappings; restore them before SID-bearing ACLs.

Why it matters / common trap. Matching UID/GID values alone does not preserve Windows ACL meaning after a Samba rebuild.

Used in: Storage + identity, Field kit

Netplan#

TL;DR: Netplan is Ubuntu's declarative network-configuration layer.

Operational detail. Render complete YAML, match recovery hardware by MAC, validate, apply through an independent path with timed rollback, and inspect actual routes.

Why it matters / common trap. Valid YAML can still express the wrong interface, route, or gateway.

Used in: Linux foundation, Field kit

Network protocol cheat sheet: DNS, DHCP, HTTP(S), SSH, NFS, SMB, and SNMP#

TL;DR: A protocol defines how systems communicate; knowing each service's purpose, transport, default ports, and trust boundary makes firewall and troubleshooting work tractable.

Operational detail. DNS resolves names, DHCP leases network settings, HTTP or HTTPS carries web traffic, SSH provides remote shells and tunnels, NFS and SMB share files, and SNMP exposes device telemetry. Record actual listeners and flows rather than relying only on customary port numbers.

Why it matters / common trap. Opening a familiar port does not prove the intended protocol is safe or even present. Encryption, authentication, discovery traffic, dynamic ports, and directionality vary; permit the narrow observed path and test it from the real client network.

Used in: Control host, Linux foundation, Network + power, Storage + identity, Services, Field kit

Network UPS Tools (NUT)#

TL;DR: NUT reads UPS status and coordinates orderly shutdown among machines sharing protected power.

Operational detail. Put the primary on a stable machine powered late; use root-owned shutdown services and give agents telemetry rather than forced-shutdown authority.

Why it matters / common trap. USB presence does not prove compatibility, and arbitrary output-cut authority can turn monitoring error into outage.

Used in: Network + power, Operations

Network-attached storage (NAS)#

TL;DR: A NAS is a machine or appliance whose main job is serving storage over a network.

Operational detail. Treat its identity, configuration, updates, snapshots, network dependency, backup, and recovery as a separate control plane.

Why it matters / common trap. NAS does not mean backup; it can share administrator, ransomware, power, theft, and fire risks.

Used in: Storage + identity, Field kit

NFS root squashing and no_root_squash#

TL;DR: Root squashing maps remote UID 0 to an unprivileged anonymous identity instead of server root.

Operational detail. Preserve it, use registered service UID/GID values, export only named datasets, and test remote-root denial; use Kerberos when client trust is insufficient.

Why it matters / common trap. Disabling it or using chmod 777 turns a container permission symptom into broad storage authority.

Used in: Before the agent, Linux foundation, Storage + identity, Services

NFS vs SMB and Samba#

TL;DR: NFS usually serves trusted Unix hosts/apps; SMB serves people using Windows and macOS, commonly through Samba.

Operational detail. NFS exposes numeric ownership; SMB supplies per-user network authentication. Use separate datasets absent a tested cross-protocol identity/ACL/locking design.

Why it matters / common trap. NFS is not “advanced SMB,” and a successful mount does not prove compatible identity or locking.

Used in: Start here, Linux foundation, Storage + identity, Services

NVMe, SATA, SAS, HDD, SSD, and USB storage#

TL;DR: HDD and SSD describe media; NVMe, SATA, SAS, and USB describe common device or transport paths.

Operational detail. Record model, firmware, health, geometry, controller, bridge, port, cable, power, and stable ID; prefer direct paths for primary pools.

Why it matters / common trap. A good disk behind an unreliable bridge, cable, controller, or power supply is still unreliable storage.

Used in: Linux foundation, Network + power, Storage + identity, Field kit

Object storage, bucket, object lock, and immutability#

TL;DR: Object storage keeps named blobs in buckets, while object lock can prevent even an administrator from deleting protected backup versions before a deadline.

Operational detail. Object stores expose an API rather than a normal mounted filesystem. Restic and similar tools can write encrypted repositories to S3-compatible buckets. Versioning preserves superseded objects; retention-mode object lock or write-once-read-many controls can make selected versions immutable, subject to provider and account configuration.

Why it matters / common trap. An off-site bucket is not ransomware-resistant if the same stolen credential can erase it. Versioning without lifecycle limits can also grow forever, while “immutable” marketing does not prove that the deletion path, account owner, and retention settings were tested.

Used in: Storage + identity, Operations

Off-host vs off-site backup#

TL;DR: Off-host means the copy is on another machine; off-site means the copy is outside the same physical disaster zone.

Operational detail. A backup on a second server protects against one host or pool failure. A rotated disk elsewhere or a remote object store adds protection from theft, fire, flood, and site-wide power events. A sound plan normally has both, with at least one copy isolated from routine administrator credentials.

Why it matters / common trap. Two machines in the same rack, on the same UPS, or administered by the same compromised account can fail together. “Cloud synced” data may replicate deletion immediately and is not automatically a retained backup.

Used in: Start here, Storage + identity, Operations

OpenZFS and ZFS#

TL;DR: OpenZFS is the current open-source implementation of ZFS, a storage system that combines volume management, a checksumming filesystem, snapshots, and replication.

Operational detail. ZFS organizes disks into vdevs, vdevs into pools, and files into datasets or block volumes. It checksums data, repairs corruption when a redundant good copy exists, supports snapshots and send/receive, and exposes properties such as compression, quotas, mountpoints, and record size.

Why it matters / common trap. ZFS can detect damage but cannot reconstruct data without redundancy or a backup. Pool topology is difficult to change casually, snapshots are not independent backups, and using unfamiliar tuning values because a blog recommends them often makes the system worse.

Used in: Linux foundation, Storage + identity, Operations

Orchestration#

TL;DR: Orchestration coordinates deployment, placement, restart, networking, and lifecycle for many workloads according to declared state.

Operational detail. Compose orchestrates containers on one host; Kubernetes adds a distributed scheduler, controllers, service discovery, policy, and cluster APIs. Orchestration is useful after repeated multi-service operations become a demonstrated burden and the household accepts the extra control-plane dependency.

Why it matters / common trap. Orchestration automates failure handling but does not create redundant storage, correct application design, or recoverable data. Adopting it before the simpler system is observable and backed up can hide failures beneath more layers.

Used in: Start here, Services, Operations

Overlay network, virtual private network (VPN), and WireGuard#

TL;DR: An overlay VPN builds an encrypted private network over existing networks; WireGuard is a common encrypted tunnel protocol beneath products such as Tailscale.

Operational detail. Peers receive overlay addresses and exchange encrypted packets without requiring every application to understand the underlay. Identity, routing, DNS, exit nodes, subnet routers, and access policy are separate controls. Direct peer paths are preferable, but relays can preserve connectivity through difficult NAT.

Why it matters / common trap. Being connected to a VPN does not mean every peer should reach every service. An overlay does not replace host firewalls, service authentication, DNS planning, or an independent recovery path when the identity or coordination service fails.

Used in: Before the agent, Control host, Network + power, Services, Field kit

Package and dependency update strategy#

TL;DR: Update deliberately in bounded batches, preserve a rollback path, and verify household functions instead of either freezing forever or upgrading everything blindly.

Operational detail. Distinguish operating-system security fixes, normal package updates, firmware, container images, language dependencies, and major releases. Record current versions, snapshots or backups, release notes, a maintenance window, and post-change checks. Homelabs rarely justify a full staging environment, so use canaries where practical and make the production change small and reversible.

Why it matters / common trap. Unrestricted apt upgrade or brew upgrade can combine unrelated changes, but banning updates creates accumulating security and compatibility debt. Auto-updating mutable image tags removes both review and an easy explanation of what changed.

Used in: Before the agent, Linux foundation, Services, Operations

Parity and RAIDZ#

TL;DR: Parity stores enough mathematical information to reconstruct missing data after a limited number of disk failures; RAIDZ is ZFS's parity-vdev family.

Operational detail. RAIDZ1, RAIDZ2, and RAIDZ3 tolerate one, two, or three failed members in a vdev, respectively. Usable capacity and rebuild exposure depend on width, disk size, workload, and failure tolerance. A pool fails if any required top-level vdev becomes unavailable.

Why it matters / common trap. Parity is redundancy, not backup, and rebuilds stress all surviving disks. Wider vdevs may improve capacity efficiency but increase the amount of data sharing one failure domain and can reduce small random-write performance.

Used in: Storage + identity, Operations

Persistent state, bulk data, and scratch space#

TL;DR: Persistent state must survive rebuilds, bulk data is large user or media content, and scratch space is disposable working data.

Operational detail. Classify every writable path before deployment. Back up configuration, databases, keys, and other irreplaceable state; give bulk media an explicit protection decision; place caches, transcodes, temporary downloads, and build output on capacity that may be safely erased.

Why it matters / common trap. Treating a database directory as disposable destroys the service, while backing up terabytes of regenerable cache wastes time and retention. A container volume is persistent relative to a container, not automatically backed up or portable.

Used in: Storage + identity, Services, Operations

Pi-hole and DNS sinkhole#

TL;DR: Pi-hole is a network DNS resolver that blocks selected names before clients connect to advertising, tracking, or unwanted endpoints.

Operational detail. Clients must actually use the resolver, directly or through a forwarding household DNS design. Keep upstream resolution, local-zone ownership, allowlists, blocklists, query retention, redundancy, and recovery behavior explicit. Validate both blocked and required household services.

Why it matters / common trap. DNS filtering is not a firewall or malware guarantee. Blocking can break login, telemetry-dependent devices, or content delivery, and one DNS appliance can become a household-wide availability dependency.

Used in: Network + power, Services, Operations

Plex direct play, direct stream, transcode, and hardware acceleration#

TL;DR: Direct play sends media unchanged, direct stream repackages compatible streams, and transcoding converts audio or video, often using a GPU or media engine.

Operational detail. Client codec, container, subtitle, bandwidth, resolution, and tone-mapping support determine the path. Hardware acceleration requires compatible devices, drivers, permissions, container device exposure, and product capability; validate with representative clients and media.

Why it matters / common trap. A powerful server may still transcode because one client or subtitle format is incompatible. Passing an entire GPU or privileged device stack into a container expands authority, and hardware acceleration does not remove network or storage bottlenecks.

Used in: Services, Operations

Portable Operating System Interface (POSIX)#

TL;DR: POSIX is a family of standards describing common Unix-like operating-system behavior, including files, permissions, processes, users, and shell interfaces.

Operational detail. In storage and identity discussions, “POSIX identity” usually means numeric user and group IDs plus owner/group/mode permission bits. Linux, macOS, NFS, and Samba overlap substantially but also have extensions and translation layers.

Why it matters / common trap. POSIX-compatible does not mean behavior is identical everywhere. Names are human labels; filesystems and NFS often enforce numeric IDs, so mismatched UID or GID assignments can silently give the wrong principal access.

Used in: Linux foundation, Storage + identity, Services

Power distribution unit (PDU)#

TL;DR: A PDU distributes electrical power to rack equipment; a metered or switched PDU can measure or remotely control individual outlets.

Operational detail. Check input plug, circuit rating, outlet type and count, continuous-load limits, surge behavior, metering accuracy, and whether switching remains available without the cloud. Label each outlet and map it to the device, power supply, UPS, and shutdown order.

Why it matters / common trap. A switched outlet is a destructive actuator, not a harmless convenience. Both redundant power supplies plugged into one PDU or one UPS still share a single failure domain.

Used in: Network + power, Operations, Field kit

Prompt injection and agent hijacking#

TL;DR: Prompt injection is untrusted content crafted to make an agent follow someone else's instructions or misuse its tools.

Operational detail. Treat web pages, logs, documents, issue text, filenames, terminal output, and retrieved memories as data, not authority. Limit tools and credentials, separate read from write identities, require confirmation for destructive or external actions, and verify proposed commands against trusted intent before execution.

Why it matters / common trap. A private server is not automatically trusted: compromised applications and copied text can contain hostile instructions. Telling a model to “ignore prompt injection” is not a security boundary; capability restriction and human-visible approval are.

Used in: Before the agent, Control host, Operations

Quorum#

TL;DR: Quorum is the minimum agreeing majority a distributed system needs to make authoritative progress without splitting into conflicting groups.

Operational detail. For a typical three-member consensus group, two healthy communicating members form quorum; losing two stops writes or control-plane progress. Quorum calculations concern voting members and failure domains, not simply the number of machines running applications.

Why it matters / common trap. Two members do not provide useful majority failure tolerance: either losing one halts the system or allowing one to proceed risks split brain. A quorum-capable control plane does not make its external storage or network dependencies redundant.

Used in: Services, Operations

Quota#

TL;DR: A quota is a limit on a consumable resource such as storage, requests, tokens, bandwidth, or model usage.

Operational detail. Record the unit, scope, reset schedule, warning thresholds, enforcement behavior, and who can raise the limit. For agent work, estimate task size as tiny through XL and watch the provider UI's observable drain; reserve capable models and high thinking effort for work that needs them.

Why it matters / common trap. “Unlimited” subscription plans still commonly have rolling or workload-specific limits. Starting a long recovery or migration with little remaining quota can strand the session at the point where context and judgment matter most.

Used in: Start here, Before the agent, Control host, Operations

Rack unit (U), rack depth, and equipment envelope#

TL;DR: A rack unit measures equipment height, while the full physical envelope also includes depth, rail range, cable bend, airflow, weight, and service clearance.

Operational detail. One rack unit is 1.75 inches or 44.45 millimeters. Measure usable post-to-post depth, door clearance, protruding handles, power plugs, rear cable radius, rail compatibility, airflow direction, total weight, and the space required to remove disks or lids.

Why it matters / common trap. “2U rackmount” says almost nothing about whether a chassis fits a shallow cabinet. Equipment may physically enter yet block doors, starve cooling, overload rails, or become impossible to service in place.

Used in: Network + power, Field kit

RAID levels: stripe, mirror, RAID5/6/10, and RAIDZ#

TL;DR: RAID layouts trade capacity, performance, and tolerance of disk failures, but none replaces a backup.

Operational detail. A stripe combines capacity with no redundancy; a mirror keeps duplicate copies; RAID10 stripes across mirrored pairs; RAID5 and RAID6 use single and dual parity; ZFS RAIDZ1/2/3 provide analogous integrated parity vdevs. Failure tolerance depends on which members fail, not only how many.

Why it matters / common trap. RAID protects availability after some disk failures, not deletion, corruption, theft, fire, or administrator error. Advertised raw capacity excludes redundancy, formatting, metadata, free-space headroom, and sometimes decimal-versus-binary units.

Used in: Storage + identity, Operations

Read-only access vs unprivileged access#

TL;DR: Read-only limits mutation through one interface; unprivileged limits authority, and neither guarantee automatically implies the other.

Operational detail. Evaluate every accessible data source, metadata path, control socket, credential, executable, and side channel. A read-only mount may expose private data or secrets; an unprivileged process may still write its own files, make network requests, consume resources, or invoke a privileged broker.

Why it matters / common trap. “It cannot write this directory” is not a complete sandbox. Read access to SSH keys, cookies, tokens, backup repositories, or configuration can enable later writes elsewhere under a stolen identity.

Used in: Before the agent, Control host, Linux foundation, Operations

Recovery point objective (RPO) and recovery time objective (RTO)#

TL;DR: RPO is how much recent data loss is acceptable; RTO is how long the service may remain unavailable.

Operational detail. Express both per household capability, not as one global slogan. Snapshot and backup frequency constrain achievable RPO; restore bandwidth, replacement hardware, credentials, runbooks, and dependencies constrain RTO. Measure them in restore drills.

Why it matters / common trap. A nightly backup suggests at best a roughly one-day RPO only if it completed and is restorable. Keeping many copies does not make restoration fast, and a fast failover can preserve already-corrupted data.

Used in: Start here, Storage + identity, Services, Operations

Redundancy vs replica#

TL;DR: Redundancy keeps a function available after a component fails; a replica is another copy, which helps only when it is independent and usable.

Operational detail. Mirrors, parity disks, clustered controllers, secondary DNS servers, and replicated databases address different failure modes. Map shared power, network, credentials, software, site, and human dependencies before claiming redundancy.

Why it matters / common trap. Two copies under one failure domain can disappear together, and synchronous replication faithfully copies deletion or corruption. A replica becomes a recovery mechanism only after promotion, consistency, and client reconnection have been tested.

Used in: Start here, Network + power, Storage + identity, Services, Operations

Restic, backup repository, snapshot, and restore#

TL;DR: Restic encrypts and deduplicates files into a backup repository, where each backup snapshot is an indexed view that can later be restored.

Operational detail. Protect the repository password separately from the repository, configure exclusions deliberately, monitor backup completion, run integrity checks, and perform restores into a clean destination. Repository backends may be local, remote over SFTP, or object storage.

Why it matters / common trap. Restic's “snapshot” is a backup catalog object, not the same as a ZFS snapshot. Successful upload logs do not prove that credentials, metadata, permissions, paths, and application-consistent data can be restored.

Used in: Storage + identity, Operations, Field kit

Role-based access control (RBAC)#

TL;DR: RBAC grants permissions to roles and assigns people or service identities to those roles instead of managing every permission individually.

Operational detail. Define verbs, resources, namespaces or scopes, assignment owners, review intervals, and a break-glass path. Use separate roles for reading, operating, changing policy, and destructive administration, then test what each identity can actually do.

Why it matters / common trap. Broad wildcard roles and accumulated group membership quietly recreate administrator access. A role name such as “viewer” is not evidence of safety if it can read secrets, logs containing credentials, or objects that enable privilege escalation.

Used in: Before the agent, Control host, Services, Operations

Rollback, revert, and fix forward#

TL;DR: Rollback restores the prior working state, revert applies a new inverse change, and fix forward introduces another change intended to repair the current state.

Operational detail. Prefer a tested rollback when the failure is understood and prior state can be restored safely. Before a change, capture versions, data compatibility, configuration, backups, and the exact abort trigger. Ask the operator before initiating rollback because stateful or partially completed migrations may make reversal riskier than a targeted repair.

Why it matters / common trap. “Roll back, do not fix forward” limits improvisation during incidents, but blind backtracking can compound corruption or replay a known bug. A snapshot is not a rollback plan unless the restore sequence and post-restore validation are known.

Used in: Before the agent, Services, Operations, Field kit

Root, sudo, privilege, and privilege escalation#

TL;DR: Root is the all-powerful Unix account; sudo grants approved commands elevated privilege, and privilege escalation is any path from lesser to greater authority.

Operational detail. Prefer ordinary accounts, narrow groups, explicit sudoers rules, short-lived elevation, and logged changes. Evaluate the full reachable action: permission to edit a root-run script, unit file, package source, container socket, or executable directory can be equivalent to root.

Why it matters / common trap. A command allowlist is not safe if arguments permit arbitrary files, shells, plugins, or output destinations. Passwordless sudo is not automatically wrong for automation, but it must be constrained to auditable operations with protected inputs.

Used in: Before the agent, Control host, Linux foundation, Operations, Field kit

Route, subnet router, and jump host#

TL;DR: A route chooses the next path for network traffic, a subnet router advertises reachability to another network, and a jump host is an intermediate login point for administration.

Operational detail. Document destination prefixes, next hops, advertisement owners, approval policy, firewall direction, and return paths. A Tailscale subnet router lets overlay clients reach devices that do not run Tailscale; a jump host terminates one administrative session and originates another.

Why it matters / common trap. Reachability is not authorization. Advertising a broad LAN route can expose printers, cameras, management interfaces, and recovery devices; a jump host holding powerful keys becomes a high-value dependency requiring hardening and logs.

Used in: Control host, Network + power, Operations, Field kit

Runbook, decision record, change journal, and session transcript#

TL;DR: A runbook says how to operate a system, while decision records, change journals, and transcripts preserve why it exists and what actually happened.

Operational detail. Retain complete bring-up and future sysadmin transcripts in a searchable, access-controlled archive with timestamps, host and user context, command output, approvals, and secret redaction. Keep durable runbooks and architecture decisions in Git; link issues or enhancement records when available, while treating raw transcripts as evidence rather than polished instructions.

Why it matters / common trap. Runbooks drift and omit the reasoning needed during an unfamiliar failure. Transcripts can recover original intent, but they may contain stale commands, credentials, personal data, or failed experiments and must never silently outrank current validated documentation.

Used in: Start here, Before the agent, Control host, Operations, Field kit

Samba and Server Message Block (SMB)#

TL;DR: SMB is a network file-sharing protocol used heavily by Windows and macOS; Samba is the common open-source server and identity implementation on Linux.

Operational detail. Define share paths, filesystem ownership, Samba users and groups, protocol versions, discovery, name resolution, ACL translation, snapshots, and client compatibility. Samba can be a simple standalone file server or part of a much larger directory environment.

Why it matters / common trap. Filesystem permissions and Samba permissions both apply, so making one permissive does not necessarily fix access. Guest access, legacy SMB versions, confused UID/GID mappings, and separately managed Samba passwords create security and recovery surprises.

Used in: Storage + identity, Services, Operations

Sector size, 512e, 4Kn, and alignment#

TL;DR: Sector size is the drive's basic addressable block; 512e emulates 512-byte sectors over 4 KiB media, while 4Kn exposes 4 KiB sectors directly.

Operational detail. Check logical and physical sector sizes, partition alignment, controller support, boot compatibility, and storage-stack block assumptions before mixing devices. Modern partitioning tools usually align correctly, but disk cloning and older hardware can preserve poor boundaries.

Why it matters / common trap. Misalignment can turn one logical write into multiple physical operations and hurt performance or endurance. Drives with the same advertised capacity can have different exact sector counts, preventing a nominally equal replacement from fitting.

Used in: Linux foundation, Storage + identity, Field kit

Self-Monitoring, Analysis and Reporting Technology (SMART)#

TL;DR: SMART exposes drive health counters and self-tests that can warn about some failures, but a passing result is not a guarantee.

Operational detail. Record device identity and transport, monitor critical attributes and error logs, schedule appropriate short and long tests, and alert on changes rather than one vendor-normalized score. Combine SMART with ZFS or filesystem errors, controller logs, temperature, and application symptoms.

Why it matters / common trap. Drives can fail suddenly with no SMART warning, and USB bridges or RAID controllers may hide data. Reallocated sectors, media errors, interface CRC errors, and NVMe wear indicators mean different things and require context before replacement.

Used in: Linux foundation, Storage + identity, Operations, Field kit

Semantic diff#

TL;DR: A semantic diff explains the operational meaning of a change, not merely which text lines differ.

Operational detail. Summarize changed identities, listeners, routes, permissions, storage paths, dependencies, versions, data migrations, restart behavior, rollback limits, and validation evidence. Keep the ordinary textual diff as the exact record and add the semantic explanation for human review.

Why it matters / common trap. Generated YAML or lockfiles can change hundreds of lines while making one meaningful change, and a one-line permission or image-tag edit can be high risk. An LLM summary is an aid, not a substitute for inspecting security-sensitive values and actual tool output.

Used in: Before the agent, Control host, Services, Operations

Service identity and service account#

TL;DR: A service identity is the non-human principal a program uses to access files, APIs, networks, or other services.

Operational detail. Give each service a stable owner, narrow UID/GID or platform account, minimum filesystem and API permissions, an explicit credential source, rotation and revocation procedure, and auditable use. Separate build, deployment, runtime, backup, and monitoring identities where their authority differs.

Why it matters / common trap. Running every daemon as one household administrator turns one compromise into access to everything and makes attribution impossible. Renaming an account or hiding its password does not reduce privilege; map what the identity can actually reach.

Used in: Before the agent, Linux foundation, Storage + identity, Services, Operations

Service tiers and criticality#

TL;DR: Service tiers group capabilities by how urgently they must be restored and how much complexity is justified to protect them.

Operational detail. Classify household functions such as network access, DNS, identity, storage, media, observability, and experiments using outage tolerance, data value, dependencies, operator availability, and recovery effort. Attach realistic RPO, RTO, backup, monitoring, and maintenance expectations to each tier.

Why it matters / common trap. Calling everything critical makes priorities meaningless and over-engineers hobbies; calling infrastructure “just a homelab” can leave household members without basic connectivity. Tier dependencies matter: a low-profile DNS or identity service may gate many visible applications.

Used in: Start here, Before the agent, Services, Operations

Snapshot#

TL;DR: A snapshot is a point-in-time view of data that is usually fast and space-efficient but commonly shares the original storage's failure domain.

Operational detail. Filesystem, volume, virtual-machine, and backup tools use the word differently. ZFS snapshots initially reference existing blocks and consume space as data diverges; they can seed replication and enable quick file recovery. Coordinate applications when crash consistency is insufficient.

Why it matters / common trap. A local snapshot is not an off-host backup and disappears with the pool. Snapshot accumulation can consume free space, and rolling an entire dataset back may discard newer good changes alongside the mistake being repaired.

Used in: Linux foundation, Storage + identity, Operations

Split DNS and MagicDNS#

TL;DR: Split DNS sends selected name queries to different resolvers; MagicDNS supplies convenient Tailscale names for devices in a tailnet.

Operational detail. Assign one authoritative owner per zone or suffix, document resolver order, search domains, fallback behavior, and what happens when the overlay is unavailable. Test from LAN, VPN, guest, and recovery contexts using names as real applications use them.

Why it matters / common trap. Two resolvers answering the same suffix differently create intermittent failures that resemble application bugs. MagicDNS names solve overlay discovery but do not automatically publish household LAN records or replace public DNS and certificate planning.

Used in: Control host, Network + power, Services, Operations

SSH key, authorized key, host key, known hosts, and restrictions#

TL;DR: A client key authenticates a user, a host key authenticates the server, and restrictions can confine what a particular authorized key is allowed to do.

Operational detail. Protect private keys with appropriate encryption and file permissions, verify server host-key fingerprints, retain known-host history, and rotate or revoke lost credentials. In authorized_keys, use forced commands, source constraints, disabled forwarding, and separate keys when automation needs only one operation.

Why it matters / common trap. Accepting a changed host key without investigating defeats server authentication. A key described as “read-only” is not read-only unless the remote account, command, paths, arguments, forwarding, and secondary tools all enforce that boundary.

Used in: Before the agent, Control host, Linux foundation, Operations, Field kit

Stateful vs stateless service#

TL;DR: A stateless service can be recreated from configuration and external inputs; a stateful service owns data or identity that must be preserved and coordinated.

Operational detail. Identify databases, media indexes, queues, generated keys, session stores, uploads, and local configuration before moving or scaling a workload. Stateless replicas are relatively easy to replace; stateful replicas need consistency, backup, ordering, and promotion rules.

Why it matters / common trap. A container image may be reproducible while its mounted volume is irreplaceable. Declaring a service stateless because the main data lives elsewhere ignores credentials, local caches that are costly to rebuild, and dependency availability.

Used in: Services, Operations

Subordinate UID/GID ranges (subuid, subgid) and user namespaces#

TL;DR: User namespaces map identities inside a container to different, usually unprivileged, numeric IDs on the host using subordinate UID and GID ranges.

Operational detail. Allocate non-overlapping ranges in /etc/subuid and /etc/subgid, preserve them across rebuilds, and confirm ownership for bind mounts, network filesystems, backups, and migrated hosts. Rootless container engines use these mappings to reduce host privilege.

Why it matters / common trap. Container root mapped to an ordinary host ID is safer than host root but is not a complete sandbox. Changing the mapping can make persistent files appear owned by unrelated IDs and can break restores or cross-host moves.

Used in: Linux foundation, Storage + identity, Services

Tailscale, tailnet, node, tag, ACL/grant, exit node, and subnet router#

TL;DR: Tailscale builds an identity-aware WireGuard overlay called a tailnet; tags, policy, exit nodes, and subnet routers control device roles and traffic paths.

Operational detail. A node joins the tailnet under a user or tag. Access controls or grants decide permitted flows; a subnet router advertises another network; an exit node carries general Internet traffic; coordination and DERP relays help peers connect. Record key expiry, ownership, DNS, routes, and recovery access.

Why it matters / common trap. Enrollment proves membership, not universal authorization. Auto-approving tags or routes, using reusable keys broadly, or depending on one subnet router can turn a convenience layer into a large blast radius or single point of failure.

Used in: Before the agent, Control host, Network + power, Services, Field kit

TCP, UDP, and port mapping#

TL;DR: TCP provides ordered connections, UDP sends independent datagrams, and port mapping translates an address-and-port tuple across a boundary such as NAT or a container host.

Operational detail. Document protocol, listening address, internal and external port, source network, firewall rule, encryption, and application owner. Container publishing, router forwarding, and Kubernetes Services are different mapping layers and may coexist.

Why it matters / common trap. TCP port 53 and UDP port 53 are distinct rules, and binding 0.0.0.0 exposes every IPv4 interface rather than only localhost. A published port can bypass the intended reverse proxy or broaden access beyond the VPN.

Used in: Control host, Linux foundation, Network + power, Services, Operations

Topology and dependency map#

TL;DR: Topology describes how components connect; a dependency map shows what each capability needs in order to function or recover.

Operational detail. Include physical hosts, power, networks, addresses, identity, DNS, storage, certificates, control planes, services, monitoring, backups, and human access paths. Mark direction, ownership, redundancy, and failure domains, then keep the map with the versioned operating record.

Why it matters / common trap. A rack diagram alone omits logical dependencies, while an application diagram may ignore power and recovery access. Hidden cycles—such as DNS needing storage that is mounted by DNS name—turn ordinary restarts into outages.

Used in: Start here, Before the agent, Network + power, Services, Operations, Field kit

Transactional change#

TL;DR: A transactional change either completes as a coherent unit or leaves the system in a known prior state instead of an ambiguous halfway condition.

Operational detail. Use validated scripts, configuration staging, atomic file replacement, database transactions, declarative tools, checkpoints, and explicit abort handling. Batch unavoidable user setup into one small reviewable script with preflight checks, idempotent operations, logging, and a final validation summary.

Why it matters / common trap. Feeding commands one at a time creates undocumented partial state and makes reruns uncertain. A long shell script is not automatically transactional: external APIs, package installs, firmware, and data migrations may need compensating actions and human-approved rollback.

Used in: Before the agent, Control host, Linux foundation, Operations, Field kit

Uninterruptible power supply (UPS), watts, volt-amperes (VA), and runtime#

TL;DR: A UPS supplies temporary battery power; watts measure real load, VA reflects apparent load, and runtime estimates how long the battery can sustain that load.

Operational detail. Size for measured peak and normal load, UPS watt and VA limits, desired shutdown time, battery age, surge behavior, and expansion. Connect monitoring, test power-loss and low-battery signaling, coordinate shutdown order, and confirm automatic recovery after utility power stabilizes.

Why it matters / common trap. The VA headline alone does not guarantee sufficient watts or runtime. A UPS is not a generator, batteries degrade, and protecting servers while leaving the switch, router, DNS, or storage unpowered may not preserve useful service.

Used in: Network + power, Operations, Field kit

Validator and native-consumer test#

TL;DR: A validator checks formal structure; a native-consumer test proves the real program can load and use the artifact as intended.

Operational detail. Run syntax and schema checks first, then invoke the actual service, CLI, parser, restore tool, browser, mount client, or deployment engine on a safe fixture. Capture versions, exit status, output, and the specific behavior verified.

Why it matters / common trap. Valid YAML can express an invalid service configuration, and a successful dry run may omit permissions, networking, credentials, or runtime data. Text inspection by a model is not evidence that the consuming system accepts the artifact.

Used in: Before the agent, Control host, Services, Operations, Field kit

Version pin and release channel#

TL;DR: A version pin selects one known artifact version, while a release channel follows a moving stream such as stable, beta, or nightly.

Operational detail. Pin container images by immutable digest or exact version where reproducibility matters, record the human-readable release, and update through a deliberate review cadence. Channels may be reasonable for low-risk clients if rollback and compatibility behavior are known.

Why it matters / common trap. Tags such as latest and even some numbered tags can move, making the same deployment file produce different systems. Permanent pins avoid surprise but accumulate security debt unless an owner and update mechanism exist.

Used in: Before the agent, Linux foundation, Services, Operations

Virtual LAN (VLAN), network segmentation, and SSID#

TL;DR: A VLAN separates one physical Ethernet infrastructure into logical broadcast domains; an SSID is a Wi-Fi network name that may map clients into one of them.

Operational detail. Define VLAN IDs, subnets, gateways, DHCP, DNS, tagged trunks, untagged access ports, wireless mappings, firewall policy, and a management recovery path. Test permitted and denied flows from actual wired and wireless clients.

Why it matters / common trap. A VLAN provides separation only when switches, access points, routers, and firewall rules agree. A different SSID name alone is not isolation, and mis-tagging the management path can lock out the operator.

Used in: Network + power, Services, Operations, Field kit

Wildcard certificate#

TL;DR: A wildcard TLS certificate covers many one-level hostnames under a domain, such as *.example.net, using one certificate and private key.

Operational detail. Automate issuance and renewal, usually with a DNS challenge, limit who can modify DNS, secure key distribution, and inventory every endpoint sharing the key. Wildcards do not normally cover the bare domain or deeper names such as a.b.example.net.

Why it matters / common trap. One convenient wildcard private key can impersonate many services, so copying it to every container expands the blast radius. Encryption does not provide service authorization, and an expired or failed renewal can break all covered names at once.

Used in: Control host, Network + power, Services, Operations

Windows security identifier (SID)#

TL;DR: A SID is Windows's stable machine-readable identifier for a user, group, computer, or other security principal.

Operational detail. Windows ACLs store SIDs rather than display names. Standalone Samba generates and maps local SIDs; directory domains allocate them centrally. Preserve domain or server identity and mapping data when migrating shares so existing ACLs continue to refer to the intended principals.

Why it matters / common trap. Recreating a user with the same visible name usually creates a different SID. Copying files without their ACL and identity context can leave unknown SID entries or accidentally grant access through a new mapping.

Used in: Storage + identity, Operations

YAML, JSON, and CSV#

TL;DR: YAML and JSON represent structured data; CSV represents rows and columns, and each format has parsing rules that visual inspection can easily misread.

Operational detail. Use a real parser and the native consumer, preserve schemas and encoding, quote ambiguous values, and avoid hand-building documents with string concatenation. YAML supports comments and rich syntax, JSON is stricter, and CSV dialects differ in delimiter, quoting, headers, and newline handling.

Why it matters / common trap. Indentation, implicit YAML types, duplicate keys, escaping, spreadsheet formula interpretation, and multiline CSV fields can change meaning without looking obviously wrong. Syntactic validity does not prove semantic correctness.

Used in: Before the agent, Control host, Services, Operations, Field kit

ZFS L2ARC, SLOG, and special vdev#

TL;DR: These are optional ZFS roles for secondary read cache, synchronous-write intent logging, and selected metadata or small blocks.

Operational detail. Add them only after workload measurement and recovery analysis. A SLOG is not a general write cache, and a lost special vdev can lose the pool.

Why it matters / common trap. Speculative “performance” devices add power, replacement, and recovery obligations without guaranteed benefit.

Used in: Storage + identity

ZFS resilver vs scrub#

TL;DR: A resilver reconstructs data onto a replacement or rejoined ZFS device; a scrub reads and verifies allocated data across the pool.

Operational detail. Monitor pool status and errors during either operation. A scrub detects checksum damage and repairs it when a valid redundant copy exists. A resilver restores the intended redundancy after device replacement or interruption; duration depends on allocated data, layout, load, and hardware.

Why it matters / common trap. A completed scrub is not a backup and cannot repair data with no good copy. Replacing another device while a vdev is degraded can exceed fault tolerance, so identify the exact member and current topology before acting.

Used in: Storage + identity, Operations

ZFS: pool, vdev, dataset, zvol, ARC, snapshot, scrub, resilver, and send/receive#

TL;DR: ZFS combines disks into pools through vdevs, exposes datasets or block volumes, caches reads in ARC, and supplies integrated integrity, snapshot, repair, and replication tools.

Operational detail. A pool's failure tolerance is determined by each top-level vdev. Datasets carry independent properties and filesystems; zvols expose block devices; ARC uses memory as cache; snapshots preserve point-in-time references; scrubs verify data; resilvers reconstruct redundancy; send/receive transfers snapshot history.

Why it matters / common trap. These nouns describe different layers, so “the ZFS disk” is too ambiguous for safe changes. Adding one nonredundant top-level vdev can reduce the reliability of an otherwise redundant pool, and neither checksums nor snapshots replace an independent tested backup.

Used in: Linux foundation, Storage + identity, Operations, Field kit