Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
452e71e
CLAUDE.md
spoulson May 20, 2026
aa970c3
Initial implementation
spoulson May 20, 2026
1ef0b1b
Use github.com/bougou/go-ipmi library
spoulson May 20, 2026
aff66be
Dry run mode
spoulson May 25, 2026
329ea39
Adjust logs
spoulson May 25, 2026
ffb518c
Rename device terminology to sensor
spoulson May 27, 2026
4af2694
Code fixes with interval handling
spoulson May 27, 2026
af26302
Propagate context to IPMI operations for clean shutdown
spoulson May 27, 2026
2ea28de
Skip fan speed apply when no new suggestions have arrived
spoulson May 27, 2026
1be00e9
Extract logFanSpeeds closure to named function
spoulson May 27, 2026
55aace6
Move main loop to service.go, leaving main() as bootstrap only
spoulson May 27, 2026
ec771f3
Fix set speed bug
spoulson May 27, 2026
ec417af
Sensor readings keyed by ID; fan log reverts to per-fan lines
spoulson May 27, 2026
acb4381
Tidy code
spoulson May 27, 2026
159e5d1
Add --version flag to print version and exit
spoulson May 27, 2026
fbd58ed
Tidy code
spoulson May 27, 2026
db01ab6
Add "make lint" target to call golangci-lint
spoulson May 27, 2026
c092d66
Fix lint errors
spoulson May 27, 2026
dc6ba18
Add GitHub Actions lint workflow using golangci-lint-action v9
spoulson May 27, 2026
8d83433
Add GitHub Actions test workflow
spoulson May 27, 2026
60bd8a4
Enable race detector in test workflow
spoulson May 27, 2026
18e93f1
Add uninstall_clean target; preserve config on reinstall
spoulson May 27, 2026
2d472c7
Add logrotate config; include in install and package targets
spoulson May 27, 2026
df7ddf2
Update .gitignore
spoulson May 27, 2026
16ae9ba
Combine lint and test into single Verification workflow
spoulson May 27, 2026
b88f2da
Rename workflow to "Verify"
spoulson May 27, 2026
104eaee
Use max sensor reading per poll; add configurable JSON log format
spoulson May 27, 2026
ba13db6
Deduplicate CPU sensor names with suffix starting at _2
spoulson May 27, 2026
e81ec7a
Deduplicate GPU sensor names with suffix starting at _2
spoulson May 27, 2026
f17eb04
Update README with description, build/install instructions, and confi…
spoulson May 27, 2026
0dcb87d
Update README.md
spoulson May 28, 2026
10b7694
Add Prometheus metrics HTTP server.
spoulson Jun 1, 2026
fe9da9e
Refine Prometheus metric names and GPU sensor ID
spoulson Jun 1, 2026
f5d6f99
Track per-sensor-ID rolling aggregates for fan speed
spoulson Jun 1, 2026
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
14 changes: 14 additions & 0 deletions .claude/settings.local.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"permissions": {
"allow": [
"Bash(git -C /home/spoulson/src/frostd log --oneline)",
"Bash(git *)",
"Bash(go version *)",
"Bash(go get *)",
"Bash(chmod +x *)",
"Bash(go build *)",
"Bash(go test *)",
"Bash(go mod *)"
]
}
}
35 changes: 35 additions & 0 deletions .github/workflows/verify.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
name: Verify

on:
push:
branches: [main]
pull_request:
branches: [main]

env:
GOLANGCI_LINT_VERSION: v2.11.4

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-go@v5
with:
go-version-file: go.mod

- uses: golangci/golangci-lint-action@v9
with:
version: ${{ env.GOLANGCI_LINT_VERSION }}

test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-go@v5
with:
go-version-file: go.mod

- run: go test -race ./...
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
/frostd
/bin
frostd*.deb
206 changes: 206 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.

## Project

`frostd` is a daemon that dynamically regulates fan speeds on Dell PowerEdge
servers based on hardware temperature metrics.

`frostd` supports Dell PowerEdge 12th generation servers, such as R720.

`frostd` identifies supported devices and actively monitors metrics and adjusts
chassis fan speed using IPMI.

## Sensor Metrics

Devices are grouped by sensor type. Each sensor type has zero or more sensor
IDs.

### CPU Sensor Metrics

`frostd` uses IPMI to read CPU temperatures of each package. Each package is
listed as a sensor ID.

### NVIDIA Tesla P40 GPU Sensor Metrics

`frostd` supports monitoring of an optional NVIDIA Tesla P40 GPU. frostd uses
`nvidia-smi` command to read GPU temperature.

#### System Prerequisites

- Compatible NVIDIA driver installed
- Compatible Cuda driver installed
- This installs the `nvidia-smi` command

## Fan Speed Control

frostd computes a suggested fan speed in range [0,100] based on configurable
ideal and maximum device temperatures and an easing formula.

### Suggestion Algorithm

For each sensor type, read the temperature and compute aggregate temperature
metric from average of last _n_ samples.

The default easing type is "parabolic". Compute the suggested fan speed for
each device with the following pseudocode formula:

```
suggested_speed = min(
max_speed,
(actual_temp - ideal_temp)^2 * (max_temp/((max_temp - ideal_temp)^2))
)
```

Design assumptions:
- Temperature unit is Celcius.
- `max_speed` = 100.
- `max_temp` is the upper bound temperature at which fans will be run at
highest speed.
- `ideal_temp` is the lower bound temperature at which fans will be run at
lowest speed.
- `max_temp` and `ideal_temp` are configured per device.
- `actual_temp` is the sensor aggregate temperature metric.
- Set fan speed to the max `suggested_speed` computed from all devices. This
ensures adequate airflow for the device that needs it most.

## Configuration

