siphon

README

Keyboard-driven Terminal UI for Ceph, inspired by k9s.

[!NOTE] Siphon was previously named Argonaut — renamed to avoid confusion with Ceph's own Argonaut release.

Stop memorizing long ceph commands. Browse your cluster, inspect resources, and perform common operational tasks through a fast, intuitive terminal interface.

Siphon replaces repetitive Ceph CLI workflows with an interactive terminal interface while staying transparent: every action shows the underlying Ceph operation, and destructive changes always require confirmation.

---

Why Siphon?

Ceph ships an excellent CLI — but many operational workflows mean long command sequences, remembering exact flags, or juggling several terminal windows.

Siphon gives you:

• Fast keyboard navigation across every resource
• Safe destructive actions — always confirmed, never a surprise
• Real-time cluster visibility — health, capacity, IO and recovery at a glance
• Transparent execution — every action previews the exact ceph command it runs

---

Features

• Dashboard — health (with a scrollable ceph health detail), capacity (cluster-wide plus the fullest pools), client IO and recovery, refreshed live.
• OSDs — mark in/out, reweight, destroy/purge/remove, metadata and utilisation; sort by id, reweight, %use, pgs or size.
• Pools — create, edit (size/min_size/PG/autoscale/rule), delete; browse and sort by pg_num, %used, stored or objects, with per-pool usage shown.
• CRUSH — interactive hierarchy tree; move buckets, view rules.
• Cluster flags — view/toggle with descriptions, rationale and risks.
• Services — cephadm services and daemons; restart, start, stop. On non-cephadm clusters (Rook, manual) it detects this and shows a read-only daemon inventory (ceph node ls) instead of failing.
• Placement groups — cluster-wide listing, live filter, sort by objects, scrub / deep-scrub / repair.
• Consistent UX — / filters any table, : command prompt, and y/n confirmations that always preview the equivalent ceph command.

---

Installation

Siphon manages a real cluster through librados (via go-ceph + cgo), so it runs on Linux. See Requirements for the full support matrix.

Download a prebuilt binary (recommended)

Prebuilt linux/amd64 and linux/arm64 binaries are attached to each GitHub Release. Install the Ceph client runtime libraries first:

# Debian/Ubuntu
sudo apt-get install -y librados2 librbd1
# RHEL/Rocky/Alma/Fedora
sudo dnf install -y librados2 librbd1

Then download, verify and install the binary (replace v0.6.0 with the latest release; ARCH picks amd64 or arm64):

VERSION=v0.6.0
ARCH=amd64            # or arm64
BASE="https://github.com/cinpol/siphon/releases/download/$VERSION"

curl -LO "$BASE/siphon_${VERSION#v}_linux_${ARCH}.tar.gz"
curl -LO "$BASE/checksums.txt"

# Verify the download
sha256sum --ignore-missing -c checksums.txt

# Extract and install
tar xzf "siphon_${VERSION#v}_linux_${ARCH}.tar.gz"
sudo install -m 0755 siphon /usr/local/bin/siphon

siphon --version
sudo siphon          # --client auto

Other package channels (Homebrew, deb/rpm) are planned for later releases — until then, other platforms build from source.

Build from source

Install the build packages (see Requirements), then:

git clone https://github.com/cinpol/siphon.git
cd siphon
make build
sudo ./bin/siphon          # --client auto

sudo (or another user that can read the admin keyring) lets librados authenticate the way the ceph CLI does.

Run in a container

A prebuilt, multi-arch image (linux/amd64 + linux/arm64, with the Ceph client libraries bundled) is on Docker Hub:

docker run --rm -it -v /etc/ceph:/etc/ceph:ro docker.io/cinpol/siphon

Docker pulls the right architecture automatically, so on an Apple Silicon Mac the image runs natively (no emulation). Works against any cluster the container can reach. See docs/docker.md, and for Kubernetes docs/kubernetes.md (any cluster) or docs/rook.md (Rook-Ceph).

Try it without a cluster

Build the pure-Go binary that talks only to an in-memory mock — works on any OS, no Ceph required:

make build-mock
./bin/siphon-mock --client mock

---

Requirements

Platforms

Platform	Status	Notes
Linux amd64	✅	Prebuilt binaries; the primary tested target.
Linux arm64	✅	Prebuilt binaries; the container image is multi-arch too.
macOS / Windows	❌	librados is not available natively; only the mock client runs, for development/demos. On Apple Silicon the multi-arch container image runs natively — use it to reach a real cluster.

Ceph releases

Siphon targets the currently maintained Ceph releases:

