From d3707a4fc19590cc72d2edc7227b863a716e73d0 Mon Sep 17 00:00:00 2001 From: CookieSource <36531905+CookieSource@users.noreply.github.com> Date: Sun, 28 Sep 2025 18:23:28 +0200 Subject: [PATCH] Add System management documentation & Monitoring This update adds new documentation on how to setup the monitoring file. It also adds some basic documentation on system management. Adding a new side bar entry. --- astro.config.mjs | 9 ++ .../docs/Packaging/Recipes/monitoring.mdx | 121 ++++++++++++++++++ .../configuration-locations.mdx | 48 +++++++ .../docs/Users/System Management/index.mdx | 10 ++ .../moss-state-management.mdx | 105 +++++++++++++++ 5 files changed, 293 insertions(+) create mode 100644 src/content/docs/Packaging/Recipes/monitoring.mdx create mode 100644 src/content/docs/Users/System Management/configuration-locations.mdx create mode 100644 src/content/docs/Users/System Management/index.mdx create mode 100644 src/content/docs/Users/System Management/moss-state-management.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 76435464..992939d7 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -47,6 +47,14 @@ export default defineConfig({ }, ], }, + { + label: "System Management", + items: [ + { slug: "users/system-management" }, + { slug: "users/system-management/configuration-locations" }, + { slug: "users/system-management/moss-state-management" }, + ], + }, { label: "Desktops", items: [ @@ -79,6 +87,7 @@ export default defineConfig({ { slug: "packaging/recipes/overview" }, { slug: "packaging/recipes/upstreams" }, { slug: "packaging/recipes/metadata" }, + { slug: "packaging/recipes/monitoring" }, { slug: "packaging/recipes/build-deps" }, { slug: "packaging/recipes/package-definition" }, { diff --git a/src/content/docs/Packaging/Recipes/monitoring.mdx b/src/content/docs/Packaging/Recipes/monitoring.mdx new file mode 100644 index 00000000..c141fec3 --- /dev/null +++ b/src/content/docs/Packaging/Recipes/monitoring.mdx @@ -0,0 +1,121 @@ +--- +title: Monitoring +lastUpdated: 2025-09-28T16:14:34Z +description: Create and maintain monitoring.yaml so release automation and security alerts stay accurate. +--- + +Every recipe should ship a `monitoring.yaml` so our tooling can watch for upstream releases and security issues. Use this reference to populate the file consistently and to find the data required for each field. + +## File layout + +A minimal monitoring file includes release tracking and optional security metadata: + +```yaml +releases: + id: 00000 + rss: https://example.com/project/releases.atom +security: + cpe: + - vendor: example + product: project +``` + +Indent with two spaces and keep related comments inline so CI and reviewers can follow your reasoning. + +## Release tracking + +`releases.id` +: Numeric identifier from [release-monitoring.org](https://release-monitoring.org) (Anitya). Look up the upstream project and note the number in the URL, for example `https://release-monitoring.org/project/300958` for Python. + +`releases.rss` +: URL to an Atom/RSS feed for new releases. Use `~` if no feed exists. + +### Common feed patterns + +- **GitHub**: `https://github.com///releases.atom` or `.../tags.atom` +- **GitLab / KDE Invent**: append `/-/tags?format=atom` to the project URL, for example `https://invent.kde.org/plasma/plasma-desktop/-/tags?format=atom` +- **PyPI**: no feed is required; prefer `~` and rely on the Anitya ID +- **Freedesktop GitLab**: `https://gitlab.freedesktop.org//-/tags?format=atom` +- **Custom sites**: many upstreams publish a `releases.xml`/`atom.xml` file; link directly when available + +### Ignore patterns + +Use `releases.ignore` to skip versions our repo does not track. Provide a short comment and regular expressions that match the releases to drop. + +```yaml +releases: + id: 320206 + ignore: + # Qt 6 builds are out of scope for qt5 packages + - ^6\. + rss: ~ +``` + +Prefer anchored expressions (`^` / `$`) to avoid false positives. + +## Security metadata + +`security.cpe` +: List of Common Platform Enumeration entries to watch in the NVD feed. Search [nvd.nist.gov](https://nvd.nist.gov/products/cpe) for vendor and product strings. Add every applicable CPE when upstream ships multiple identifiers. + +`security.ignore` +: Optional list of CVE IDs or regexes our package should ignore (for example, CVEs that only affect optional components). + +If no CPE exists, set the value to `~` and add a dated comment noting the last time you checked. + +```yaml +security: + cpe: ~ + # No known CPE as of 2024-09-01 +``` + +## Where to find the data + +1. **Start with release-monitoring.org**: search for the upstream name. +2. **Collect feeds**: confirm the `releases.atom` or `/-/tags?format=atom` URL opens in a browser. Use curl or `wget -qO- ` locally when you need to double-check. +3. **Identify CPE strings**: search the NVD catalog or reuse values from similar recipes. Many projects share vendor IDs (for example, both upstream `python` and the `urllib3` package provide CPEs). +4. **Document exceptions**: add comments whenever you set `ignore` patterns or leave fields empty so future maintainers understand the decision. + +## Example templates + +### GitHub project with security feed + +```yaml +releases: + id: 4078 + rss: https://github.com/urllib3/urllib3/releases.atom +security: + cpe: + - vendor: urllib3 + product: urllib3 + - vendor: python + product: urllib3 +``` + +### GitLab project with prerelease filter + +```yaml +releases: + id: 5440 + ignore: + # Track the current stable branch only + - 258.* + rss: https://gitlab.freedesktop.org/systemd/systemd/-/tags?format=atom +security: + cpe: + - vendor: systemd_project + product: systemd +``` + +### No CPE available + +```yaml +releases: + id: 19755 + rss: ~ +security: + cpe: ~ + # No CPE published as of 2023-03-23 +``` + +Keep monitoring files in sync with upstream changes. When a project moves or renames releases, update the ID and feed so our automated tooling continues to work. diff --git a/src/content/docs/Users/System Management/configuration-locations.mdx b/src/content/docs/Users/System Management/configuration-locations.mdx new file mode 100644 index 00000000..dcfb9326 --- /dev/null +++ b/src/content/docs/Users/System Management/configuration-locations.mdx @@ -0,0 +1,48 @@ +--- +title: Configuration Locations +lastUpdated: 2025-09-28T16:14:34Z +description: Understand where packages ship their default configuration and how to override it on a stateless system. +--- + +AerynOS ships configuration in a stateless layout. Packages deliver defaults in `/usr/share/defaults`, while administrator and user changes live elsewhere so updates can proceed without overwriting your work. + +## System defaults + +Default files mirror the traditional `/etc` hierarchy under `/usr/share/defaults`. + +| Purpose | Default location | Example contents | +| --- | --- | --- | +| Base system settings | `/usr/share/defaults/etc` | `ld.so.conf`, `libnl`, `tpm2-tss` | +| PAM policies | `/usr/share/defaults/pam.d` | `sudo`, `system-login`, `polkit-1` | +| Shell profiles | `/usr/share/defaults/profile` and `/usr/share/defaults/profile.d` | `00-aeryn.sh`, interactive shell tweaks | +| Service defaults | `/usr/share/defaults/environment.d` | Session-wide environment snippets | +| Sudo configuration | `/usr/share/defaults/sudo` | `sudoers`, drop-in files | +| SSH defaults | `/usr/share/defaults/ssh` | `ssh_config`, `sshd_config` | + + +Packages may add more directories under `/usr/share/defaults` as required. The layout always mirrors where the file would appear under `/etc` on a traditional filesystem. + +## System overrides + +Place administrator overrides in `/etc`. Files in `/etc` shadow anything under `/usr/share/defaults` and survive package updates. Use drop-in directories such as `/etc/pam.d` or `/etc/sudoers.d` to keep customisations scoped and easy to audit. + +When you need to revert to the shipped defaults, remove the override from `/etc` and Moss will fall back to the matching file in `/usr/share/defaults`. + +## User-level configuration + +Desktop and application settings follow the XDG Base Directory specification. Store per-user changes in: + +- `~/.config` for configuration files +- `~/.local/share` for data files + +These paths override both `/etc` and `/usr/share/defaults` for the owning user. + +## Where to look next + +Run the following command to explore the current defaults on your system: + +```bash +ls /usr/share/defaults +``` + +Combine this with `moss search-file` to identify which package owns a specific default file when you need to adjust or report an issue. diff --git a/src/content/docs/Users/System Management/index.mdx b/src/content/docs/Users/System Management/index.mdx new file mode 100644 index 00000000..7b74c1a3 --- /dev/null +++ b/src/content/docs/Users/System Management/index.mdx @@ -0,0 +1,10 @@ +--- +title: System Management +lastUpdated: 2025-09-28T16:14:34Z +description: Keep an AerynOS system healthy with stateless configuration guidance and moss lifecycle tasks. +--- +import DirectoryList from '@components/DirectoryList.astro'; + +Use this section to manage an installed system, from understanding where configuration lives to operating moss states safely. + + diff --git a/src/content/docs/Users/System Management/moss-state-management.mdx b/src/content/docs/Users/System Management/moss-state-management.mdx new file mode 100644 index 00000000..e109eea8 --- /dev/null +++ b/src/content/docs/Users/System Management/moss-state-management.mdx @@ -0,0 +1,105 @@ +--- +title: Manage Moss States and Packages +lastUpdated: 2025-09-28T16:14:34Z +description: Learn how to inspect and switch states, search for software, and keep an AerynOS system up to date with moss. +--- + +Moss keeps AerynOS stateless by tracking every change as a state. Use the commands below to inspect those states, discover software, and keep your system current. + +## Check the current state + +1. List the active state to confirm what is running right now. + +```bash +sudo moss state active +``` + +2. Review the state history when you need context for a rollback. + +```bash +sudo moss state list +``` + +Use the state ID (the number after `State #`) when you need to query or activate a specific snapshot. + +## Activate a different state + +Follow these steps to roll back or advance to another state safely. + +1. Identify the target state ID with `moss state list`. +2. Activate that state. + +```bash +sudo moss state activate 128 +``` + +3. Verify the change. + +```bash +sudo moss state active +``` + +Activating a state rewrites the live system to match that snapshot. Reboot afterwards so long-running services start with the expected binaries and configuration. + +## Search for packages + +Use keyword searches to discover software by name or summary. + +```bash +sudo moss search fractional +``` + +Add `--installed` if you only want to search software that is already present on the system. + +## Search for installed files + +Look up which package delivered a specific file when you troubleshoot or audit an installation. + +```bash +sudo moss search-file libEGL.so +``` + +`moss search-file` scans files from installed packages only. + +## Install software + +1. Refresh repository metadata when needed. + +```bash +sudo moss repo update +``` + +2. Install one or more packages. + +```bash +sudo moss install howdy-git +``` + +Moss creates a new state automatically. Confirm success with `moss state active`. + +## Update the system + +Keep the entire system current with a sync operation. + +```bash +sudo moss sync --update +``` + +`--update` pulls fresh repository metadata before applying upgrades. Moss records the result as a new state, so you can roll back if something goes wrong. + +## Remove software + +Uninstall packages you no longer need. + +```bash +sudo moss remove howdy-git +``` + +Moss snapshots the removal in a new state. Use `moss state list` to find the previous state if you have to recover. + +## List currently installed software + + +```bash +moss list +```