frostd reads a YAML config file in the default path `/etc/frostd.yaml` or
overridden by specifying CLI argument `-c <file>`.

The YAML config specifies which sensor types to monitor: CPU and/or NVIDIA
Tesla P40 GPU. Each sensor type includes settings for:
- ideal temperature in Celcius (Default 40)
- maximum temperature in Celcius (Default 75)
- sample size (Default 3)
- sample time interval (Default 15s)

All instances of a sensor type will be discovered (e.g. multiple CPU packages,
multiple GPUs).

Log file output file is specified (Default `/var/log/frostd/frostd.log`).

Dry run mode is enabled with `dry_run: true` (Default `false`). When enabled,
frostd monitors temperature metrics and logs suggested fan speeds but does not
issue any fan speed changes via IPMI. Useful for observing behavior without
affecting hardware.

## Technology Stack

`frostd` is written in Golang and compiled to standalone executable file to be
run on Debian or Ubuntu Linux on x86-64 architecture. The executable runs as a
systemd service.

## Developer Prerequisites

- Debian or Ubuntu Linux OS on x86-64 architecture
- Golang 1.26+ installed
- `make` installed

## Software Design

### Technology Stack

- `frostd` is a systemd service written in latest Golang.
- It must be run on a Dell PowerEdge 12th generation server.

### Tooling

- Use `slog` package for logging.
- Use module `github.com/bougou/go-ipmi` for IPMI support. Do not depend on
the commonly used `ipmitool` command.

### Service Lifecycle

Service starts up by parsing and validating the configuration file.

Then, the service runs in a loop. On each iteration:
- Polls temperature metrics
- Compute suggested fan speed
- Set chassis fan speed
- Sleep until next interval
- Sleep to incremental times, not static durations. This ensures loops occur
on steady cadence even if one iteration takes a bit longer to process.

The service immediately and gracefully stops when requested with command:
`systemctl stop frostd`.

### Tests

Tests are required to confirm requirements and prevent regressions during code
maintenance.

Use module `github.com/stretchr/testify` for `assert` and `require` packages
for simplifying assertions and validation logic.

End-to-end tests are required for functionality:
- Configuration parsing
- YAML file structure
- Validation for each field with happy path, numeric range errors, and likely special case checks
- Computing aggregate temperature metrics
- Computing suggested fan speeds from mock temperature samples
- Reading actual CPU temperature metrics
- Reading actual NVIDIA GPU temperature metrics using `nvidia-smi`

### Error Handling

#### Startup

On startup, validate configuration. If configuration file cannot be parsed or
contains validation errors, log a descriptive error message and exit.

#### Runtime

If there are errors reading temperature metrics, log a descriptive error and
retry on next iteration.

Log all sensor temperature metrics, computed aggregate metrics, and suggested
fan speed.

If there are errors setting fan speed, log a descriptive error. Retry on the
next iteration when fan speed is suggested again.

## Launch From Source

The repository will provide a `make run` target that will:
- Call `go run` to launch the service using the configuration file `dev.yaml`.
- `dev.yaml` is a copy of the default configuration file used for installing
`/etc/frostd.yaml`.
- Log output goes to stdout instead of a log file.

## Software Package Installation

The repository will provide a `make package` target that will:
- Build the executable
- Build a Debian .deb package that can be installed with `apt install` on
Debian and Ubuntu Linux OS

The package includes the compiled executable, default configuration for
`/etc/frostd.yaml`, and systemd service configuration.

The package installation script steps:
- Copy executable to `/usr/local/bin`
- Copy default config file to `/etc/frostd.yaml`
- Add systemd configuration for `frostd` service
- Start `frostd` service

## Code Style

### Makefile

Use `.PHONY` directives to indicate a target is a descriptive script name and
not a literal filename. Place the directive on the line before its definition,
not as a single directive for all targets. This helps prevent forgetting to
update the list.

### Golang

Write code for latest Golang version. Follow Golang's current standards of code
style and best practices as outlined in Effective Go by Google.

## License

License: Apache 2.0
50 changes: 50 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
BINARY = frostd
GOLANGCI_LINT = ./bin/golangci-lint
GOLANGCI_LINT_VERSION = v2.11.4

.PHONY: build
build:
go build -o $(BINARY) .

.PHONY: run
run:
go run . -c dev.yaml

.PHONY: test
test:
go test -race ./...

$(GOLANGCI_LINT):
curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b ./bin $(GOLANGCI_LINT_VERSION)

.PHONY: lint
lint: $(GOLANGCI_LINT)
$(GOLANGCI_LINT) run

.PHONY: install
install: build
test -f /etc/frostd.yaml || sudo cp frostd.yaml /etc/frostd.yaml
sudo cp packaging/frostd.logrotate /etc/logrotate.d/frostd
sudo sed "s|ExecStart=.*|ExecStart=$(CURDIR)/$(BINARY)|" \
packaging/frostd.service \
| sudo tee /etc/systemd/system/frostd.service > /dev/null
sudo systemctl daemon-reload
sudo systemctl enable frostd
sudo systemctl start frostd

.PHONY: uninstall
uninstall:
sudo systemctl stop frostd || true
sudo systemctl disable frostd || true
sudo rm -f /etc/systemd/system/frostd.service
sudo systemctl daemon-reload

.PHONY: uninstall_clean
uninstall_clean: uninstall
LOG_FILE=$$(awk '/^log_file:/{print $$2}' /etc/frostd.yaml 2>/dev/null); \
sudo rm -f /etc/frostd.yaml; \
if [ -n "$$LOG_FILE" ]; then sudo rm -f "$$LOG_FILE"; fi

.PHONY: package
package: build
packaging/build-deb.sh
Loading
Loading