breezed 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. breezed-0.1.0/.github/workflows/ci.yml +15 -0
  2. breezed-0.1.0/.github/workflows/publish.yml +38 -0
  3. breezed-0.1.0/.gitignore +11 -0
  4. breezed-0.1.0/.pre-commit-config.yaml +17 -0
  5. breezed-0.1.0/LICENSE +21 -0
  6. breezed-0.1.0/PKG-INFO +159 -0
  7. breezed-0.1.0/README.md +138 -0
  8. breezed-0.1.0/pyproject.toml +48 -0
  9. breezed-0.1.0/src/breezed/__init__.py +3 -0
  10. breezed-0.1.0/src/breezed/cli.py +471 -0
  11. breezed-0.1.0/src/breezed/config.py +172 -0
  12. breezed-0.1.0/src/breezed/controller.py +182 -0
  13. breezed-0.1.0/src/breezed/curve.py +58 -0
  14. breezed-0.1.0/src/breezed/daemon.py +429 -0
  15. breezed-0.1.0/src/breezed/ipmi.py +134 -0
  16. breezed-0.1.0/src/breezed/logs.py +81 -0
  17. breezed-0.1.0/src/breezed/metrics.py +108 -0
  18. breezed-0.1.0/src/breezed/policy.py +18 -0
  19. breezed-0.1.0/src/breezed/ports.py +35 -0
  20. breezed-0.1.0/src/breezed/templates/breezed.service.template +33 -0
  21. breezed-0.1.0/src/breezed/templates/breezed.toml.example +22 -0
  22. breezed-0.1.0/src/breezed/types.py +64 -0
  23. breezed-0.1.0/src/breezed/watcher.py +47 -0
  24. breezed-0.1.0/tests/fixtures/config_valid.toml +20 -0
  25. breezed-0.1.0/tests/fixtures/sdr_fan.txt +6 -0
  26. breezed-0.1.0/tests/fixtures/sdr_temperature.txt +7 -0
  27. breezed-0.1.0/tests/test_cli.py +502 -0
  28. breezed-0.1.0/tests/test_config.py +278 -0
  29. breezed-0.1.0/tests/test_controller.py +376 -0
  30. breezed-0.1.0/tests/test_curve.py +82 -0
  31. breezed-0.1.0/tests/test_daemon.py +531 -0
  32. breezed-0.1.0/tests/test_ipmi.py +151 -0
  33. breezed-0.1.0/tests/test_logging.py +158 -0
  34. breezed-0.1.0/tests/test_metrics.py +117 -0
  35. breezed-0.1.0/tests/test_types.py +53 -0
  36. breezed-0.1.0/tests/test_version.py +7 -0
  37. breezed-0.1.0/uv.lock +257 -0
