From 70762307edc7fbe02f22d68e5c2540eefe019cb7 Mon Sep 17 00:00:00 2001 From: "John A. Hoeven" Date: Sun, 26 Jul 2026 00:39:40 +0200 Subject: [PATCH] Update README.md and create suse-user-guide-example.md --- README.md | 154 ++++++++++ suse-user-guide-example.md | 610 +++++++++++++++++++++++++++++++++++++ 2 files changed, 764 insertions(+) create mode 100644 suse-user-guide-example.md diff --git a/README.md b/README.md index b94c385..281249d 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,156 @@ # suse-autoyast-workflows +**Practical, honestly-labeled AutoYaST deployment workflows for openSUSE Leap, SLES, and Tumbleweed.** + +REFER TO ALL RELEVANT OFFICIAL SOFTWARE MANUALS + +Public domain. Built in Brianza. Designed for anyone deploying SUSE with AutoYaST. + +--- + +## What This Is + +A set of process workflows for partially unattended openSUSE +installation via AutoYaST — covering client device profiling, VM-based +pre-deployment testing, and the bare-metal deployment that follows it. +Built from real, documented deployment experience, not theoretical best +practice. + +[WARNING] This repository is a guiding template, not a source of truth. +SUSE's own documentation — [documentation.suse.com](https://documentation.suse.com) +— is authoritative for whatever SLES/Leap/Tumbleweed release is actually +being deployed. Find and read the AutoYaST Guide for that specific +release; don't assume an example seen elsewhere still applies. AutoYaST +syntax, package availability, default groups, and repo layout all shift +between releases; a detail confirmed here on one version is not a +standing guarantee for another. Adapt this repo's guidance to the +current release's own manual before relying on it, every time, not just +on first use. + +This isn't a theoretical caution. The project that generalized into this +repo burned real time chasing exactly this: assuming a detail true for +one openSUSE release still held for the target being deployed, when it +didn't. Thirteen install passes traced back, in part, to not re-checking +the current release's own guide closely enough at each step. Don't +repeat that mistake by trusting this repo the way it should have +trusted the current manual instead. + +[WARNING] The same applies to the virtualization tooling this repo's +workflows depend on. `libvirt`, `virt-install`, `virt-viewer`, and QEMU +each version independently of the SUSE release being deployed and of +each other — flag syntax, default behavior, and firmware/TPM support +change between releases. The +[libvirt documentation](https://libvirt.org/docs.html) and each tool's +own man page are authoritative, not this repo. A command confirmed +working here on one host's package versions is not a standing guarantee +on a different host, a different tinkerpad13 update cycle, or a +different distro's packaging of the same tools. + +AutoYaST automates the configuration decisions — package selection, +partitioning, privilege escalation setup — but this is not a walk-away +install. Physical presence (or its VM equivalent, a watched console) +matters throughout: AutoYaST's own documentation notes that some +interactive dialogs bypass suppression entirely, and this repo's +workflows are built around staying attended for exactly that reason. +"Partially unattended" is the honest description — the profile does the +deciding, a person does the watching. + +This repository is **in progress**. Several referenced sub-workflows +don't exist yet (see Status below) — what's here is published as an +honest work in progress, not withheld until complete. Consider this the +technical process layer: version selection, media policy, VM tooling, +test-cycle mechanics. It does not cover AutoYaST profile authoring +itself, which lives in its own not-yet-written workflow, or any +business-process content around client engagement — this repo is +deployment mechanics only. + +--- + +## Where This Comes From + +This workflow set was generalized out of a real deployment project — +migrating a ThinkPad from Alpine to openSUSE Tumbleweed via AutoYaST, +across thirteen documented install passes. That project surfaced the +core technical problem this repo's guidance is built around: openSUSE's +`Defaults targetpw` sudo behavior, which breaks the standard RHEL-style +privilege escalation pattern unless addressed explicitly. + +That original project's full build log — warts, false starts, and all — +stays a separate, private record. This repository is downstream of it, +not a sanitized copy of it: everything here is written fresh, as +general-purpose process, not as an account of what happened on any one +specific machine. + +--- + +## Scope + +**Covered:** openSUSE Leap and SLES, as the primary target — point +releases where a DVD image stays representative of what actually +installs, making genuine pre-deploy VM testing possible. Tumbleweed is +not excluded, but its rolling-release nature changes the guarantees the +test cycle can offer; see the deploy workflow's own notes on this. + +**Not covered:** AutoYaST profile authoring itself (package selection, +partitioning, post-install script content) — referenced from this +repo's workflows but documented separately. Client engagement mechanics +and pricing (how a handoff is billed, structured, or negotiated) are +deliberately kept out of this repository entirely; that's specific to +whoever's deploying and isn't this repo's business. + +**Covered, at the principle level:** client empowerment as a closing +step. This repo's deploy workflow recommends ending every deployment +with a handoff — a portable copy of the deployed VM in whatever +deliverable form suits the situation, plus a basic usage guide the +deployer writes for that specific client. What form the guide takes, +how the copy is delivered, and how any of it is billed are left +entirely to the deployer; the recommendation is that a handoff happens +and empowers the client, not a specification of how. + +Two example handoff documents are included as reference: a generic +**user's guide** (`suse-user-guide-example.md`) and a planned +**administrator's guide**, showing the kind of thing this recommendation +actually produces. Neither contains, nor should ever contain, real +credentials, passwords, or any client-specific detail — a guide +documents how to authenticate, never what to authenticate with. Treat +them as a starting shape to adapt, not a template to fill in verbatim. + +--- + +## Status + +**Early, actively being refined.** One real-world deployment (Tumbleweed) +informs the current guidance; Leap and SLES guidance is not yet verified +against an actual test pass. Several sub-workflows this repo's documents +reference are not yet written: + +| Referenced | Covers | +|---|---| +| `autoyast-crafting-workflow.md` | Authoring/selecting the AutoYaST profile itself — not yet written | +| `autoyast-error-debugging-workflow.md` | Diagnosing a failed verification check to root cause — not yet written | +| `suse-deploy-post-install-testing-workflow.md` | Post-install inspection beyond pass/fail — not yet written | +| `device-profile.md` | Client device intake sheet — not yet written | +| `suse-autoyast-deploy-phase2.md` | Bare-metal deployment at the client site — closes with the client handoff recommendation — not yet written | +| `suse-user-guide-example.md` | ✅ Written — generic user's guide, worked example | +| `administrator-guide-example.md` | Generic administrator's guide — not yet written | + +`[UNVERIFIED]` tags throughout the existing documents mark specific +claims not yet confirmed on Leap/SLES — check these explicitly before +relying on them for a real deployment. + +--- + +## Licence + +All original content in this repository is released to the public +domain under the Unlicense. + +--- + +## Project + +**Cervello Elettrico OS** — `git.jhoeven.net/ceos` + +Brianza, Italy · `servizi@cervelloelettrico.it` · `cervelloelettrico.it` + +*Crafted by John A. Hoeven with the ethical assistance of Claude AI (Anthropic).* \ No newline at end of file diff --git a/suse-user-guide-example.md b/suse-user-guide-example.md new file mode 100644 index 0000000..30bd77c --- /dev/null +++ b/suse-user-guide-example.md @@ -0,0 +1,610 @@ +# tinkerpad13 Quick Reference — Day-to-Day Admin and General Linux Basics + +My own enthusiast-level quick reference for my personal device (openSUSE +Tumbleweed) day-to-day administration. Covers shell navigation, zypper +package management, systemd services, users/permissions, storage and +Btrfs/Snapper, networking, logs, troubleshooting, and system updates. +Most commands are general Linux, not SUSE-specific; sections calling +out SUSE-specific behavior are tagged explicitly, and a few notes below +are specific to how *this* system is actually configured, not a general +SUSE default. + +[WARNING] This is a quick reference for common day-to-day tasks, not a +substitute for the official documentation for the exact SUSE release in +use. Commands, defaults, and package names shift between versions — +check documentation.suse.com or `man ` when something here +doesn't match what's on screen. + +--- + +## SECTION: Shell and navigation + + +To show the current directory: + +```sh +pwd +``` + +To list files including sizes and hidden files: + +```sh +ls -lah +``` + +To change directory: + +```sh +cd /path/to/directory +``` + +`cd ..` moves up one directory level. + +To copy a file or folder (recursive for folders): + +```sh +cp -r source destination +``` + +To move or rename a file or folder: + +```sh +mv source destination +``` + +To delete a folder and its contents: + +```sh +rm -r directory/ +``` + +[WARNING] `rm -r` has no undo and no trash — deleted files and folders +are not recoverable this way. + +To search for files by name: + +```sh +find / -name "pattern*" +``` + +To search inside files for text: + +```sh +grep -r "search text" directory/ +``` + +To page through a file's contents (press `q` to quit): + +```sh +less filename +``` + +To read the manual page for a command: + +```sh +man command +``` + +To search past commands: + +```sh +history | grep search-term +``` + +[NOTE] Tab-completion works everywhere in the shell — press Tab instead +of typing full paths or command names. + +--- + +## SECTION: Package management with zypper + + +zypper is SUSE's command-line package manager, used across Leap, SLES, +and Tumbleweed. + +To search for a package: + +```sh +zypper se search-term +``` + +To install a package: + +```sh +zypper in package-name +``` + +To remove a package: + +```sh +zypper rm package-name +``` + +To show details about a package: + +```sh +zypper info package-name +``` + +To check whether a package is installed and which version: + +```sh +zypper if package-name +``` + +To list configured repositories: + +```sh +zypper lr +``` + +To refresh repository metadata: + +```sh +zypper ref +``` + +To update installed packages on Leap or SLES: + +```sh +zypper up +``` + +To fully sync packages on Tumbleweed: + +```sh +zypper dup +``` + +[WARNING] On Tumbleweed, always use `zypper dup`, never `zypper up`. +Mixing the two commands can break dependency resolution on a rolling +release. + +To check whether a reboot is actually required after updates: + +```sh +zypper ps -s +``` + +--- + +## SECTION: Users, groups, and permissions + + +To show the current user: + +```sh +whoami +``` + +To show which groups the current user belongs to: + +```sh +groups +``` + +To run a single command as root: + +```sh +sudo command +``` + +To switch to another user's shell: + +```sh +su - username +``` + +To add a new user with a home directory: + +```sh +sudo useradd -m username +``` + +To add an existing user to a group: + +```sh +sudo usermod -aG groupname username +``` + +To set file permissions (owner/group/other): + +```sh +chmod 750 filename +``` + +To change file ownership: + +```sh +chown user:group filename +``` + +To change your own password: + +```sh +passwd +``` + +[WARNING] If sudo ever asks for root's password on this system, that +means elevation is not possible — root is locked (confirmed via +`passwd -l root`), so there is no password that will authenticate +against it. This is not a "try harder" situation — retyping it more +carefully won't help, there is no correct answer to give it. It means +the intended sudo configuration (own-password authentication via +`sudo-policy-wheel-auth-self` + `wheel` membership) is not in effect, +and the system needs to be fixed at the console or reinstalled, not +worked around. + +Ask me how I know. + +--- + +## SECTION: Services with systemd + + +To check whether a service is running, with recent log lines: + +```sh +systemctl status service-name +``` + +To start a service immediately: + +```sh +sudo systemctl start service-name +``` + +To stop a service immediately: + +```sh +sudo systemctl stop service-name +``` + +To restart a service (stop then start): + +```sh +sudo systemctl restart service-name +``` + +To make a service start automatically at boot: + +```sh +sudo systemctl enable service-name +``` + +To prevent a service from starting at boot: + +```sh +sudo systemctl disable service-name +``` + +To list every service that failed to start: + +```sh +systemctl --failed +``` + +To list all known services: + +```sh +systemctl list-units --type=service +``` + +[NOTE] `enable` and `start` are separate actions — enabling a service +does not start it immediately, and starting a service does not make it +survive a reboot. To do both at once: + +```sh +sudo systemctl enable --now service-name +``` + +--- + +## SECTION: Storage and disks + + +To show free space per mounted filesystem: + +```sh +df -h +``` + +To show the total size of a folder: + +```sh +du -sh directory/ +``` + +To list block devices and partitions: + +```sh +lsblk +``` + +To show what's currently mounted and where: + +```sh +mount +``` + +To mount a device manually: + +```sh +sudo mount /dev/device-name /mount-point +``` + +To check a drive's health quickly: + +```sh +sudo smartctl -H /dev/device-name +``` + +--- + +## SECTION: Btrfs and Snapper — SUSE default root filesystem + + +SUSE uses Btrfs as the default root filesystem, with Snapper managing +automatic snapshots. + +To list available snapshots: + +```sh +snapper list +``` + +To roll back to a specific snapshot number: + +```sh +sudo snapper rollback snapshot-number +``` + +To show real Btrfs space usage: + +```sh +btrfs filesystem usage / +``` + +[NOTE] Snapper automatically takes snapshots before and after package +changes — a broken update is usually a rollback away from being fixed, +without needing to reinstall anything. + +--- + +## SECTION: Networking + + +To show interfaces and IP addresses: + +```sh +ip a +``` + +To show the routing table: + +```sh +ip r +``` + +To show what's listening on which port: + +```sh +ss -tlnp +``` + +To test basic reachability to a host: + +```sh +ping hostname-or-ip +``` + +To show a NetworkManager device overview: + +```sh +nmcli device status +``` + +To show current firewall rules for the default zone: + +```sh +sudo firewall-cmd --list-all +``` + +To apply firewall configuration changes: + +```sh +sudo firewall-cmd --reload +``` + +[WARNING] Firewall changes made with `firewall-cmd` alone are temporary +and do not survive a reboot. Add `--permanent` to the change itself, +then run `--reload` to apply it. + +--- + +## SECTION: Logs and troubleshooting + + +To show recent logs with explanations, newest entries last: + +```sh +journalctl -xe +``` + +To show logs for one specific service: + +```sh +journalctl -u service-name +``` + +To show logs since the last boot: + +```sh +journalctl -b +``` + +To show logs within a specific time window: + +```sh +journalctl --since "1 hour ago" +``` + +To show kernel and hardware messages with timestamps: + +```sh +dmesg -T | tail -50 +``` + +To generate a full diagnostic bundle for SUSE support: + +```sh +sudo supportconfig +``` + +[NOTE] When something breaks unexpectedly, check `systemctl --failed` +first to find what's actually broken, then run +`journalctl -u -xe` to see the actual error. + +--- + +## SECTION: Processes and resources + + +To show a live view of processes and resource usage (press `q` to +quit): + +```sh +top +``` + +A friendlier alternative, if installed: + +```sh +htop +``` + +To find a specific running process: + +```sh +ps aux | grep process-name +``` + +To ask a process to stop: + +```sh +kill process-id +``` + +To force-stop a process as a last resort: + +```sh +kill -9 process-id +``` + +To show memory usage in human-readable form: + +```sh +free -h +``` + +To show how long since the last reboot and the current load average: + +```sh +uptime +``` + +--- + +## SECTION: Files you'll actually open + + +| File | Type | Purpose | +|---|---|---| +| `/etc/hostname` | `path` | The system's hostname | +| `/etc/fstab` | `path` | What mounts automatically at boot | +| `/etc/ssh/sshd_config` | `path` | SSH server settings | +| `/etc/sudoers.d/` | `path` | Sudo permission drop-in files | +| `/var/log/` | `path` | Traditional log location — most logging now lives in `journalctl` instead | +| `~/.bashrc` | `path` | The current user's own shell startup customizations | + +[WARNING] Never hand-edit `/etc/sudoers` directly — always use `visudo` +or a file in `/etc/sudoers.d/`. A syntax error in sudoers can lock out +sudo access entirely. + +--- + +## SECTION: Updating the system + + +To refresh and update on Leap or SLES: + +```sh +zypper ref && zypper up +``` + +To refresh and fully sync on Tumbleweed: + +```sh +zypper ref && zypper dup +``` + +To list available patches on Leap or SLES: + +```sh +zypper lp +``` + +To apply patches specifically: + +```sh +zypper patch +``` + +To confirm whether a reboot is required after updating: + +```sh +zypper ps -s +``` + +[NOTE] A snapshot is taken automatically before most updates via +Snapper — if an update goes wrong, rollback (Section: Btrfs and Snapper) +is usually available without reinstalling anything. + +--- + +## SECTION: Quick glossary + + +| Term | Type | Meaning | +|---|---|---| +| `YaST` | `string` | SUSE's central configuration tool, available as TUI or GUI | +| `zypper` | `string` | SUSE's command-line package manager | +| `Snapper` | `string` | Automatic Btrfs snapshot manager | +| `AutoYaST` | `string` | SUSE's unattended/scripted install system | +| `targetpw` | `string` | SUSE's default sudo behavior — asks for root's password, not the invoking user's own, unless changed | +| `wheel` | `string` | The group typically granted sudo access | + +--- + +## SECTION: When you're stuck + + +1. Run `systemctl --failed` — confirm what's actually broken. +2. Run `journalctl -u -xe` — see what the actual error says. +3. Run `snapper list` — check whether a rollback is the fastest fix. +4. Check documentation.suse.com for the exact release in use before + assuming a fix found elsewhere applies. +5. If still stuck, run `sudo supportconfig` and hand the resulting + bundle to whoever supports the system. + +[WARNING] This reference covers the commands used most days. It is not +a substitute for the official documentation for the specific SUSE +release in use — commands, defaults, and package names shift between +versions. + +--- +**Source:** CE OS — tinkerpad13 personal quick reference, developed 2026-07-26 +**Source-type:** `ce-authored` +**Licence:** John A. Hoeven with the ethical assistance of Claude AI — personal working document +**Verified-on:** tinkerpad13 (openSUSE Tumbleweed) — sudo/root behavior confirmed on this system directly; general commands are standard SUSE-family behavior +**Session:** 2026-07-26 \ No newline at end of file