Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ check:
test -f system_files/shared/usr/lib/systemd/system/bootc-unified-storage.service.d/10-utah-local-test.conf
grep -q 'enable gdm.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
grep -q 'enable ublue-system-setup.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
grep -q 'enable utah-countme.timer' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
test -f system_files/shared/usr/lib/systemd/system/utah-countme.service
test -f system_files/shared/usr/lib/systemd/system/utah-countme.timer
test -f system_files/shared/usr/libexec/utah-countme
grep -q 'disable bootc-fetch-apply-updates.timer' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
grep -q 'disable bootc-fetch-apply-updates.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset
grep -q 'bootc-fetch-apply-updates.timer' scripts/configure-services.sh
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,10 @@ This is the honest list, and it is why the label above says pre-alpha.
repository is consumed and the local QEMU image reaches GDM and GNOME Shell.
- **CUDA is deliberately excluded** — 7.68 GB installed. Use the NVIDIA
container toolkit, which is included, and run CUDA in a container.
- **Telemetry (countme).** Utah includes a weekly countme client reporting
to `countme.projectbluefin.io` following Bluefin ADR 0006. Users can opt out
by running `sudo touch /etc/projectbluefin/countme/disabled` or by masking
the timer: `sudo systemctl mask utah-countme.timer`.

See the [open issues](https://github.com/projectbluefin/utah/issues) for where
things stand.
Expand Down
1 change: 1 addition & 0 deletions contracts/bluefin-desktop.toml
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ enabled = [
"flatpak-preinstall.service",
"gdm.service",
"ublue-system-setup.service",
"utah-countme.timer",
"uupd.timer",
]
masked = [
Expand Down
40 changes: 31 additions & 9 deletions docs/skills/desktop-contract.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
name: desktop-contract
version: "1.0"
version: "1.1"
last_updated: "2026-09-18"
id: desktop-contract
one_line_purpose: Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy.
one_line_purpose: Maintain Utah identity, Bluefin desktop defaults, telemetry, and first-boot Flatpak policy.
entry_point: docs/skills/desktop-contract.md
category: contracts
mcp_compliance_level: partial
optimization_status: draft
status: active
dependencies: []
tags: [desktop, branding, gnome, flatpak]
tags: [desktop, branding, gnome, flatpak, telemetry, countme]
description: >-
The runtime desktop contract in contracts/bluefin-desktop.toml and its
in-image verifiers. Use when changing branding, os-release, service
presets, GNOME extensions, or first-boot Flatpak behavior.
presets, GNOME extensions, countme telemetry, or first-boot Flatpak behavior.
metadata:
type: policy
---
Expand Down Expand Up @@ -57,7 +57,7 @@ The TOML's sections are the contract's table of contents:
- **`[services]`** — systemd units the preset must enable: `gdm.service`,
`bluetooth.service`, `ublue-system-setup.service`, `flatpak-preinstall.service`,
`flatpak-nuke-fedora.service`, `brew-setup.service`, `dconf-update.service`,
`bootc-unified-storage.service`, `uupd.timer`. Update policy delegates
`bootc-unified-storage.service`, `utah-countme.timer`, `uupd.timer`. Update policy delegates
background updates to `uupd.timer`; `bootc-fetch-apply-updates.timer` and
`bootc-fetch-apply-updates.service` are masked in `/etc` and `/usr/lib` (and
disabled in `85-utah-desktop.preset`) so cross-vendor `/etc` 3-way merges
Expand Down Expand Up @@ -100,16 +100,38 @@ on `GjsPrivate.DBusImplementation`, gracefully degrading to an inert portal on G
Hummingbird defaults to a server preset and disables unlisted services, so
the desktop policy is applied explicitly. `scripts/configure-services.sh`
mirrors bluefin-lts's `40-services.sh`: it applies the desktop presets,
enables GDM, firmware updates, Tailscale, uupd, user setup and resolved,
configures authselect, and removes the extension build toolchain before
cleanup (Containerfile RUN comment; originated in `docs/building.md`'s former
design section and now lives in this skill).
enables GDM, firmware updates, Tailscale, uupd, user setup, resolved, and
the weekly `utah-countme.timer` client reporting, configures authselect, and
removes the extension build toolchain before cleanup (Containerfile RUN comment;
originated in `docs/building.md`'s former design section and now lives in this
skill).

Hummingbird's base does not include `systemd-resolved` by default; it is listed
under `[services]` in `packages/utah.toml` and configured in
`scripts/configure-services.sh`, which also disables `PrivateTmp` on
`systemd-resolved.service` for bootc early-boot DNS resolution.

## Countme telemetry

Utah reports weekly anonymous telemetry to `countme.projectbluefin.io` matching
Project Bluefin ADR 0006:
- **Client implementation:** `/usr/libexec/utah-countme` executed via
`utah-countme.service` and scheduled by `utah-countme.timer`.
- **Systemd isolation:** Runs as `DynamicUser=yes` with
`StateDirectory=utah-countme` storing local installation `epoch` and
`lastrun` timestamps.
- **Reporting parameters & query string:** An empty HTTP GET request is sent to
`https://countme.projectbluefin.io/metalink?repo=${REPO}&tag=${IMAGE_TAG}&flavor=${IMAGE_FLAVOR}&arch=${ARCH}&countme=${BUCKET}`
- `repo`: image name (`utah` or custom variant)
- `tag`: OS image version / release tag
- `flavor`: desktop flavor (`main`, `nvidia`, `gaming`, etc.)
- `arch`: system architecture (`x86_64`)
- `countme`: installation age cohort bucket (1: first week, 2: 2–4 weeks, 3: 5–24 weeks, 4: >24 weeks)
- **Data & logging policy:** No personal information or hardware identifiers are transmitted; requests contain no HTTP body. As with all HTTP requests, standard server connection metadata (including client IP address) is received by the endpoint for aggregate deduplication and cohort counting.
- **Network & failure resilience:** Requests use an explicit `--max-time 10` timeout. `lastrun` is updated unconditionally before the request so network or endpoint outages do not trigger daily retry storms on reboot; failed reports are simply dropped.
- **Persistent state integrity:** The install epoch is stored in `/var/lib/utah-countme/epoch`. If this file exists but cannot be read or is corrupted, execution degrades to a no-op (no ping sent and no epoch reset) to avoid resetting systems into bucket 1.
- **Opt-out:** Honored whenever `/etc/projectbluefin/countme/disabled` exists, or by masking the timer (`systemctl mask utah-countme.timer`).

## The verifiers run twice

The same verifier runs in the Containerfile and on demand, so a local image
Expand Down
10 changes: 6 additions & 4 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,20 @@
{
"id": "desktop-contract",
"name": "desktop-contract",
"one_line_purpose": "Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy.",
"one_line_purpose": "Maintain Utah identity, Bluefin desktop defaults, telemetry, and first-boot Flatpak policy.",
"entry_point": "docs/skills/desktop-contract.md",
"category": "contracts",
"status": "active",
"tags": [
"desktop",
"branding",
"gnome",
"flatpak"
"flatpak",
"telemetry",
"countme"
],
"description": "The runtime desktop contract in contracts/bluefin-desktop.toml and its in-image verifiers. Use when changing branding, os-release, service presets, GNOME extensions, or first-boot Flatpak behavior.",
"version": "1.0",
"description": "The runtime desktop contract in contracts/bluefin-desktop.toml and its in-image verifiers. Use when changing branding, os-release, service presets, GNOME extensions, countme telemetry, or first-boot Flatpak behavior.",
"version": "1.1",
"last_updated": "2026-09-18",
"doc_type": "policy"
},
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Generated: 2026-09-19 · schema 1.0 · 8 skills
|---|---|---|---|
| [ci-workflows](ci-workflows.md) | ci-ops | active | Navigate Utah's build, promote, and sync workflow topology. |
| [containerfile](containerfile.md) | image-build | active | Edit the Containerfile without regressing layer count or cache hits. |
| [desktop-contract](desktop-contract.md) | contracts | active | Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy. |
| [desktop-contract](desktop-contract.md) | contracts | active | Maintain Utah identity, Bluefin desktop defaults, telemetry, and first-boot Flatpak policy. |
| [flavors](flavors.md) | image-build | active | Add, remove, or retire an image flavor safely. |
| [kernel-cache](kernel-cache.md) | image-build | active | Understand and rebuild the OGC kernel and NVIDIA module cache image. |
| [local-testing](local-testing.md) | testing | active | Build, install, and boot Utah locally in a VM or live ISO. |
Expand Down
1 change: 1 addition & 0 deletions scripts/configure-services.sh
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ enable_unit fwupd.service
enable_unit fwupd-refresh.timer
enable_unit dconf-update.service
enable_unit tailscaled.service
enable_unit utah-countme.timer
enable_unit uupd.timer
enable_unit ublue-system-setup.service
enable_unit systemd-resolved.service
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ enable firewalld.service
enable fwupd.service
enable fwupd-refresh.timer
enable tailscaled.service
enable utah-countme.timer
enable uupd.timer
enable ublue-system-setup.service
enable systemd-resolved.service
Expand Down
16 changes: 16 additions & 0 deletions system_files/shared/usr/lib/systemd/system/utah-countme.service
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[Unit]
Description=Weekly Utah Count Me telemetry reporting
Documentation=https://docs.projectbluefin.io
Wants=network-online.target
After=network-online.target
ConditionPathExists=/run/ostree-booted
ConditionPathExists=/usr/share/ublue-os/image-info.json
ConditionPathExists=!/etc/projectbluefin/countme/disabled

[Service]
Type=oneshot
DynamicUser=yes
StateDirectory=utah-countme
ExecStart=/usr/libexec/utah-countme
StandardOutput=journal
StandardError=journal
16 changes: 16 additions & 0 deletions system_files/shared/usr/lib/systemd/system/utah-countme.timer
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[Unit]
Description=Weekly Utah Count Me telemetry timer
Documentation=https://docs.projectbluefin.io
ConditionPathExists=/run/ostree-booted
ConditionPathExists=/usr/share/ublue-os/image-info.json
ConditionPathExists=!/etc/projectbluefin/countme/disabled

[Timer]
OnBootSec=10m
OnCalendar=weekly
Persistent=true
AccuracySec=1h
RandomizedDelaySec=12h

[Install]
WantedBy=timers.target
136 changes: 136 additions & 0 deletions system_files/shared/usr/libexec/utah-countme
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
#!/usr/bin/bash
# /usr/libexec/utah-countme
# Weekly user-counting client for Utah (bootc) systems
set -euo pipefail

DISABLED_FILE="${DISABLED_FILE:-/etc/projectbluefin/countme/disabled}"
IMAGE_INFO="${IMAGE_INFO:-/usr/share/ublue-os/image-info.json}"
STATE_DIR="${STATE_DIRECTORY:-/var/lib/utah-countme}"
OS_RELEASE_FILE="${OS_RELEASE_FILE:-/etc/os-release}"
WEEK=604800

# Allow users to opt out without disabling the timer.
[ -e "$DISABLED_FILE" ] && exit 0

if ! command -v curl >/dev/null 2>&1; then
echo "utah-countme: curl is unavailable; skipping telemetry" >&2
exit 0
fi

NOW=$(date +%s)

# Ensure state directory exists
if [ ! -d "$STATE_DIR" ]; then
mkdir -p "$STATE_DIR"
fi

EPOCH_FILE="${STATE_DIR}/epoch"
LASTRUN_FILE="${STATE_DIR}/lastrun"

# 1. Read or initialize epoch file
# Note: The epoch is recorded the first time this script runs (typically ~10m
# after first boot via OnBootSec=10m) and acts as the baseline for cohort age.
if [ ! -f "$EPOCH_FILE" ]; then
echo "$NOW" > "$EPOCH_FILE" || {
echo "utah-countme: cannot initialize epoch file; skipping telemetry" >&2
exit 0
}
fi

if ! EPOCH=$(cat "$EPOCH_FILE" 2>/dev/null) || [ -z "$EPOCH" ] || ! [[ "$EPOCH" =~ ^[0-9]+$ ]]; then
echo "utah-countme: cannot read epoch file; skipping telemetry" >&2
exit 0
fi

# 2. Throttling: only run once per 7-day window
if [ -f "$LASTRUN_FILE" ]; then
LASTRUN=$(cat "$LASTRUN_FILE" 2>/dev/null || echo 0)
if [[ "$LASTRUN" =~ ^[0-9]+$ ]] && (( NOW - LASTRUN < WEEK )); then
exit 0
fi
fi

# 3. Compute Fedora-style week bucket
# 1: first week, 2: 2–4w, 3: 5–24w, 4: >24w
if (( NOW < EPOCH )); then
WEEKS=1
else
WEEKS=$(( (NOW - EPOCH) / WEEK + 1 ))
fi

if (( WEEKS <= 1 )); then
BUCKET=1
elif (( WEEKS <= 4 )); then
BUCKET=2
elif (( WEEKS <= 24 )); then
BUCKET=3
else
BUCKET=4
fi

# 4. Extract image metadata
REPO="utah"
IMAGE_TAG="unknown"
IMAGE_FLAVOR="unknown"

if [ -f "$IMAGE_INFO" ]; then
read -r INFO_NAME INFO_TAG INFO_FLAVOR < <(python3 -c '
import json, sys
try:
with open(sys.argv[1]) as f:
d = json.load(f)
print(d.get("image-name", "") or "", d.get("image-tag", "") or "", d.get("image-flavor", "") or "")
except Exception:
print("", "", "")
' "$IMAGE_INFO")
if [ -n "$INFO_NAME" ]; then
REPO="$INFO_NAME"
fi
if [ -n "$INFO_TAG" ]; then
IMAGE_TAG="$INFO_TAG"
fi
if [ -n "$INFO_FLAVOR" ]; then
IMAGE_FLAVOR="$INFO_FLAVOR"
fi
fi

# Fallback to os-release if tag or flavor are still unknown
if [ -f "$OS_RELEASE_FILE" ]; then
if [ "$IMAGE_TAG" = "unknown" ]; then
OS_VERSION=$(grep -E '^OSTREE_VERSION=' "$OS_RELEASE_FILE" 2>/dev/null | head -n1 | cut -d= -f2 | tr -d '"' || true)
if [ -z "$OS_VERSION" ]; then
OS_VERSION=$(grep -E '^IMAGE_VERSION=' "$OS_RELEASE_FILE" 2>/dev/null | head -n1 | cut -d= -f2 | tr -d '"' || true)
fi
if [ -z "$OS_VERSION" ]; then
OS_VERSION=$(grep -E '^VERSION_ID=' "$OS_RELEASE_FILE" 2>/dev/null | head -n1 | cut -d= -f2 | tr -d '"' || true)
fi
if [ -n "$OS_VERSION" ]; then
IMAGE_TAG="$OS_VERSION"
fi
fi
if [ "$IMAGE_FLAVOR" = "unknown" ]; then
OS_FLAVOR=$(grep -E '^IMAGE_FLAVOR=' "$OS_RELEASE_FILE" 2>/dev/null | cut -d= -f2 | tr -d '"' || true)
if [ -n "$OS_FLAVOR" ]; then
IMAGE_FLAVOR="$OS_FLAVOR"
fi
fi
fi

# Default flavor to "main" if still unspecified
if [ "$IMAGE_FLAVOR" = "unknown" ]; then
IMAGE_FLAVOR="main"
fi

ARCH=$(uname -m)
OS_VERSION_ID="unknown"
if [ -f "$OS_RELEASE_FILE" ]; then
OS_VERSION_ID=$(grep -E '^VERSION_ID=' "$OS_RELEASE_FILE" 2>/dev/null | cut -d= -f2 | tr -d '"' || echo "unknown")
fi

# 5. Formulate request
USER_AGENT="utah-countme (${REPO} ${OS_VERSION_ID}; ${IMAGE_FLAVOR}; Linux.${ARCH})"
URL="https://countme.projectbluefin.io/metalink?repo=${REPO}&tag=${IMAGE_TAG}&flavor=${IMAGE_FLAVOR}&arch=${ARCH}&countme=${BUCKET}"

# 6. Send ping (update lastrun unconditionally to prevent outage retry storms)
echo "$NOW" > "$LASTRUN_FILE"
curl -sf --retry 3 --max-time 10 -H "User-Agent: ${USER_AGENT}" "$URL" >/dev/null || true
Loading
Loading