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
6 changes: 6 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ 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
bash -n system_files/shared/usr/libexec/utah-countme
pytest tests/unit/test_countme.py
test -f scripts/configure-services.sh
bash -n scripts/configure-services.sh
test -f scripts/configure-branding.sh
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,5 +138,6 @@ enabled = [
"flatpak-preinstall.service",
"gdm.service",
"ublue-system-setup.service",
"utah-countme.timer",
"uupd.timer",
]
42 changes: 32 additions & 10 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"
last_updated: "2026-09-05"
version: "1.1"
last_updated: "2026-09-11"
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`,
`ublue-system-setup.service`, `flatpak-preinstall.service`,
`flatpak-nuke-fedora.service`, `brew-setup.service`, `dconf-update.service`,
`bootc-unified-storage.service`, `uupd.timer`.
`bootc-unified-storage.service`, `utah-countme.timer`, `uupd.timer`.

## GNOME extensions are pinned submodules

Expand Down Expand Up @@ -88,16 +88,38 @@ system and glib-compile-schemas.
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. If the server is unreachable or offline, the script exits cleanly without updating `lastrun`, allowing the ping to be retried on the next schedule without skipping a weekly reporting window.
- **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
14 changes: 8 additions & 6 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-09-05",
"generated_at": "2026-09-11",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -41,19 +41,21 @@
{
"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",
"last_updated": "2026-09-05",
"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-11",
"doc_type": "policy"
},
{
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@
This file is a human-readable mirror of `index.json`. Both are generated by
`scripts/generate_skill_index.py` — do not hand-edit either file.

Generated: 2026-09-05 · schema 1.0 · 8 skills
Generated: 2026-09-11 · schema 1.0 · 8 skills

| id | category | status | one-line purpose |
|---|---|---|---|
| [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 @@ -46,6 +46,7 @@ enable_unit fwupd-refresh.timer
enable_unit dconf-update.service
enable_unit tailscaled.service
enable_unit uupd.timer
enable_unit utah-countme.timer
enable_unit ublue-system-setup.service
enable_unit systemd-resolved.service
enable_unit bootc-unified-storage.service
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ enable fwupd.service
enable fwupd-refresh.timer
enable tailscaled.service
enable uupd.timer
enable utah-countme.timer
enable ublue-system-setup.service
enable systemd-resolved.service
enable bootc-unified-storage.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
123 changes: 123 additions & 0 deletions system_files/shared/usr/libexec/utah-countme
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
#!/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 jq >/dev/null 2>&1; then
echo "utah-countme: jq is unavailable; skipping telemetry" >&2
exit 0
fi

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
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 (( 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
WEEKS=$(( (NOW - EPOCH) / WEEK + 1 ))
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
INFO_NAME=$(jq -r '."image-name" // empty' "$IMAGE_INFO" 2>/dev/null || true)
if [ -n "$INFO_NAME" ]; then
REPO="$INFO_NAME"
fi
INFO_TAG=$(jq -r '."image-tag" // empty' "$IMAGE_INFO" 2>/dev/null || true)
if [ -n "$INFO_TAG" ]; then
IMAGE_TAG="$INFO_TAG"
fi
INFO_FLAVOR=$(jq -r '."image-flavor" // empty' "$IMAGE_INFO" 2>/dev/null || true)
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|IMAGE_VERSION|VERSION_ID)=' "$OS_RELEASE_FILE" 2>/dev/null | head -n1 | cut -d= -f2 | tr -d '"' || true)
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
if curl -sf --retry 3 --max-time 10 -H "User-Agent: ${USER_AGENT}" "$URL" >/dev/null; then
echo "$NOW" > "$LASTRUN_FILE"
fi
Loading