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
6 changes: 5 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ on:
- .github/workflows/release.yml
- scripts/dist.sh
- internal/version/**
- cmd/gfsctl/**
- go.mod
workflow_dispatch:

Expand Down Expand Up @@ -40,12 +41,15 @@ jobs:
- name: Build archives
run: scripts/dist.sh

- name: Check fsck reports the build version
- name: Check fsck and gfsctl report the build version
run: |
tar -xzf dist/goclusterfs_*_linux_amd64.tar.gz -C "$RUNNER_TEMP"
out="$("$RUNNER_TEMP"/goclusterfs_*_linux_amd64/goclusterfs-fsck -version)"
echo "$out"
grep -qF "commit $(git rev-parse HEAD)" <<<"$out"
out="$("$RUNNER_TEMP"/goclusterfs_*_linux_amd64/gfsctl version)"
echo "$out"
grep -qF "$(git rev-parse HEAD)" <<<"$out"

- name: List artifacts
run: |
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
/goclusterfs
/goclusterfs-mount
/goclusterfs-fsck
/gfsctl
/GoClusterFS
/coverage.out

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- Release workflow: pushing a `v*` tag publishes a GitHub Release with `linux/amd64` and `linux/arm64` archives, checksums, and the matching `CHANGELOG.md` section. `scripts/dist.sh` builds the same archives locally.
- `goclusterfs-fsck -version` prints the release version, commit, and commit date.
- HTTP API in `goclusterfs-mount` (`-api`, on by default): `/health`, `/metrics`, `/api/v1/status` and `/api/v1/stats/...`. It listens on `127.0.0.1:8080` (`-api-addr`). Mount refuses a non-loopback `-api-addr` or `-api-cors '*'` without `-api-token`, and checks the API flags before it opens the device. `/metrics` uses the Prometheus client library and adds Go runtime and process metrics. `-api-rate-limit` limits requests per client IP (off by default).
- `gfsctl`, a read-only CLI for the HTTP API: `status`, `health`, `stats`, `metrics`, with watch mode and JSON output. Release archives include it.
- `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: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ FUSE binding: `github.com/hanwen/go-fuse/v2`. Linux only.
## Build and Run

```bash
make build # ./goclusterfs-mount and ./goclusterfs-fsck
make build # ./goclusterfs-mount, ./goclusterfs-fsck and ./gfsctl
go build ./... && go vet ./...
```

Expand All @@ -35,6 +35,7 @@ fusermount3 -u mnt # or Ctrl+C the mo
| `cmd/mount` | `goclusterfs-mount`: fixes the on-disk layout, runs journal recovery, wires all managers, mounts with go-fuse |
| `cmd/fsck` | `goclusterfs-fsck`: 8-phase checker with `-repair` and `-force` modes |
| `cmd/crctest` | Prints CRC32C test values |
| `cmd/gfsctl` | `gfsctl`: read-only CLI for the HTTP API (status, health, stats, metrics) |
| `internal/goclusterfs` | FUSE nodes (`FS` root, `Dir`, `File`) and every VFS operation |
| `internal/storage` | O_DIRECT device, 4 KB aligned buffers, CRC32C |
| `internal/superblock` | Superblock format and the on-disk layout; `-format` writes it, mount reads it |
Expand Down
12 changes: 9 additions & 3 deletions 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 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 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 @@ -14,6 +14,7 @@ GOMOD=$(GOCMD) mod
# Binary names
MOUNT_BINARY=goclusterfs-mount
FSCK_BINARY=goclusterfs-fsck
GFSCTL_BINARY=gfsctl

GOLANGCI_LINT_VERSION=v2.15.0
GOVULNCHECK_VERSION=v1.9.0
Expand All @@ -23,7 +24,7 @@ COVER_PROFILE=coverage.out
.DEFAULT_GOAL := help

# Build all binaries
build: build-mount build-fsck
build: build-mount build-fsck build-gfsctl

build-mount:
@echo "Building $(MOUNT_BINARY)..."
Expand All @@ -35,6 +36,11 @@ build-fsck:
$(GOBUILD) -o $(FSCK_BINARY) ./cmd/fsck
@echo "Built $(FSCK_BINARY) successfully"

build-gfsctl:
@echo "Building $(GFSCTL_BINARY)..."
$(GOBUILD) -o $(GFSCTL_BINARY) ./cmd/gfsctl
@echo "Built $(GFSCTL_BINARY) successfully"

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

Expand Down Expand Up @@ -167,7 +173,7 @@ vuln:
# Utilities
clean:
@echo "Cleaning build artifacts..."
rm -f $(MOUNT_BINARY) $(FSCK_BINARY) $(COVER_PROFILE)
rm -f $(MOUNT_BINARY) $(FSCK_BINARY) $(GFSCTL_BINARY) $(COVER_PROFILE)
rm -f *.img
@echo "Clean complete"

Expand Down
27 changes: 26 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` and `goclusterfs-fsck` in the repo root.
This builds `goclusterfs-mount`, `goclusterfs-fsck` and `gfsctl` in the repo root.

### Format and Mount

Expand Down Expand Up @@ -143,6 +143,31 @@ With `-broadcast` on and no `-broadcast-secret`, mount logs a `WARNING` line at

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

## gfsctl

`gfsctl` reads a mount's HTTP API from the command line. It only reads; it changes nothing. `make build` builds it, and release archives include it.

```bash
./gfsctl status # mount state, version, capacity
./gfsctl health # exits 1 when a component is unhealthy
./gfsctl stats # overview; also: cache, journal, trim, lock, sfb, cluster, all
./gfsctl metrics # Prometheus text from /metrics
./gfsctl status -w -i 5s # refresh every 5 s
./gfsctl stats all -o json # JSON for scripts
```

It connects to `localhost:8080` by default. Each setting comes from the first of: a flag, an environment variable, the config file (`gfsctl config path`; `gfsctl config init` writes a sample with mode 0600), then the default.

| Flag | Environment | Default |
|------|-------------|---------|
| `--host` | `GFSCTL_HOST` | `localhost` |
| `--port` | `GFSCTL_PORT` | `8080` |
| `--token` | `GFSCTL_TOKEN` | (none) |
| `--output`, `-o` | `GFSCTL_OUTPUT` | `text` (or `json`) |
| `--timeout` | `GFSCTL_TIMEOUT` | `30s` |

Use `GFSCTL_TOKEN` or the config file for the token: other local users can read `--token` with `ps`. Statistics answer 503 until mount feeds them to the API, and `gfsctl` prints that error.

## Multi-Node Setup

For clustered deployments:
Expand Down
100 changes: 100 additions & 0 deletions cmd/gfsctl/client/api.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package client

import (
"context"
)

// Health fetches the health status from the API.
func (c *Client) Health(ctx context.Context) (*HealthResponse, error) {
var resp HealthResponse
if err := c.Get(ctx, "/health", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// Status fetches the filesystem status from the API.
func (c *Client) Status(ctx context.Context) (*StatusResponse, error) {
var resp StatusResponse
if err := c.Get(ctx, "/api/v1/status", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// StatsOverview fetches the stats overview from the API.
func (c *Client) StatsOverview(ctx context.Context) (*StatsOverviewResponse, error) {
var resp StatsOverviewResponse
if err := c.Get(ctx, "/api/v1/stats", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// CacheStats fetches cache statistics from the API.
func (c *Client) CacheStats(ctx context.Context) (*CacheStatsResponse, error) {
var resp CacheStatsResponse
if err := c.Get(ctx, "/api/v1/stats/cache", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// JournalStats fetches journal statistics from the API.
func (c *Client) JournalStats(ctx context.Context) (*JournalStatsResponse, error) {
var resp JournalStatsResponse
if err := c.Get(ctx, "/api/v1/stats/journal", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// TrimStats fetches TRIM statistics from the API.
func (c *Client) TrimStats(ctx context.Context) (*TrimStatsResponse, error) {
var resp TrimStatsResponse
if err := c.Get(ctx, "/api/v1/stats/trim", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// LockStats fetches lock statistics from the API.
func (c *Client) LockStats(ctx context.Context) (*LockStatsResponse, error) {
var resp LockStatsResponse
if err := c.Get(ctx, "/api/v1/stats/lock", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// SFBStats fetches SFB (Sub-File Block) statistics from the API.
func (c *Client) SFBStats(ctx context.Context) (*SFBStatsResponse, error) {
var resp SFBStatsResponse
if err := c.Get(ctx, "/api/v1/stats/sfb", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// AllStats fetches all statistics from the API.
func (c *Client) AllStats(ctx context.Context) (*AllStatsResponse, error) {
var resp AllStatsResponse
if err := c.Get(ctx, "/api/v1/stats/all", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// ClusterInfo returns cluster membership from /api/v1/stats/cluster.
func (c *Client) ClusterInfo(ctx context.Context) (*ClusterInfoResponse, error) {
var resp ClusterInfoResponse
if err := c.Get(ctx, "/api/v1/stats/cluster", &resp); err != nil {
return nil, err
}
return &resp, nil
}

// Metrics returns the Prometheus text from /metrics.
func (c *Client) Metrics(ctx context.Context) ([]byte, error) {
return c.GetRaw(ctx, "/metrics")
}
Loading
Loading