From 74d262b6364bebac5edf8a271ed1deb4b0a73259 Mon Sep 17 00:00:00 2001 From: Thibault Koechlin Date: Tue, 26 May 2026 13:54:30 +0200 Subject: [PATCH 1/2] identify early users with installations from outdated / upstream repositories --- skills/crowdsec/SKILL.md | 42 ++++++++++++++- .../crowdsec/references/operate/upgrades.md | 53 ++++++++++++++++++- 2 files changed, 92 insertions(+), 3 deletions(-) diff --git a/skills/crowdsec/SKILL.md b/skills/crowdsec/SKILL.md index 87e4898..df83db5 100644 --- a/skills/crowdsec/SKILL.md +++ b/skills/crowdsec/SKILL.md @@ -52,6 +52,45 @@ If they are neither root nor a sudoer, **stop and ask them to grant it** — don guess. Once confirmed, run bare-metal commands as root or prefixed with `sudo`. Docker/k8s commands run inside the container/pod and do not need this. +## Step 1.5 — Version & install-source sanity check (Linux) + +Do this **first** on any install task and on any "weird behavior" report — missing +`cscli` commands/flags, hub items that won't install, behavior that doesn't match the +docs. A common, misleading failure is an engine that's **years behind** because it was +installed from the wrong source, not a config bug. This trap is **Linux-distro only** +(Docker/k8s pull a tag from Docker Hub — see the note at the end). + +Compare the running engine to the latest published release: + +```bash +curl -s https://version.crowdsec.net/latest # → {"tag_name":"v1.7.8",...}; parse tag_name +cscli version # bare-metal: prefix sudo +``` + +Then check **where the package came from**: + +```bash +# Debian/Ubuntu +apt-cache policy crowdsec # read the *** installed line's origin +ls /etc/apt/sources.list.d/ | grep -i crowdsec +# RHEL-family +dnf info crowdsec ; dnf repolist | grep -i crowdsec +``` + +The official source is the packagecloud repo (`packagecloud.io/crowdsec/crowdsec`, repo id +`crowdsec_crowdsec`). A distro origin (`archive.ubuntu.com`, `deb.debian.org`, +`ports.ubuntu.com`) — or **no crowdsec repo file at all** — means it was installed from the +distro's own ancient package. + +**Rule:** if the source isn't the official repo **or** the version is well behind +`tag_name`, treat it as a likely-outdated install — **stop debugging config** and migrate +onto the official repo first: [references/operate/upgrades.md](./references/operate/upgrades.md) +§ Detect & fix an outdated / distro-packaged install. + +**Docker/Kubernetes:** no repo-source trap — the version is the image tag pulled from Docker +Hub. If it's far behind `version.crowdsec.net/latest`, pull a newer tag +([references/operate/upgrades.md](./references/operate/upgrades.md) happy path). + ## Step 2 — Detect the intent | Cue from user | Go to | @@ -73,6 +112,7 @@ Docker/k8s commands run inside the container/pod and do not need this. | "AppSec", "WAF", "virtual patching", "block by request shape" | [references/appsec/](./references/appsec/) — overview, deploy, configure, troubleshoot | | "Console", "enroll", "share signals" | [references/install/console.md](./references/install/console.md) | | "upgrade", "back up", "roll back", "new version", "tainted items after upgrade" | [references/operate/upgrades.md](./references/operate/upgrades.md) | +| "old/outdated version", "`cscli` command or flag missing", "hub item won't install", "behavior doesn't match the docs", "installed from the distro package" | [references/operate/upgrades.md](./references/operate/upgrades.md) § Detect & fix an outdated / distro-packaged install (see **Step 1.5** above) | | "multiple agents", "remote LAPI", "mTLS", "postgres backend" | [references/operate/multi-server.md](./references/operate/multi-server.md) *(TODO — stub)* | | "is it working?", "smoke test", "validate install", "verify setup", "did detection / WAF / blocking actually wire up?" | [references/operate/health-check.md](./references/operate/health-check.md) | | **Debug — common** · "it's broken" / "not working" / general diagnosis | [references/debug/common/triage.md](./references/debug/common/triage.md) → run `bash ${CLAUDE_SKILL_DIR}/scripts/diagnose.sh` | @@ -98,7 +138,7 @@ These work in every environment. On bare-metal/systemd, prefix with `sudo` (unle | Purpose | Command | |---|---| -| Engine version | `cscli version` | +| Engine version (compare to latest: `curl -s https://version.crowdsec.net/latest`) | `cscli version` | | Effective config (paths, LAPI URL, DB type) | `cscli config show` | | One-shot triage table | `cscli metrics` | | Recent alerts | `cscli alerts list -l 50` | diff --git a/skills/crowdsec/references/operate/upgrades.md b/skills/crowdsec/references/operate/upgrades.md index 00aa6ad..c0bbaf6 100644 --- a/skills/crowdsec/references/operate/upgrades.md +++ b/skills/crowdsec/references/operate/upgrades.md @@ -1,9 +1,9 @@ --- verified: - - date: 2026-05-22 + - date: 2026-05-26 version: "1.7.8" env: systemd - notes: "apt-cache policy (no-op at latest, packagecloud repo, rollback table), hub upgrade, backup paths; non-destructive" + notes: "apt-cache policy (no-op at latest, packagecloud repo, rollback table), hub upgrade, backup paths; outdated/distro-source detection (official origin packagecloud.io/crowdsec/crowdsec + crowdsec_crowdsec.list confirmed; Ubuntu 26.04 universe trap = 1.4.6; version.crowdsec.net/latest tag_name); fix recipe not run end-to-end" --- # Operate — Upgrades, backup, rollback @@ -37,6 +37,55 @@ sudo cscli lapi status # LAPI still reachable The DB migrating forward is automatic and transparent: an engine upgraded across a minor version (e.g. v1.6 → v1.7) on the same data volume keeps all existing decisions and machines. +## Detect & fix an outdated / distro-packaged install (Linux) + +A common time-sink: the engine is **years behind** because it was installed from the wrong +source, not because an upgrade was skipped. `apt upgrade crowdsec` then does nothing useful — +it only moves within whatever repo the package came from. This is a **Linux-distro-only** trap; +Docker/Kubernetes pull a tag from Docker Hub and have no equivalent. Two origins cause it: + +- **The distro's own `crowdsec` package** — `apt install crowdsec` *without* first adding the + official repo pulls an ancient build from Debian/Ubuntu `universe` (e.g. Ubuntu 26.04 universe + ships `1.4.6` against a current `1.7.8`). +- **Outdated docs** pointing at a raw packagecloud `script.deb.sh` URL instead of the maintained + `https://install.crowdsec.net` entrypoint. + +Symptoms that should trigger this check: missing `cscli` commands/flags, hub items that won't +install, or behavior that doesn't match the current docs. + +**1 — Confirm how far behind you are.** Compare the running engine to the latest published +release: + +```bash +curl -s https://version.crowdsec.net/latest # → {"name":"v1.7.8","tag_name":"v1.7.8",...} +sudo cscli version # the engine you actually run +``` + +**2 — Identify the install source.** + +| Distro | Command | Official source | Trap | +|---|---|---|---| +| Debian/Ubuntu | `apt-cache policy crowdsec` (read the `***` installed line) and `ls /etc/apt/sources.list.d/ \| grep -i crowdsec` | origin `packagecloud.io/crowdsec/crowdsec`, repo file present | origin `archive.ubuntu.com` / `deb.debian.org` / `ports.ubuntu.com`, or **no** crowdsec repo file | +| RHEL-family | `dnf info crowdsec` (the "From repo" / "Repo" field) and `dnf repolist \| grep -i crowdsec` | repo id `crowdsec_crowdsec` | any other repo, or the distro's | + +If the source isn't the official repo, **stop debugging config** — the version is the problem. + +**3 — Migrate onto the official repo.** Back up first (config + DB survive a reinstall only if +you don't `purge` them — see [Backup](#backup--only-when-it-actually-matters) below), then add +the official repo and reinstall: + +```bash +sudo cp -a /etc/crowdsec /etc/crowdsec.bak +sudo cp -a /var/lib/crowdsec/data /var/lib/crowdsec/data.bak +sudo apt remove crowdsec # remove, not purge — keeps /etc/crowdsec +curl -s https://install.crowdsec.net | sudo sh # adds the signed official repo +sudo apt install crowdsec # or: sudo dnf install crowdsec +sudo systemctl restart crowdsec +sudo cscli version # now matches version.crowdsec.net/latest +``` + +Repo and post-install details are in [../install/bare-metal.md](../install/bare-metal.md) §1. + ## Bouncers upgrade on their own cadence Each bouncer is its **own package**, versioned independently of the engine — they're LAPI From 0cb26a7d0b72d8acd6503ffb7ea4a8b3819a4807 Mon Sep 17 00:00:00 2001 From: Thibault Koechlin Date: Tue, 26 May 2026 15:27:17 +0200 Subject: [PATCH 2/2] tighten --- skills/crowdsec/SKILL.md | 10 ++-- .../crowdsec/references/operate/upgrades.md | 48 +++---------------- 2 files changed, 11 insertions(+), 47 deletions(-) diff --git a/skills/crowdsec/SKILL.md b/skills/crowdsec/SKILL.md index df83db5..7e7ede3 100644 --- a/skills/crowdsec/SKILL.md +++ b/skills/crowdsec/SKILL.md @@ -54,11 +54,9 @@ Docker/k8s commands run inside the container/pod and do not need this. ## Step 1.5 — Version & install-source sanity check (Linux) -Do this **first** on any install task and on any "weird behavior" report — missing -`cscli` commands/flags, hub items that won't install, behavior that doesn't match the -docs. A common, misleading failure is an engine that's **years behind** because it was -installed from the wrong source, not a config bug. This trap is **Linux-distro only** -(Docker/k8s pull a tag from Docker Hub — see the note at the end). +Do this **first** on any install task and on any "weird behavior" report (missing +`cscli` commands/flags, hub items that won't install, behavior ≠ docs). An engine +installed from the wrong source can be **years behind** — a Linux-distro-only trap. Compare the running engine to the latest published release: @@ -138,7 +136,7 @@ These work in every environment. On bare-metal/systemd, prefix with `sudo` (unle | Purpose | Command | |---|---| -| Engine version (compare to latest: `curl -s https://version.crowdsec.net/latest`) | `cscli version` | +| Engine version | `cscli version` | | Effective config (paths, LAPI URL, DB type) | `cscli config show` | | One-shot triage table | `cscli metrics` | | Recent alerts | `cscli alerts list -l 50` | diff --git a/skills/crowdsec/references/operate/upgrades.md b/skills/crowdsec/references/operate/upgrades.md index c0bbaf6..78b8147 100644 --- a/skills/crowdsec/references/operate/upgrades.md +++ b/skills/crowdsec/references/operate/upgrades.md @@ -3,7 +3,7 @@ verified: - date: 2026-05-26 version: "1.7.8" env: systemd - notes: "apt-cache policy (no-op at latest, packagecloud repo, rollback table), hub upgrade, backup paths; outdated/distro-source detection (official origin packagecloud.io/crowdsec/crowdsec + crowdsec_crowdsec.list confirmed; Ubuntu 26.04 universe trap = 1.4.6; version.crowdsec.net/latest tag_name); fix recipe not run end-to-end" + notes: "apt-cache policy (no-op at latest, packagecloud repo, rollback table), hub upgrade, backup paths; outdated/distro-source facts confirmed (official origin packagecloud.io/crowdsec/crowdsec, Ubuntu 26.04 universe trap = 1.4.6); migrate-in-place recipe not run end-to-end" --- # Operate — Upgrades, backup, rollback @@ -39,52 +39,18 @@ version (e.g. v1.6 → v1.7) on the same data volume keeps all existing decision ## Detect & fix an outdated / distro-packaged install (Linux) -A common time-sink: the engine is **years behind** because it was installed from the wrong -source, not because an upgrade was skipped. `apt upgrade crowdsec` then does nothing useful — -it only moves within whatever repo the package came from. This is a **Linux-distro-only** trap; -Docker/Kubernetes pull a tag from Docker Hub and have no equivalent. Two origins cause it: - -- **The distro's own `crowdsec` package** — `apt install crowdsec` *without* first adding the - official repo pulls an ancient build from Debian/Ubuntu `universe` (e.g. Ubuntu 26.04 universe - ships `1.4.6` against a current `1.7.8`). -- **Outdated docs** pointing at a raw packagecloud `script.deb.sh` URL instead of the maintained - `https://install.crowdsec.net` entrypoint. - -Symptoms that should trigger this check: missing `cscli` commands/flags, hub items that won't -install, or behavior that doesn't match the current docs. - -**1 — Confirm how far behind you are.** Compare the running engine to the latest published -release: - -```bash -curl -s https://version.crowdsec.net/latest # → {"name":"v1.7.8","tag_name":"v1.7.8",...} -sudo cscli version # the engine you actually run -``` - -**2 — Identify the install source.** - -| Distro | Command | Official source | Trap | -|---|---|---|---| -| Debian/Ubuntu | `apt-cache policy crowdsec` (read the `***` installed line) and `ls /etc/apt/sources.list.d/ \| grep -i crowdsec` | origin `packagecloud.io/crowdsec/crowdsec`, repo file present | origin `archive.ubuntu.com` / `deb.debian.org` / `ports.ubuntu.com`, or **no** crowdsec repo file | -| RHEL-family | `dnf info crowdsec` (the "From repo" / "Repo" field) and `dnf repolist \| grep -i crowdsec` | repo id `crowdsec_crowdsec` | any other repo, or the distro's | - -If the source isn't the official repo, **stop debugging config** — the version is the problem. - -**3 — Migrate onto the official repo.** Back up first (config + DB survive a reinstall only if -you don't `purge` them — see [Backup](#backup--only-when-it-actually-matters) below), then add -the official repo and reinstall: +If the engine is **years behind**, the fix isn't `apt upgrade` — that only moves within whatever +repo the package came from. Detect it with the version + install-source check in `SKILL.md` +Step 1.5. If it was installed from the wrong source, add the official repo and upgrade in place — +`apt install` (no `--purge`) keeps `/etc/crowdsec` and the DB: ```bash -sudo cp -a /etc/crowdsec /etc/crowdsec.bak -sudo cp -a /var/lib/crowdsec/data /var/lib/crowdsec/data.bak -sudo apt remove crowdsec # remove, not purge — keeps /etc/crowdsec curl -s https://install.crowdsec.net | sudo sh # adds the signed official repo -sudo apt install crowdsec # or: sudo dnf install crowdsec +sudo apt install crowdsec # or: sudo dnf install crowdsec — pulls latest sudo systemctl restart crowdsec -sudo cscli version # now matches version.crowdsec.net/latest ``` -Repo and post-install details are in [../install/bare-metal.md](../install/bare-metal.md) §1. +Repo and post-install details: [../install/bare-metal.md](../install/bare-metal.md) §1. ## Bouncers upgrade on their own cadence