Skip to content
Merged
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
29 changes: 29 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ permissions:
env:
GO_VERSION: "1.26"
GOLANGCI_LINT_VERSION: v2.15.0
# Exact release, at least 48 hours old when pinned (company package-age policy).
NODE_VERSION: "22.23.4"

jobs:
build-and-unit-test:
Expand Down Expand Up @@ -113,6 +115,33 @@ jobs:
- name: Run govulncheck
run: make vuln

dashboard:
name: Dashboard
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ env.NODE_VERSION }}
cache: npm
cache-dependency-path: web/dashboard/package-lock.json

- name: Set up Go
uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
with:
go-version: ${{ env.GO_VERSION }}
check-latest: true
cache: true

- name: Install, lint, typecheck and build
run: make dashboard

- name: Check the build embeds and serves
run: go test -v -run 'TestEmbeddedBuild|TestServesBuild' ./internal/webui/

integration-tests:
name: Integration Tests
runs-on: ubuntu-latest
Expand Down
21 changes: 21 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ on:
- .github/workflows/release.yml
- scripts/dist.sh
- internal/version/**
- internal/webui/**
- cmd/gfsctl/**
- web/dashboard/**
- go.mod
workflow_dispatch:

Expand All @@ -18,6 +20,8 @@ permissions:

env:
GO_VERSION: "1.26"
# Exact release, at least 48 hours old when pinned (company package-age policy).
NODE_VERSION: "22.23.4"

jobs:
build:
Expand All @@ -38,6 +42,14 @@ jobs:
check-latest: true
cache: false

- name: Set up Node
uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: ${{ env.NODE_VERSION }}

- name: Build the dashboard
run: make dashboard

- name: Build archives
run: scripts/dist.sh

Expand All @@ -51,6 +63,15 @@ jobs:
echo "$out"
grep -qF "$(git rev-parse HEAD)" <<<"$out"

- name: Check goclusterfs-mount embeds the dashboard
run: |
mount="$(echo "$RUNNER_TEMP"/goclusterfs_*_linux_amd64/goclusterfs-mount)"
if ! grep -qF 'src="/ui/assets/' "$mount"; then
echo "::error::goclusterfs-mount has no dashboard build, only the placeholder"
exit 1
fi
ls "$RUNNER_TEMP"/goclusterfs_*_linux_amd64/licenses/npm/react

- name: List artifacts
run: |
for f in dist/*.tar.gz; do
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- `-api-token-file` (mode 0600 or stricter) and `GOCLUSTERFS_API_TOKEN` for the API token. Mount warns when it comes from `-api-token`, which `ps` shows to every local user.
- HTTP API write endpoints, only with a token: create, list, clone and delete snapshots, clone files, and flush the journal, flush TRIM or clear caches on this node. Snapshot and clone requests call `setxattr` through the mount, like `setfattr`.
- `gfsctl`, a read-only CLI for the HTTP API: `status`, `health`, `stats`, `metrics`, with watch mode and JSON output. Release archives include it.
- Web dashboard at `/ui/` on the API server (`-dashboard`, on by default): status, capacity, cache, journal, TRIM and lock counters, the node registry, and per-file snapshots and clones. Release archives include it; `make dashboard build` builds it from source.
- `goclusterfs-mount -version`, which prints the same version string as `goclusterfs-fsck -version`. `/api/v1/status` reports it too.
- Mount logs a `WARNING` line at startup when `-broadcast` is on without `-broadcast-secret`.
- Design, deployment, operations, and troubleshooting docs in `docs/`.
Expand Down
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ FUSE binding: `github.com/hanwen/go-fuse/v2`. Linux only.

```bash
make build # ./goclusterfs-mount, ./goclusterfs-fsck and ./gfsctl
make dashboard build # same, with the web dashboard embedded (needs Node 22 and npm)
go build ./... && go vet ./...
```

Expand Down Expand Up @@ -57,6 +58,8 @@ fusermount3 -u mnt # or Ctrl+C the mo
| `internal/api` | HTTP API served by `cmd/mount`: `/health`, `/metrics`, `/api/v1/status`, `/api/v1/stats/...`; loopback only unless `-api-token` is set |
| `internal/stats` | Background sampler that feeds `/api/v1/stats/...`, `/metrics` and the capacity in `/api/v1/status` |
| `internal/version` | Build version, set with `-ldflags -X` by `scripts/dist.sh` |
| `internal/webui` | Serves the web dashboard under `/ui/`; embeds `make dashboard`'s build, or a placeholder page |
| `web/dashboard` | React dashboard source (Vite, npm); `make dashboard` builds it into `internal/webui/build/dist` |

## On-Disk Layout

Expand Down
14 changes: 13 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# GoClusterFS Makefile
# Build and test automation for the distributed filesystem

.PHONY: build build-mount build-fsck build-gfsctl test test-unit test-integration test-all test-parity test-multinode-docker docker-build-test docker-clean-test test-multinode-vm vm-clean clean fmt vet check-fuse check-qemu lint vuln help
.PHONY: build build-mount build-fsck build-gfsctl dashboard test test-unit test-integration test-all test-parity test-multinode-docker docker-build-test docker-clean-test test-multinode-vm vm-clean clean fmt vet check-fuse check-qemu lint vuln help

# Go parameters
GOCMD=go
Expand All @@ -16,6 +16,9 @@ MOUNT_BINARY=goclusterfs-mount
FSCK_BINARY=goclusterfs-fsck
GFSCTL_BINARY=gfsctl

DASHBOARD_DIR=web/dashboard
DASHBOARD_DIST=internal/webui/build/dist

GOLANGCI_LINT_VERSION=v2.15.0
GOVULNCHECK_VERSION=v1.9.0
COVER_PROFILE=coverage.out
Expand All @@ -41,6 +44,12 @@ build-gfsctl:
$(GOBUILD) -o $(GFSCTL_BINARY) ./cmd/gfsctl
@echo "Built $(GFSCTL_BINARY) successfully"

# Builds the web dashboard into $(DASHBOARD_DIST), which goclusterfs-mount embeds; run before build
dashboard:
@echo "Building the web dashboard..."
cd $(DASHBOARD_DIR) && npm ci && npm run lint && npm run build
@echo "Built the dashboard into $(DASHBOARD_DIST)"

# Unit tests (fast, no FUSE needed)
test: test-unit

Expand Down Expand Up @@ -174,6 +183,7 @@ vuln:
clean:
@echo "Cleaning build artifacts..."
rm -f $(MOUNT_BINARY) $(FSCK_BINARY) $(GFSCTL_BINARY) $(COVER_PROFILE)
rm -rf $(DASHBOARD_DIST)
rm -f *.img
@echo "Clean complete"

Expand All @@ -200,6 +210,8 @@ help:
@echo " build - Build all binaries"
@echo " build-mount - Build goclusterfs-mount binary"
@echo " build-fsck - Build goclusterfs-fsck binary"
@echo " build-gfsctl - Build gfsctl binary"
@echo " dashboard - Build the web dashboard (npm ci) for build to embed; run make dashboard build"
@echo ""
@echo " Test:"
@echo " test - Run unit tests (alias for test-unit)"
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ cd GoClusterFS
make build
```

This builds `goclusterfs-mount`, `goclusterfs-fsck` and `gfsctl` in the repo root.
This builds `goclusterfs-mount`, `goclusterfs-fsck` and `gfsctl` in the repo root. To include the web dashboard, run `make dashboard build` instead; it needs Node 22 and npm. Release archives include it.

### Format and Mount

Expand Down Expand Up @@ -142,6 +142,7 @@ With `-broadcast` on, the mount fails if it cannot bind both UDP ports; pass `-b
| `-api-token` | (empty) | The token on the command line; visible to all local users in `ps` |
| `-api-cors` | (empty) | Comma-separated CORS allowed origins |
| `-api-rate-limit` | `0` (off) | Requests per second per client IP, with bursts of twice that |
| `-dashboard` | `true` | Serve the web dashboard at `http://<api-addr>/ui/` |

The API only listens on this host by default. Mount refuses to start when `-api-addr` can be reached from other hosts and no token is set. See [HTTP API Flags](docs/API-CONFIG.md#http-api-flags).

Expand Down
10 changes: 10 additions & 0 deletions cmd/mount/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ import (
"github.com/supporttools/GoClusterFS/internal/superblock"
"github.com/supporttools/GoClusterFS/internal/trim"
"github.com/supporttools/GoClusterFS/internal/version"
"github.com/supporttools/GoClusterFS/internal/webui"
)

type fsStatusProvider struct {
Expand Down Expand Up @@ -115,6 +116,7 @@ func main() {
apiToken = flag.String("api-token", "", "API bearer token; visible to all local users in ps, prefer -api-token-file")
apiCORS = flag.String("api-cors", "", "Comma-separated CORS allowed origins (empty=disabled)")
apiRate = flag.Float64("api-rate-limit", 0, "API requests per second per client IP, with bursts of twice that (0=off)")
dashboard = flag.Bool("dashboard", true, "Serve the web dashboard on the API server under /ui/")
)
flag.Parse()

Expand All @@ -137,6 +139,9 @@ func main() {
log.Printf("WARNING: -api-token is visible to every local user in ps and /proc/<pid>/cmdline, and it unlocks API writes. Use -api-token-file or %s instead.", apiTokenEnv)
}
apiCfg := apiConfig(*apiAddr, token, *apiCORS, *apiRate)
if *dashboard {
apiCfg.Dashboard = webui.Handler()
}
if *apiEnabled {
if err := apiCfg.Validate(); err != nil {
log.Fatalf("Invalid API settings: %v", err)
Expand Down Expand Up @@ -461,6 +466,11 @@ func main() {
if !apiServer.WritesEnabled() {
log.Printf("API: snapshot, clone and admin endpoints are off; set -api-token-file or %s to turn them on", apiTokenEnv)
}
if apiCfg.Dashboard != nil && webui.Built() {
log.Printf("API: dashboard at /ui/")
} else if apiCfg.Dashboard != nil {
log.Printf("API: this binary has no dashboard build; /ui/ explains how to add it")
}
}
}
} else {
Expand Down
15 changes: 12 additions & 3 deletions docs/API-CONFIG.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,16 +94,17 @@ The kernel caches file attributes and directory entries for `-attr-timeout`. For
| `-api-token` | string | (empty) | The token on the command line. Every local user can read it with `ps`; mount logs a `WARNING` |
| `-api-cors` | string | (empty) | Comma-separated CORS allowed origins, or `*` |
| `-api-rate-limit` | float | `0` (off) | Requests per second per client IP, with bursts of twice that, up to 1,000,000. Over the limit, the API answers 429 |
| `-dashboard` | bool | `true` | Serve the [web dashboard](#web-dashboard) under `/ui/` |

The API serves `GET /health`, `GET /metrics`, `GET /api/v1/status`, `GET /api/v1/stats/...` and, with `-api-token`, the [write endpoints](#http-api-write-endpoints). [HTTP API Statistics](#http-api-statistics) lists what `/metrics`, `/api/v1/status` and `/api/v1/stats/...` return. `/health` only checks the API itself. With `-api-token` set, `/api/v1/...` requests need `Authorization: Bearer <token>`. `/health` and `/metrics` never need the token.
The API serves `GET /health`, `GET /metrics`, `GET /api/v1/status`, `GET /api/v1/stats/...`, the [web dashboard](#web-dashboard) under `/ui/` and, with `-api-token`, the [write endpoints](#http-api-write-endpoints). [HTTP API Statistics](#http-api-statistics) lists what `/metrics`, `/api/v1/status` and `/api/v1/stats/...` return. `/health` only checks the API itself. With `-api-token` set, `/api/v1/...` requests need `Authorization: Bearer <token>`. `/health`, `/metrics` and the dashboard's files under `/ui/` never need the token.

Without `-api-token`, the API answers only requests whose `Host` header is `localhost`, a `127.x` address or `[::1]`, so a web page cannot reach it through DNS rebinding, and mount refuses `-api-cors '*'`. List the dashboard's origin instead, for example `-api-cors http://localhost:5173`.
Without `-api-token`, the API answers only requests whose `Host` header is `localhost`, a `127.x` address or `[::1]`, so a web page cannot reach it through DNS rebinding, and mount refuses `-api-cors '*'`. List the allowed origins instead. The dashboard at `/ui/` shares the API's origin and needs no CORS.

By default the API only accepts connections from this host. To serve other hosts, set `-api-addr` (for example `:8080` or `10.0.0.5:8080`) and `-api-token-file`. Mount exits before it opens the device when the address is not loopback (`127.0.0.0/8`, `::1` or `localhost`) and the token is empty.

Give the token with `-api-token-file` or the `GOCLUSTERFS_API_TOKEN` environment variable, and set only one of them. Mount refuses a token file that group or others can read. `-api-token` still works, but `ps` and `/proc/<pid>/cmdline` show it to every local user, and with it they could change any file's snapshots through the API. The API uses plain HTTP, so a token sent to another host crosses the network unencrypted: put a TLS proxy in front of the API, or reach it over an SSH tunnel (`ssh -L 8080:127.0.0.1:8080 node`).

The rate limit counts requests per connecting IP address, and per /64 for IPv6. It ignores `X-Forwarded-For`, so behind a proxy every client shares the proxy's limit. `/health` and `/metrics` are never limited. The limiter tracks at most 65,536 clients at once; while it is full, new clients get 429 until idle clients' buckets refill and are dropped, about 2 seconds (longer below 0.5 requests per second).
The rate limit counts requests per connecting IP address, and per /64 for IPv6. It ignores `X-Forwarded-For`, so behind a proxy every client shares the proxy's limit. `/health`, `/metrics` and `/ui/` are never limited. The limiter tracks at most 65,536 clients at once; while it is full, new clients get 429 until idle clients' buckets refill and are dropped, about 2 seconds (longer below 0.5 requests per second).

Each mount on a host needs its own `-api-addr`. When the port is taken, mount logs a warning and runs without the API.

Expand All @@ -130,6 +131,14 @@ Errors answer with `{error, code, details}`: 400 for a bad path, name, destinati

Mount logs each write at INFO with the client address, the action, its arguments and the result. On shutdown, mount stops taking requests, waits for writes in flight to finish, and only then unmounts.

### Web Dashboard

Mount serves a web dashboard at `http://<api-addr>/ui/`, unless `-dashboard=false`. It shows status, capacity, the cache, journal, TRIM and lock counters, and the nodes in the registry. It lists snapshots, and for a file you name it creates, clones and deletes them and clones the file. Its Settings page runs the admin endpoints.

The dashboard's files are static and hold no data, so they need no token and skip the rate limit. The page calls `/api/v1/...` on the same origin with the same rules as any client: reads need the token when one is set, and snapshots always need it. Enter the token on the dashboard's Settings page. The browser keeps it in `sessionStorage`, so closing the tab forgets it. Responses carry a `Content-Security-Policy` that lets the page load and call only its own origin and stops other sites from framing it.

Release archives include the dashboard. `go build` and `make build` alone embed a page that says to run `make dashboard build`; `make dashboard` needs Node 22 and npm, and installs the exact packages in `web/dashboard/package-lock.json` with `npm ci`.

---

## HTTP API Statistics
Expand Down
4 changes: 4 additions & 0 deletions internal/api/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package api
import (
"fmt"
"net"
"net/http"
"net/url"
"slices"
"strings"
Expand Down Expand Up @@ -56,6 +57,9 @@ type Config struct {
// RateLimitBurst is the maximum burst size (token bucket capacity).
// Default: 200
RateLimitBurst int

// Dashboard, if set, serves the web dashboard under /ui/ without auth or rate limiting.
Dashboard http.Handler
}

// DefaultConfig returns a Config with sensible defaults.
Expand Down
85 changes: 85 additions & 0 deletions internal/api/dashboard_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
package api

import (
"net/http"
"testing"
)

func dashboardConfig() Config {
cfg := DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret")
cfg.Dashboard = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-Dashboard-Path", r.URL.Path)
})
return cfg
}

func TestExempt(t *testing.T) {
paths := []string{"/health", "/metrics", "/ui/"}
for p, want := range map[string]bool{
"/health": true,
"/metrics": true,
"/ui": true,
"/ui/": true,
"/ui/assets/a.js": true,
"/ui/snapshots": true,
"/health/x": false,
"/healthz": false,
"/uix": false,
"/ui/../api/v1/status": false,
"/ui/./../metrics/x": false,
"/api/v1/status": false,
} {
if got := exempt(p, paths); got != want {
t.Errorf("exempt(%q) = %v, want %v", p, got, want)
}
}
}

func TestDashboardNeedsNoToken(t *testing.T) {
srv := startServer(t, dashboardConfig())
for path, want := range map[string]string{
"/ui": "/",
"/ui/": "/",
"/ui/assets/a.js": "/assets/a.js",
"/ui/snapshots": "/snapshots",
} {
resp := get(t, srv, path, "", nil)
if resp.StatusCode != http.StatusOK || resp.Header.Get("X-Dashboard-Path") != want {
t.Errorf("%s: status %d, dashboard saw %q; want 200 and %q", path, resp.StatusCode, resp.Header.Get("X-Dashboard-Path"), want)
}
}
for _, path := range []string{"/ui/../api/v1/status", "/ui/%2e%2e/api/v1/status", "/uix", "/api/v1/status"} {
if got := get(t, srv, path, "", nil).StatusCode; got != http.StatusUnauthorized {
t.Errorf("%s without token: status %d, want 401", path, got)
}
}
}

func TestDashboardSkipsRateLimit(t *testing.T) {
srv := startServer(t, dashboardConfig().WithRateLimit(0.25, 1))
for i := 0; i < 5; i++ {
if got := get(t, srv, "/ui/assets/a.js", "", nil).StatusCode; got != http.StatusOK {
t.Fatalf("request %d: status %d, want 200", i+1, got)
}
}
}

func TestNoDashboardMeansNoUIRoute(t *testing.T) {
cfg := DefaultConfig().WithListenAddr("127.0.0.1:0").WithAuthToken("secret")
srv := startServer(t, cfg)
if got := get(t, srv, "/ui/", "", nil).StatusCode; got != http.StatusUnauthorized {
t.Errorf("/ui/ without token: status %d, want 401", got)
}
auth := map[string]string{"Authorization": "Bearer secret"}
if got := get(t, srv, "/ui/", "", auth).StatusCode; got != http.StatusNotFound {
t.Errorf("/ui/ with token: status %d, want 404", got)
}
}

func TestDashboardKeepsLoopbackHostCheck(t *testing.T) {
cfg := dashboardConfig().WithAuthToken("")
srv := startServer(t, cfg)
if got := get(t, srv, "/ui/", "evil.example", nil).StatusCode; got != http.StatusForbidden {
t.Errorf("/ui/ with a foreign Host: status %d, want 403", got)
}
}
Loading
Loading