@@ -0,0 +1,15 @@
1
+ name: CI
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches: [master]
7
+
8
+ jobs:
9
+ ci:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
13
+ - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0
14
+ - run: uvx pre-commit run --all-files
15
+ - run: uv run pytest
@@ -0,0 +1,38 @@
1
+ name: publish
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v[0-9]+.[0-9]+.[0-9]+*"
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ permissions:
12
+ contents: read
13
+ steps:
14
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
15
+ - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0
16
+ - run: uv build
17
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
18
+ with:
19
+ name: dist
20
+ path: dist/
21
+
22
+ publish:
23
+ needs: build
24
+ runs-on: ubuntu-latest
25
+ environment:
26
+ name: pypi
27
+ url: https://pypi.org/project/breezed/
28
+ permissions:
29
+ id-token: write
30
+ contents: read
31
+ steps:
32
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
33
+ - uses: astral-sh/setup-uv@6b9c6063abd6010835644d4c2e1bef4cf5cd0fca # v6.0
34
+ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
35
+ with:
36
+ name: dist
37
+ path: dist/
38
+ - run: uv publish
@@ -0,0 +1,11 @@
1
+ .python-version
2
+ .venv/
3
+ __pycache__/
4
+ *.py[cod]
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .ty_cache/
8
+ dist/
9
+ build/
10
+ *.egg-info/
11
+ .coverage
@@ -0,0 +1,17 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v6.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-toml
9
+ - repo: https://github.com/astral-sh/ruff-pre-commit
10
+ rev: v0.16.4
11
+ hooks:
12
+ - id: ruff-check
13
+ - id: ruff-format
14
+ - repo: https://github.com/astral-sh/ty-pre-commit
15
+ rev: v0.0.74
16
+ hooks:
17
+ - id: ty
breezed-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Martin Miglio <contact@martinmiglio.dev>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
breezed-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,159 @@
1
+ Metadata-Version: 2.5
2
+ Name: breezed
3
+ Version: 0.1.0
4
+ Summary: Curve-based fan controller for Dell PowerEdge servers via iDRAC/IPMI
5
+ Project-URL: Homepage, https://github.com/martinmiglio/breezed
6
+ Project-URL: Repository, https://github.com/martinmiglio/breezed
7
+ Project-URL: Issues, https://github.com/martinmiglio/breezed/issues
8
+ Author-email: Martin Miglio <contact@martinmiglio.dev>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Operating System :: POSIX :: Linux
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Topic :: System :: Hardware
16
+ Requires-Python: >=3.13
17
+ Requires-Dist: pydantic>=2.13.4
18
+ Requires-Dist: rich>=13
19
+ Requires-Dist: typer>=0.12
20
+ Description-Content-Type: text/markdown
21
+
22
+ # breezed
23
+
24
+ Curve-based fan controller for Dell PowerEdge servers via iDRAC/IPMI.
25
+ Python 3.13 · uv · ruff · ty.
26
+
27
+ Source: [github.com/martinmiglio/breezed](https://github.com/martinmiglio/breezed)
28
+
29
+ breezed is a curve-based fan controller for Dell PowerEdge servers, driving
30
+ iDRAC/IPMI with a multi-point temperature curve and linear interpolation between
31
+ points so homelab racks stay quiet at idle and cool under load. Above the top curve point it hands control back to
32
+ iDRAC's own automatic thermal management — the safety net is always one degree
33
+ away. Logs are JSON on stdout; a Prometheus-format metrics socket is opt-in;
34
+ adapters (IPMI transport) and speed policies (curve today, PID later) sit
35
+ behind small Protocols, so either can be swapped without touching the core.
36
+
37
+ ## Install
38
+
39
+ From PyPI:
40
+
41
+ ```sh
42
+ pip install breezed
43
+ # or
44
+ uv tool install breezed
45
+ ```
46
+
47
+ To deploy as a systemd service (the `breezed` binary needs privileges to talk to
48
+ iDRAC; `daemon install` stages the unit and re-execs under sudo once), run one
49
+ command and enter your password once:
50
+
51
+ ```sh
52
+ breezed daemon install
53
+ ```
54
+
55
+ `daemon install` stages the unit/env/config, then re-executes itself via sudo to
56
+ perform the fixed privileged steps (create the service user, install the runtime
57
+ under `/opt`, write the systemd unit, enable and start the service). Pass
58
+ `--dry-run` to print the steps without escalating. The user-level `uv` only
59
+ invokes breezed from the checkout; it is not copied into the system installation
60
+ and is not a service dependency.
61
+
62
+ ## CLI examples
63
+
64
+ ```sh
65
+ breezed run --config /etc/breezed/breezed.toml --metrics-port 9762 -v # foreground daemon
66
+ breezed set 20 # one-shot 20% duty cycle
67
+ breezed auto # one-shot back to iDRAC automatic control
68
+ breezed status --config /etc/breezed/breezed.toml # snapshot: temps, RPMs, curve target
69
+ breezed validate breezed.toml --probe # check config; probe reads live temp
70
+ ```
71
+
72
+ The `daemon` subcommands manage the systemd deployment:
73
+
74
+ ```sh
75
+ breezed daemon install # one command, one sudo prompt
76
+ breezed daemon install --dry-run # print the privileged steps without escalating
77
+ breezed daemon status # report unit state and binary version
78
+ breezed daemon uninstall # one command, one sudo prompt; keeps env/config
79
+ ```
80
+
81
+ Exit codes: `0` ok, `1` runtime error (e.g. IPMI failure), `2` usage/config error.
82
+ Machine-readable output is always JSON on stdout; errors go to stderr as text.
83
+
84
+ ## Deploy (systemd)
85
+
86
+ systemd is the only deployment path — no containers. `daemon install` stages
87
+ `breezed.service`, `breezed.env`, and `breezed.toml` into a private temp
88
+ directory, prints the privileged steps, then re-executes itself once via sudo
89
+ to perform them. uv installs and manages the runtime directly under `/opt`:
90
+
91
+ ```sh
92
+ breezed daemon install
93
+ # one sudo password prompt; then:
94
+ sudoedit /etc/breezed.env
95
+ journalctl -u breezed -f
96
+ ```
97
+
98
+ `daemon install --dry-run` prints the same steps without escalating, for review.
99
+ The sudo re-exec runs only a fixed, code-reviewed sequence — no free-form
100
+ commands, no shell — using the absolute path of the running binary, so it is
101
+ immune to sudo's `secure_path`.
102
+
103
+ The runtime step sets `UV_TOOL_DIR=/opt/breezed`,
104
+ `UV_TOOL_BIN_DIR=/usr/local/bin`, and
105
+ `UV_PYTHON_INSTALL_DIR=/opt/breezed-python`, then installs the current checkout
106
+ with `--reinstall`. The sequence creates the non-login `breezed` system user and
107
+ installs files with explicit ownership and permissions:
108
+
109
+ - `/etc/systemd/system/breezed.service`: `root:root`, mode `0644`
110
+ - `/etc/breezed/breezed.toml`: invoking user and group, mode `0664`
111
+ - `/etc/breezed.env`: `root:breezed`, mode `0640`
112
+
113
+ The config and environment install steps run on first installation only and are
114
+ skipped when those files already exist, so upgrades never overwrite tuned config
115
+ or secrets.
116
+
117
+ **Upgrading**: update the checkout and run `breezed daemon install` again.
118
+ The uv `tool install --reinstall` step replaces the runtime in `/opt`; the config
119
+ and environment steps are skipped because those files already exist. `breezed
120
+ daemon uninstall` mirrors install: one sudo prompt to disable and remove the
121
+ service and runtime, while `/etc/breezed/` and `/etc/breezed.env` remain.
122
+
123
+ The metrics port is baked into the unit's `ExecStart` deliberately (netdata
124
+ scrapes it). To run without metrics, edit the unit to drop
125
+ `--metrics-port 9762` and `systemctl daemon-reload && systemctl restart
126
+ breezed`; note your edit will be overwritten by the next `daemon install`.
127
+
128
+ ## Config example
129
+
130
+ A fully commented example ships inside the package: see `breezed.toml.example`
131
+ in the breezed templates directory (also copied to `/etc/breezed/breezed.toml`
132
+ on first install, never overwritten after that).
133
+
134
+ Secrets never go in the config file: `IDRAC_HOST`, `IDRAC_USER`, and
135
+ `IDRAC_PASSWORD` come from the environment (`/etc/breezed.env`); host and user
136
+ may also live in the config, but environment variables win. The config
137
+ hot-reloads when its mtime changes; an invalid reload keeps the last good
138
+ config.
139
+
140
+ ## Metrics (netdata)
141
+
142
+ With the default unit, breezed serves Prometheus text format on
143
+ `127.0.0.1:9762`. Scrape URL for netdata's `prometheus` collector:
144
+ `http://127.0.0.1:9762/metrics`. Metric names: `breezed_temp_c`,
145
+ `breezed_fan_percent`, `breezed_mode`, `breezed_ipmi_errors_total`,
146
+ `breezed_polls_total`.
147
+
148
+ ## Safety
149
+
150
+ Manually controlling server fans means you are the thermal management system:
151
+ a bad curve can cook components or leave a server roaring at 100%. breezed
152
+ mitigates this by deferring to iDRAC automatic control above the curve top and
153
+ forcing AUTO again after repeated sensor-read failures — but you chose the
154
+ curve points, so choose them carefully. If anything looks wrong,
155
+ `breezed auto` hands control back to the iDRAC instantly.
156
+
157
+ ## License
158
+
159
+ [MIT](LICENSE)
@@ -0,0 +1,138 @@
1
+ # breezed
2
+
3
+ Curve-based fan controller for Dell PowerEdge servers via iDRAC/IPMI.
4
+ Python 3.13 · uv · ruff · ty.
5
+
6
+ Source: [github.com/martinmiglio/breezed](https://github.com/martinmiglio/breezed)
7
+
8
+ breezed is a curve-based fan controller for Dell PowerEdge servers, driving
9
+ iDRAC/IPMI with a multi-point temperature curve and linear interpolation between
10
+ points so homelab racks stay quiet at idle and cool under load. Above the top curve point it hands control back to
11
+ iDRAC's own automatic thermal management — the safety net is always one degree
12
+ away. Logs are JSON on stdout; a Prometheus-format metrics socket is opt-in;
13
+ adapters (IPMI transport) and speed policies (curve today, PID later) sit
14
+ behind small Protocols, so either can be swapped without touching the core.
15
+
16
+ ## Install
17
+
18
+ From PyPI:
19
+
20
+ ```sh
21
+ pip install breezed
22
+ # or
23
+ uv tool install breezed
24
+ ```
25
+
26
+ To deploy as a systemd service (the `breezed` binary needs privileges to talk to
27
+ iDRAC; `daemon install` stages the unit and re-execs under sudo once), run one
28
+ command and enter your password once:
29
+
30
+ ```sh
31
+ breezed daemon install
32
+ ```
33
+
34
+ `daemon install` stages the unit/env/config, then re-executes itself via sudo to
35
+ perform the fixed privileged steps (create the service user, install the runtime
36
+ under `/opt`, write the systemd unit, enable and start the service). Pass
37
+ `--dry-run` to print the steps without escalating. The user-level `uv` only
38
+ invokes breezed from the checkout; it is not copied into the system installation
39
+ and is not a service dependency.
40
+
41
+ ## CLI examples
42
+
43
+ ```sh
44
+ breezed run --config /etc/breezed/breezed.toml --metrics-port 9762 -v # foreground daemon
45
+ breezed set 20 # one-shot 20% duty cycle
46
+ breezed auto # one-shot back to iDRAC automatic control
47
+ breezed status --config /etc/breezed/breezed.toml # snapshot: temps, RPMs, curve target
48
+ breezed validate breezed.toml --probe # check config; probe reads live temp
49
+ ```
50
+
51
+ The `daemon` subcommands manage the systemd deployment:
52
+
53
+ ```sh
54
+ breezed daemon install # one command, one sudo prompt
55
+ breezed daemon install --dry-run # print the privileged steps without escalating
56
+ breezed daemon status # report unit state and binary version
57
+ breezed daemon uninstall # one command, one sudo prompt; keeps env/config
58
+ ```
59
+
60
+ Exit codes: `0` ok, `1` runtime error (e.g. IPMI failure), `2` usage/config error.
61
+ Machine-readable output is always JSON on stdout; errors go to stderr as text.
62
+
63
+ ## Deploy (systemd)
64
+
65
+ systemd is the only deployment path — no containers. `daemon install` stages
66
+ `breezed.service`, `breezed.env`, and `breezed.toml` into a private temp
67
+ directory, prints the privileged steps, then re-executes itself once via sudo
68
+ to perform them. uv installs and manages the runtime directly under `/opt`:
69
+
70
+ ```sh
71
+ breezed daemon install
72
+ # one sudo password prompt; then:
73
+ sudoedit /etc/breezed.env
74
+ journalctl -u breezed -f
75
+ ```
76
+
77
+ `daemon install --dry-run` prints the same steps without escalating, for review.
78
+ The sudo re-exec runs only a fixed, code-reviewed sequence — no free-form
79
+ commands, no shell — using the absolute path of the running binary, so it is
80
+ immune to sudo's `secure_path`.
81
+
82
+ The runtime step sets `UV_TOOL_DIR=/opt/breezed`,
83
+ `UV_TOOL_BIN_DIR=/usr/local/bin`, and
84
+ `UV_PYTHON_INSTALL_DIR=/opt/breezed-python`, then installs the current checkout
85
+ with `--reinstall`. The sequence creates the non-login `breezed` system user and
86
+ installs files with explicit ownership and permissions:
87
+
88
+ - `/etc/systemd/system/breezed.service`: `root:root`, mode `0644`
89
+ - `/etc/breezed/breezed.toml`: invoking user and group, mode `0664`
90
+ - `/etc/breezed.env`: `root:breezed`, mode `0640`
91
+
92
+ The config and environment install steps run on first installation only and are
93
+ skipped when those files already exist, so upgrades never overwrite tuned config
94
+ or secrets.
95
+
96
+ **Upgrading**: update the checkout and run `breezed daemon install` again.
97
+ The uv `tool install --reinstall` step replaces the runtime in `/opt`; the config
98
+ and environment steps are skipped because those files already exist. `breezed
99
+ daemon uninstall` mirrors install: one sudo prompt to disable and remove the
100
+ service and runtime, while `/etc/breezed/` and `/etc/breezed.env` remain.
101
+
102
+ The metrics port is baked into the unit's `ExecStart` deliberately (netdata
103
+ scrapes it). To run without metrics, edit the unit to drop
104
+ `--metrics-port 9762` and `systemctl daemon-reload && systemctl restart
105
+ breezed`; note your edit will be overwritten by the next `daemon install`.
106
+
107
+ ## Config example
108
+
109
+ A fully commented example ships inside the package: see `breezed.toml.example`
110
+ in the breezed templates directory (also copied to `/etc/breezed/breezed.toml`
111
+ on first install, never overwritten after that).
112
+
113
+ Secrets never go in the config file: `IDRAC_HOST`, `IDRAC_USER`, and
114
+ `IDRAC_PASSWORD` come from the environment (`/etc/breezed.env`); host and user
115
+ may also live in the config, but environment variables win. The config
116
+ hot-reloads when its mtime changes; an invalid reload keeps the last good
117
+ config.
118
+
119
+ ## Metrics (netdata)
120
+
121
+ With the default unit, breezed serves Prometheus text format on
122
+ `127.0.0.1:9762`. Scrape URL for netdata's `prometheus` collector:
123
+ `http://127.0.0.1:9762/metrics`. Metric names: `breezed_temp_c`,
124
+ `breezed_fan_percent`, `breezed_mode`, `breezed_ipmi_errors_total`,
125
+ `breezed_polls_total`.
126
+
127
+ ## Safety
128
+
129
+ Manually controlling server fans means you are the thermal management system:
130
+ a bad curve can cook components or leave a server roaring at 100%. breezed
131
+ mitigates this by deferring to iDRAC automatic control above the curve top and
132
+ forcing AUTO again after repeated sensor-read failures — but you chose the
133
+ curve points, so choose them carefully. If anything looks wrong,
134
+ `breezed auto` hands control back to the iDRAC instantly.
135
+
136
+ ## License
137
+
138
+ [MIT](LICENSE)
@@ -0,0 +1,48 @@
1
+ [project]
2
+ name = "breezed"
3
+ version = "0.1.0"
4
+ description = "Curve-based fan controller for Dell PowerEdge servers via iDRAC/IPMI"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ authors = [{ name = "Martin Miglio", email = "contact@martinmiglio.dev" }]
8
+ requires-python = ">=3.13"
9
+ dependencies = [
10
+ "pydantic>=2.13.4",
11
+ "rich>=13",
12
+ "typer>=0.12",
13
+ ]
14
+ classifiers = [
15
+ "License :: OSI Approved :: MIT License",
16
+ "Operating System :: POSIX :: Linux",
17
+ "Programming Language :: Python :: 3 :: Only",
18
+ "Programming Language :: Python :: 3.13",
19
+ "Topic :: System :: Hardware",
20
+ ]
21
+
22
+ [project.urls]
23
+ Homepage = "https://github.com/martinmiglio/breezed"
24
+ Repository = "https://github.com/martinmiglio/breezed"
25
+ Issues = "https://github.com/martinmiglio/breezed/issues"
26
+
27
+ [project.scripts]
28
+ breezed = "breezed.cli:app"
29
+
30
+ [dependency-groups]
31
+ dev = ["pytest>=8"]
32
+
33
+ [build-system]
34
+ requires = ["hatchling"]
35
+ build-backend = "hatchling.build"
36
+
37
+ [tool.hatch.build.targets.wheel]
38
+ packages = ["src/breezed"]
39
+
40
+ [tool.ruff]
41
+ line-length = 100
42
+ target-version = "py313"
43
+
44
+ [tool.ruff.lint]
45
+ select = ["E", "W", "F", "I", "UP", "B", "SIM"]
46
+
47
+ [tool.ty.src]
48
+ include = ["src", "tests"]
@@ -0,0 +1,3 @@
1
+ """Curve-based fan controller for Dell PowerEdge servers via iDRAC/IPMI."""
2
+
3
+ __version__ = "0.1.0"