Release	Major
Reef	18
Squid	19
Tentacle	20

Linux distributions

Build-tested in CI against Ubuntu 22.04 / 24.04, Debian 12 / 13 and AlmaLinux 9 (which also covers binary-compatible RHEL / Rocky 9). Any distribution shipping a supported Ceph client release should work; the constraint is the Ceph client version, not the distro itself.

System packages

To run a prebuilt binary you need the Ceph client shared libraries; to build from source you also need the development headers, a C compiler and pkg-config:

Distro family	Runtime	Build
Debian / Ubuntu	librados2 librbd1	librados-dev librbd-dev gcc pkg-config
RHEL / Rocky / Alma / Fedora	librados2 librbd1	librados-devel librbd-devel gcc pkgconf-pkg-config

Building from source also needs Go 1.26+.

Cluster access

Siphon authenticates exactly like the ceph CLI: it needs a reachable cluster with a valid ceph.conf and a client keyring. If ceph -s works from the host (as the user running Siphon), Siphon will connect too.

---

Usage

siphon [flags]

Flag	Default	Description
--client	auto	auto | mock | goceph
--ceph-conf	(librados default)	Path to ceph.conf, overriding app config
--version		Print version information and exit

--client auto uses the native go-ceph transport and errors with guidance if librados is unavailable — it never silently shows mock data. Use --client mock to explicitly run against the built-in demo cluster.

Keys

• 1–7 — switch views; : — command prompt (e.g. :osd)
• / — filter the current table live
• ⇧+column — sort a table by that column; press again to reverse. Pools: ⇧N/P/U/S/O (name/pg_num/%used/stored/objects); OSDs: ⇧I/R/U/P/S (id/reweight/%use/pgs/size); PGs: ⇧O (objects)
• Enter — details for the selected item; on the Dashboard it opens a scrollable ceph health detail. Context actions use the shortcut keys shown in the header
• Inside the Health-detail overlay: ↑/↓, PgUp/PgDn, g/G scroll; Esc closes
• q — quit

---

Configuration

Optional, loaded from ~/.config/siphon/config.yaml (honours XDG_CONFIG_HOME). Built-in defaults are used when absent.

ceph:
  config_path: ""          # empty = librados default search path
  user: client.admin
ui:
  refresh_seconds: 5
  dashboard_pool_rows: 5   # pools shown on the dashboard (fullest first); rest → Pools view
  # pg_problem_flags:      # PG state flags the "problems only" (u) filter treats as problems.
  #   - inconsistent       # Omit the whole key to use these built-in defaults; setting it
  #   - snaptrim_error     # replaces the list entirely.
  #   - failed_repair
  #   - unfound
  #   - stale

---

Architecture at a glance

Strict separation of concerns; the dependency direction always points inward:

cmd/siphon         entrypoint: wiring only
        │
        ▼
internal/ui          Bubble Tea app (Model/Update/View), views, styles
        │
        ▼
internal/service     business logic & safety/confirmation workflows
        │
        ▼
internal/ceph        Client interface — the ONLY seam to Ceph
   ├── goceph        native librados transport (build tag: goceph)
   ├── mock          in-memory client for dev/tests (no cluster needed)
   └── decode        version-aware parsing of Ceph admin-command JSON
internal/model       transport-agnostic domain types
internal/version     Ceph release matrix + build info
internal/config      app config (XDG YAML)

Only implementations under internal/ceph import a concrete transport (go-ceph). Everything else depends on the ceph.Client interface, which keeps the app testable against the mock and free of any single transport.

---

Status

Siphon is under active development. Implemented so far:

• ✅ Dashboard
• ✅ OSDs
• ✅ Pools
• ✅ CRUSH
• ✅ Cluster flags
• ✅ Services
• ✅ Placement groups

More resources and workflows are on the way, with partial-failure resilience and stale-data handling throughout.

---

Development

make test               # unit + end-to-end (mock) tests
make vet
make fmt

The native go-ceph transport (internal/ceph/goceph) is gated behind the goceph build tag because it requires cgo and librados. The default (untagged) build uses the in-memory mock, so development and CI need no cluster or C libraries.

Contributions are welcome — see CONTRIBUTING.md.

---

Acknowledgements

Siphon is inspired by the excellent work behind k9s, bringing a similar keyboard-driven operational experience to Ceph clusters. It is built on Bubble Tea and go-ceph.

---

License

Licensed under the Apache License 2.0. See NOTICE for attribution and third-party components. Siphon links the Ceph client libraries (librados/librbd, LGPL-2.1) dynamically when built with the goceph tag.