Metadata-Version: 2.4
Name: smfc
Version: 5.1.2
Summary: Super Micro Fan Control for Linux
Author-email: Peter Sulyok <peter@sulyok.net>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/petersulyok/smfc
Project-URL: Changelog, https://github.com/petersulyok/smfc/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/petersulyok/smfc/issues
Keywords: supermicro,linux,daemon,fancontrol
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Hardware
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyudev
Dynamic: license-file

﻿
# smfc
[![Tests](https://github.com/petersulyok/smfc/actions/workflows/test.yml/badge.svg)
](https://github.com/petersulyok/smfc/actions/workflows/tests.yml) [![Codecov](https://codecov.io/gh/petersulyok/smfc/branch/main/graph/badge.svg)
](https://app.codecov.io/gh/petersulyok/smfc) [![Issues](https://img.shields.io/github/issues/petersulyok/smfc)
](https://github.com/petersulyok/smfc/issues) [![Supported Python Versions](https://img.shields.io/pypi/pyversions/smfc)](https://pypi.org/project/smfc)
[![PyPI version](https://badge.fury.io/py/smfc.svg)](https://badge.fury.io/py/smfc)

Super Micro fan control for Linux (home) servers.

## TL;DR

This is a `systemd service` running on Linux that can control fans with the help of IPMI on Super Micro X10-X13/H10-H13 (and some X9) motherboards.

### 1. Prerequisites
 - a Super Micro motherboard with ASPEED AST2400/2500/2600 chip
 - Python 3.10-3.14
 - a Linux distribution with:
   - `systemd` and `bash`
   - `coretemp` kernel module for Intel CPUs or `k10temp` kernel module for AMD CPUs
   - `drivetemp` kernel module (kernel version 5.6+ required) for SATA HDDs/SSDs
 - `ipmitool`
 - optional: `smartmontools` for SAS/SCSI disks and *standby guard* feature
 - optional: `nvidia-smi` for GPU fan controller 


### 2. Installation and configuration
 1. Set up the IPMI threshold values for your fans (see [chapter 6.](https://github.com/petersulyok/smfc/tree/main?tab=readme-ov-file#6-ipmi-fan-control-and-sensor-thresholds) for more details) 
 2. Optional: enable advanced power management features for your CPU and SATA hard disks for lower power consumption, heat generation and fan noise. 
 3. Load kernel modules (`coretemp/k10temp` and `drivetemp`)
 4. Install `smfc` service (see [chapter 9.](https://github.com/petersulyok/smfc?tab=readme-ov-file#9-installation-and-uninstallation) for more details)
    or run `smfc` in docker (see more details in [Docker.md](docker/Docker.md))
 5. Edit the configuration file `/etc/smfc/smfc.conf` and command line options in `/etc/default/smfc` (see [chapter 10.](https://github.com/petersulyok/smfc/tree/main?tab=readme-ov-file#10-configuration-file) for more details).
 6. Start `smfc` service (see [chapter 11.](https://github.com/petersulyok/smfc/tree/main?tab=readme-ov-file#11-how-to-run-smfc) for more details)
 7. Check results in system log
 8. Leave feedback in [discussion #55](https://github.com/petersulyok/smfc/discussions/55)

Feel free to visit [Discussions](https://github.com/petersulyok/smfc/discussions) and raise your questions or share your experience on this project.

## Details
### 1. How does it work?
This service was designed for Super Micro motherboards with IPMI functionality. It implements fan controllers that control
fan speed dynamically in one or more IPMI zones. The service operates the fans in IPMI FULL mode, where the fan rotation level
can be adjusted with IPMI raw commands (read [more details here](https://forums.servethehome.com/index.php?resources/supermicro-x9-x10-x11-fan-speed-control.20/)).

#### 1.1 IPMI zones
_IPMI zone_ is a logical term, representing a cooling zone, where there are predefined fans having the same rotation speed.
Please note that the fan assignment to an IPMI zone is predefined on the motherboard, it cannot be changed (Super Micro does not 
provide individual fan configuration features in IPMI, while other vendors do it). On a typical Super Micro motherboard, there are two IPMI zones:

- CPU or System zone (IPMI zone 0) with fan names: FAN1, FAN2, etc.
- Peripheral or HD zone (IPMI zone 1) with fan names: FANA, FANB, etc.

On Super Micro server boards, there could be more IPMI zones with different fan names (see [issue #31](https://github.com/petersulyok/smfc/issues/31)). 

> `smfc v3.8.0` and earlier versions implemented a feature (called _Swapped Zones_) to swap IPMI zone 0 and 1. From `smfc v4.0.0` the IPMI zones can be assigned freely to fan controllers providing more freedom and convenience for the user (see `ipmi_zone=` parameter for more details).  

#### 1.2 Fan controllers
In `smfc`, the following fan controllers are implemented:

| Fan controller | Temperature source      | Configuration                                                         | Default IPMI zone   |
|----------------|-------------------------|-----------------------------------------------------------------------|---------------------|
| CPU            | Intel/AMD CPU(s)        | CPUs are identified automatically                                     | 0 (CPU zone)        |
| HD             | SATA and SCSI HDDs/SSDs | Hard disks' names must be specified in `[HD] hd_names=` parameter     | 1 (Peripheral zone) |
| NVME           | NVMe SSDs               | NVMe device names must be specified in `[NVME] nvme_names=` parameter | 1 (Peripheral zone) |
| GPU            | Nvidia GPUs             | GPU indices must be specified in `[GPU] gpu_device_ids=` parameter    | 1 (Peripheral zone) |
| CONST          | None                    | Constant fan level can be specified in `[CONST] level=` parameter     | 1 (Peripheral zone) |

These fan controllers can be enabled and disabled independently. They can be used in a free combination with one or more IPMI zones. Multiple fan controllers
can share the same IPMI zone -- `smfc` will automatically apply the **highest** fan level requested by any controller in that zone (see [chapter 1.3](#13-shared-ipmi-zone-arbitration) for details).
_CONST fan controller_ is an exception here, it does not require a temperature source, it can provide a constant fan level for one or more IPMI zones.
In `smfc` configuration file each fan controller has an individual section.

In `smfc`, a temperature-driven fan controller implements the following control logic:

 1. it reads the temperature
 2. it calculates a new fan level based on the user-defined control function and the temperature value
 3. the service applies the fan level for the IPMI zone(s) with IPMI commands (i.e. `ipmitool`)

<img src="https://github.com/petersulyok/smfc/raw/main/doc/smfc_overview.png" align="center" width="600">

If the temperature source has multiple instances (e.g. multiple CPUs, HDDs, NVMEs or GPUs) then the user can configure a calculation method (i.e. minimum, average, maximum) for the calculation of the final temperature value (see `temp_calc=` parameter).

Please note that `smfc` will set all fans back to 100% speed at service termination to avoid overheating!

#### 1.3 Shared IPMI zone arbitration
When multiple fan controllers are assigned to the same IPMI zone, `smfc` detects this at startup and automatically switches to a two-phase arbitration loop for those controllers. Controllers on non-shared zones are not affected -- they apply their fan levels directly.

At startup, `smfc` logs the detected shared zones at INFO level:

```
Shared IPMI zone 1: ['HD', 'NVME', 'CONST']
```

For shared zones, the control loop uses a two-phase approach in each iteration:

 1. **Compute phase**: each fan controller on a shared zone reads its temperature source and calculates its desired fan level, but defers the IPMI call.
 2. **Apply phase**: the service collects all desired levels, groups them by IPMI zone, and applies the **maximum** level per zone. Only one IPMI command is sent per zone, and only when the level has actually changed.

Controllers on non-shared zones skip the apply phase entirely -- they execute their own IPMI calls directly during the compute phase, just like they would if no sharing existed.

This means the hottest component always wins on a shared zone. For example, if HD fan controller wants 45% on zone 1 and NVME fan controller wants 70% on the same zone, `smfc` will set zone 1 to 70%. When the NVME cools down below the HD temperature, the HD controller's level will take over.

The CONST fan controller also participates in the arbitration -- its constant level acts as a guaranteed minimum for its zone(s). For example, configuring `[CONST] level=40` on zone 1 ensures that zone never drops below 40%, even if all temperature-driven controllers would request a lower value.

When a shared zone's level changes, the log output at INFO level shows the winning controller and lists all other controllers with their requested levels:

```
Shared IPMI zone [1]: new level = 70% (winner: NVME=70%/52.0C, losers: HD=45%/38.5C, CONST=40%)
```

For non-shared zones, only the applied level is logged:

```
IPMI zone [0]: new level = 60% (CPU=45.0C)
```

### 2. User-defined control function
Fan controllers use user-defined control functions that map a temperature interval to a fan rotation level interval.

 <img src="https://github.com/petersulyok/smfc/raw/main/doc/userdefined_control_function.png" align="center" width="500">

The following five parameters will define such a function:

     min_temp=
     max_temp=
     min_level=
     max_level=
     steps=

In this way, a fan controller can map any new temperature value to a fan level (from Celsius degrees to % value).   
Changing the fan rotational speed is a very slow process (it could take several seconds depending on the fan type and the requested amount of change), so we try to minimize these kinds of actions. Instead of setting fan rotational speed continuously, we define discrete fan levels based on `steps=` parameter.

 <img src="https://github.com/petersulyok/smfc/raw/main/doc/fan_output_levels.png" align="center" width="500">

The fan controllers implement the following strategies to avoid/minimize the unnecessary change of fan rotation speed:

 1. When the fan rotational speed is changed, it always applies a delay time (defined in `[IPMI] fan_level_delay=` configuration parameter) to let the fan implement the physical change.
 2. There is a sensitivity threshold parameter (`sensitivity=`) in the fan controller configuration. While the temperature change is below this value, the fan controller does not react. 
 3. The configuration parameter `polling=` defines the frequency of the temperature reading. The bigger polling time, the lower frequency of the fan speed change.

### 3. Standby guard
For the HD fan controller, an additional optional feature was implemented, called *Standby guard*, with the following assumptions:
	
 - SATA hard disks are organized into a RAID array
 - the RAID array will go to standby mode recurrently

This feature monitors the power state of SATA hard disks (with the help of `smartctl`) and will put the whole array into standby mode if a few members have already stepped into that state. With this feature, the situation can be avoided where the array is partially in standby mode while other members are still active.
SCSI disks are not compatible with this feature.

### 4. Hard disk compatibility
The following table summarizes how the temperature is read for different disk types: 

| Disk type  | Temperature source   | Kernel module | Command    |
|------------|----------------------|---------------|------------|
| `SATA`     | Linux kernel (HWMON) | `drivetemp`   | -          |
| `NVME`     | Linux kernel (HWMON) | -             | -          |
| `SAS/SCSI` | `smartctl`           | -             | `smartctl` |


> The `smfc` service was originally designed for `SATA` hard drives, but from `smfc v3.0.0`, it is also compatible with `NVME` and `SAS/SCSI` disks.
> `smfc v5.0.0` introduced a new NVME fan controller and separated the use of SATA and SAS/SCSI HDDs/SSDs and NVME SSD disks.  

Some additional notes:

- For `SATA` disks the `drivetemp` kernel module should be loaded. **This is the fastest way to read disk temperature**, and the kernel module can report the temperature while hard disks are in sleep mode!
- For `SAS/SCSI` disks the `smartctl` command will be used to read disk temperature.
- If `drivetemp` module is not loaded or an HDD is not compatible with `drivetemp` module then `smfc` will use `smartctl` automatically.   
- Different disks types can be mixed in `hd_names=` configuration parameter but the *Standby guard* feature will not be supported in this case.
- For `NVME` SSDs, no kernel driver needs to be loaded; the kernel can handle this disk type automatically
- NVME SSDs can be used in [NVME] fan controller and [HD] fan controller does not accept them anymore.


### 5. Super Micro compatibility
Feel free to create a short feedback in [discussion #55](https://github.com/petersulyok/smfc/discussions/55) on your compatibility experience.

#### 5.1 Super Micro X10-X13/H10-H13 motherboards
Originally, this software was designed to work with Super Micro X10-X12/H10-H12 motherboards with IPMI functionality,
where the BMC chip is ASPEED AST2400 or AST2500. Most motherboards in this set are compatible with the Super Micro IPMI
raw commands used here and are supported out of the box.

Newer X13/H13 motherboards with AST2600 chips are also compatible with `smfc` (see more details in [issue #33](https://github.com/petersulyok/smfc/issues/33) about
an X13SAE-F motherboard). The only difference is in the implementation of thresholds: the AST2600 chip implements only the
`Lower Critical` threshold, so setting up thresholds is different.

Some motherboards require platform-specific IPMI raw commands for fan control. `smfc` implements a **platform abstraction**
(since `smfc v5.1.0`) that handles these differences. The platform is auto-detected from BMC product name, or can be overridden with the
`platform_name=` configuration parameter (see [chapter 10.2](https://github.com/petersulyok/smfc/tree/main?tab=readme-ov-file#102-sample-configuration-file)). Currently supported platforms:

| `platform_name=` parameter | Platform                                     | Notes                                                                                            |
|----------------------------|----------------------------------------------|--------------------------------------------------------------------------------------------------|
| `auto`                     | automatic discovery based on BMC information | Default behaviour                                                                                |
| `generic`                  | Generic X10-X13/H10-H13 Super Micro boards   | Uses standard Super Micro IPMI raw commands                                                      |
| `X10QBi`                   | Super Micro X10QBi motherboard               | Nuvoton NCT7904D fan controller, 4 fan zones (0x10-0x13), see [issue #69](https://github.com/petersulyok/smfc/issues/69) and [PR #97](https://github.com/petersulyok/smfc/pull/97) |

With this abstraction layer, new Super Micro motherboards can also be added to `smfc` with a good understanding of their IPMI raw commands and fan control logic.

#### 5.2 Super Micro X14/H14 motherboards
For the newer X14/H14 motherboards, compatibility is still being investigated. There are some issues (#98) and discussions (#92, #106) about this to get better understanding.

#### 5.3 Super Micro X9 motherboards
For X9 motherboards, compatibility is not guaranteed; it depends on the hardware components of the motherboard (i.e. not all X9 motherboards employ a BMC chip).

#### 5.4 Super Micro X8 motherboards
The earlier X8 motherboards are NOT compatible with this software. They do not implement `IPMI FULL` mode, and they cannot control fan levels with IPMI raw commands.


### 6. IPMI fan control and sensor thresholds
On Super Micro X10-X11 motherboards IPMI uses six sensor thresholds to specify the safe and unsafe fan rotational speed intervals (these are RPM values rounded to the nearest hundreds, defined for each fan separately):

```
Lower Non-Recoverable  
Lower Critical  
Lower Non-Critical
Upper Non-Critical  
Upper Critical  
Upper Non-Recoverable
```

but newer Super Micro X13 motherboards (with AST2600 BMC chip) have only one sensor threshold:

```
Lower Critical  
```

Originally, this chapter was created for Super Micro X10-X11 motherboards, but can be easily adapted to X13 motherboards as well (see more details in #33).

Like many other utilities (created by NAS and home server community), `smfc` also uses **IPMI FULL mode** for fan control, where all fans in the zone:

   1. initially configured to full speed (100%)
   2. then their speed can be safely configured in `[Lower Critical, Upper Critical]` interval
   3. if any fan speed oversteps either `Lower Critical` or `Upper Critical` threshold then IPMI will generate an _assertion event_ and will set all fan speeds back to 100% in the zone

Please also consider the fact that **fans are mechanical devices, their rotational speed is not stable** (it could be fluctuating). To avoid IPMI's assertion mechanism described here please follow the next steps: 

  1. Per fan: check the minimum and maximum rotational speeds of your fan on its vendor website
  2. Per fan: configure proper IPMI sensor thresholds adjusted to the fan speed interval
  3. Per zone: define safe `min_level`/`max_level` values for `smfc` respecting the variance of all fans in the IPMI zone (it could take several iterations and adjustments) 

<img src="https://github.com/petersulyok/smfc/raw/main/doc/ipmi_sensor_threshold.png" align="center" width="600">

Here is a real-life example for a [Noctua NF-F12 PWM](https://noctua.at/en/products/fan/nf-f12-pwm) fan:

```
Upper Non-Recoverable = 1800 rpm
Upper Critical = 1700 rpm
Upper Non-Critical = 1600 rpm
Lower Non-Critical = 200 rpm
Lower Critical = 100 rpm
Lower Non-Recoverable = 0 rpm
Max RPM = 1500 rpm
Min RPM = 300 rpm
max_level = 100 (i.e. 1500 rpm)
min_level = 35 (i.e. 500 rpm)
```


Notes:
  - Use the following `ipmitool` command to display the current IPMI sensor thresholds for fans:
    ```
    root@home:~# ipmitool sensor|grep FAN
    FAN1             | 500.000    | RPM        | ok    | 0.000     | 100.000   | 200.000   | 1600.000  | 1700.000  | 1800.000  
    FAN2             | 500.000    | RPM        | ok    | 0.000     | 100.000   | 200.000   | 1600.000  | 1700.000  | 1800.000  
    FAN3             | na         |            | na    | na        | na        | na        | na        | na        | na        
    FAN4             | 400.000    | RPM        | ok    | 0.000     | 100.000   | 200.000   | 1600.000  | 1700.000  | 1800.000  
    FANA             | 500.000    | RPM        | ok    | 0.000     | 100.000   | 200.000   | 1600.000  | 1700.000  | 1800.000  
    FANB             | 500.000    | RPM        | ok    | 0.000     | 100.000   | 200.000   | 1600.000  | 1700.000  | 1800.000  
    ```
  - Use the following `ipmitool` command to list assertion events:
    ```
    root@home:~# ipmitool sel list
       1 | 10/19/2023 | 05:15:35 PM CEST | Fan #0x46 | Lower Critical going low  | Asserted
       2 | 10/19/2023 | 05:15:35 PM CEST | Fan #0x46 | Lower Non-recoverable going low  | Asserted
       3 | 10/19/2023 | 05:15:38 PM CEST | Fan #0x46 | Lower Non-recoverable going low  | Deasserted
       4 | 10/19/2023 | 05:15:38 PM CEST | Fan #0x46 | Lower Critical going low  | Deasserted
       5 | 10/19/2023 | 05:20:59 PM CEST | Fan #0x46 | Lower Critical going low  | Asserted
    ```
  - Use the following `ipmitool` commands to specify all six sensor thresholds for FAN1:
    ```
    root@home:~# ipmitool sensor thresh FAN1 lower 0 100 200
    root@home:~# ipmitool sensor thresh FAN1 upper 1600 1700 1800
    ```
  - You can also edit and run `ipmi/set_ipmi_threshold.sh` to configure all IPMI sensor thresholds
  - If you install new BMC firmware on your Super Micro motherboard, you have to configure IPMI thresholds again
  - If you do not see fans when executing `ipmitool sensors`, you may want to reset the BMC to factory default using the Web UI or using `ipmitool mc reset cold`
  - Noctua specifies the variance of minimum and maximum fan rotational speeds (e.g. see the [specification of Noctua NF-F12 PWM](https://noctua.at/en/products/fan/nf-f12-pwm/specification)). For example:

    - `Rotational speed (+/- 10%) 1500 RPM`: 1350-1650 RPM interval
    - `Min. rotational speed @ 20% PWM (+/-20%) 300 RPM`: 240-360 RPM interval
    
    Please note that [LNA](https://noctua.at/en/na-src10)/ULNA cables or [Y-cables](https://noctua.at/en/na-syc1) can modify the rotational speed calculations here and the required IPMI sensor thresholds too. 

You can read more about:

 - IPMI fan control: [STH Forums](https://forums.servethehome.com/index.php?resources/supermicro-x9-x10-x11-fan-speed-control.20/) and [TrueNAS Forums](https://www.truenas.com/community/threads/pid-fan-controller-perl-script.50908/)
 - Change IPMI sensors thresholds: [TrueNAS Forums](https://www.truenas.com/community/resources/how-to-change-ipmi-sensor-thresholds-using-ipmitool.35/)

### 7. Power management
If low noise and low heat generation are important attributes of your Linux box, then you may consider the following chapters.

#### 7.1 CPU
Most modern CPUs have multiple energy-saving features. You can check your BIOS and enable them to minimize the heat generation.

Intel(R) CPUs:
 - Intel(R) Speed Shift Technology
 - Intel(R) SpeedStep
 - C-states
 - Boot performance mode

AMD(R) CPUs:
 - PowerNow!
 - Cool\`n\`quiet
 - Turbo Core

With this setup the CPU will change its base frequency and power consumption dynamically based on the load.

#### 7.2 SATA hard disks
In case of SATA hard disks, you may enable:

 - advanced power management
 - spin down timer

With the help of command `hdparm` you can enable advanced power management and specify a spin down timer (read more [here](https://en.wikipedia.org/wiki/Hdparm)):

	hdparm -B 127 /dev/sda
	hdparm -S 240 /dev/sda
	
In file `/etc/hdparm.conf` you can specify all parameters persistently:

	quiet

	/dev/sda {
        apm = 127
        spindown_time = 240
	}
	/dev/sdb {
        apm = 127
        spindown_time = 240
	}
	...

Important notes: 
 1. If you plan to spin down your hard disks or RAID array (i.e. put them to standby mode) you have to set up the configuration parameter `[HD] polling=` to at least twice as big as the `spindown_time` specified here.
 2. In file `/etc/hdparm.conf` you must define HD names in `/dev/disk/by-id/...` form to avoid inconsistency.

### 8. Kernel modules
One or more of the following Linux kernel modules need to be loaded for `smfc`:

 - [`coretemp`](https://www.kernel.org/doc/html/latest/hwmon/coretemp.html): temperature report for Intel(R) CPUs
 - [`k10temp`](https://docs.kernel.org/hwmon/k10temp.html): temperature report for AMD(R) CPUs
 - [`drivetemp`](https://www.kernel.org/doc/html/latest/hwmon/drivetemp.html): temperature report for SATA hard disks (available from kernel 5.6+ version)

Use `/etc/modules` file for persistent loading of these modules. 

Notes:
- Reading `drivetemp` module is the fastest way to get the temperature of the hard disks, and it can read temperature of the SATA hard disks even if they are in standby mode.


### 9. Installation and uninstallation
For the installation and uninstallation, you need root privileges. There are several ways to install and uninstall `smfc`, this chapter will show them.

#### 9.1. Manual installation and uninstallation
There is an installation script ([`bin/install.sh`](https://raw.githubusercontent.com/petersulyok/smfc/refs/heads/main/bin/install.sh)) which can install `smfc` in two different ways:
- remotely from the GitHub repository (no cloning required)
- locally from a git repository (GitHub repository needs to be cloned)

The installation script requires `curl`, `pip`, `gzip`, and `mandb` commands, and it has the following
command line parameters:

```
user@host:~$ ./install.sh --help
usage: install.sh [-h|--help] [-k|--keep-config] [-l|--local] [-v|--verbose]
           -h, --help         help text
           -k, --keep-config  keep original configuration file
           -l, --local        installation from a local git repository
           -v, --verbose      verbose output
```

The default location of the installed files: 

| Files          | Installation folder                                        | Description                     |
|----------------|------------------------------------------------------------|---------------------------------|
| `smfc.service` | `/etc/systemd/system`                                      | systemd service definition file |
| `smfc`         | `/etc/default`                                             | service command line options    |
| `smfc.conf`    | `/etc/smfc`                                                | service configuration file      |
| `smfc.1.gz`    | `/usr/local/share/man/man1`                                | smfc manual page                | 
| `smfc`         | `/usr/local/bin` or </br> `/usr/bin`                       | smfc command                    |
| `smfc service` | `/usr/local/lib/python3.xx` or </br> `/usr/lib/python3.xx` | smfc python package             |

Notes for the script:
- Different Linux distros install python package to different folders (it was tested on Ubuntu 24.04, Debian 13,
Suse Leap 15, Proxmox 9, and Arch Linux)
- Installation process will stop for any error
- The default installation method is the remote installation
- Using `--local` parameter will do installation locally, from the current folder (i.e. GitHub repository needs to be cloned)
- The default action is the following:
  - the existing previous configuration file will be renamed
  - a new configuration file will be installed
  - `hd_names=` configuration parameter will be pre-filled with the list of existing hard disks for user's convenience
    (please check/edit this parameter!)
- Using `--keep-config` parameter, the original configuration file will be preserved
- Using `--verbose` parameter, the phases of the installation will be displayed 

For remote installation the script can be executed (as root user) this way:

```
curl --silent https://raw.githubusercontent.com/petersulyok/smfc/refs/heads/main/bin/install.sh|bash /dev/stdin --verbose
```

or if you want to preserve your existing configuration file:

```
curl --silent https://raw.githubusercontent.com/petersulyok/smfc/refs/heads/main/bin/install.sh|bash /dev/stdin --verbose --keep-config
```

For local installation follow these steps (here [`uv` command](https://docs.astral.sh/uv/getting-started/installation/) is also required):

```
git clone https://github.com/petersulyok/smfc.git
cd smfc
uv sync
uv build
./bin/install.sh --local --verbose --keep-config
```

Here we clone the GitHub repository and make the `smfc` package locally before installation.

On the other hand, there is an uninstallation script ([`bin/uninstall.sh`](https://raw.githubusercontent.com/petersulyok/smfc/refs/heads/main/bin/uninstall.sh)) which can uninstall `smfc`.
This script has the following command line parameters:

```
user@host:~$ ./uninstall.sh --help
usage: uninstall.sh [-h|--help] [-k|--keep-config] [-v|--verbose]
           -h, --help         help text
           -k, --keep-config  keep original configuration file
           -v, --verbose      verbose output
```

This script can be executed locally and remotely as described for installation above. Here is an example for remote execution: 

```
curl --silent https://raw.githubusercontent.com/petersulyok/smfc/refs/heads/main/bin/uninstall.sh|bash /dev/stdin --verbose
```

The script will remove the installed `smfc` files and the python package.

#### 9.2. DEB and RPM package installation
Pre-built DEB and RPM packages are available as build artifacts from the [GitHub packages workflow](https://github.com/petersulyok/smfc/actions/workflows/packages.yml) on each release. You can also build them locally from the repository.

For Debian/Ubuntu systems:

```
sudo dpkg -i smfc_*.deb
```

For Fedora/RHEL systems:

```
sudo dnf install smfc-*.rpm
```

The packages install the same files as the manual installation (service unit, configuration, man page, and sample configs). Configuration files under `/etc/` are preserved on upgrade. See [PACKAGES.md](PACKAGES.md) for build instructions and compatible distributions.

#### 9.3. Docker installation
`smfc` is also available as a docker image, see more details in [Docker.md](../docker/Docker.md). In this case, your job is only to provide your configuration file on the host computer, `smfc` will be executed automatically when the container is starting. 

### 10. Configuration file
After successful installation, create/edit your new configuration file. If you just upgraded to a new `smfc` version, you can preserve the existing one. 

#### 10.1 Right strategy to create your configuration file
You have to think over and answer the following questions:

1. What are the most important heat sources in your machine? Typically, these could be CPU(s), hard disks, or GPUs.
2. Which fan controller would you like to use and configure in `smfc`?
3. What is the expected temperature interval (minimum/maximum C degree) for the selected temperature source(s)? Use some test tools to measure it (e.g. [`s-tui`](https://github.com/amanusk/s-tui), [`fio`](https://fio.readthedocs.io/en/latest/fio_doc.html), [`iozone`](https://www.iozone.org/)) if you don't have their track records.  
4. Which IPMI zone(s) will be connected to these fan controllers/temperature sources)? Check how many IPMI zones you have, how the fans are connected on your motherboard, and how they are cooling the selected temperature source(s). Multiple controllers can share the same zone -- the highest requested level will be applied automatically.
5. What is the stable level interval for fans in the selected IPMI zone(s)? Probably this part requires the most patience! You have assumptions here that need to be verified. If you experience IPMI assertions and your fans are spinning up then you have to refine the level interval or threshold configuration and try again. You will have several cycles here, this is normal. 

#### 10.2 Sample configuration file
The configuration file contains sections. The first one for IPMI configuration, the rest for fan controllers.
Edit `/etc/smfc/smfc.conf` and specify your configuration parameters here:

```
#
#   smfc.conf (C) 2020-2026, Peter Sulyok
#   smfc 5.x service configuration parameters
#
#   Please read the documentation here: https://github.com/petersulyok/smfc
#

# Ipmi specific parameters.
[Ipmi]
# Path for ipmitool (str, default=/usr/bin/ipmitool)
command=/usr/bin/ipmitool 
# Delay time after changing IPMI fan mode (int, seconds, default=10)
fan_mode_delay=10
# Delay time after changing IPMI fan level (int, seconds, default=2)
fan_level_delay=2
# IPMI parameters for remote access (string, default='')
#remote_parameters=-U USERNAME -P PASSWORD -H HOST
# Super Micro platform (string, default='auto')
# Potential values:
#  auto    - automatic discovery based on BMC information
#  generic - Generic X10-X13/H10-H13 Super Micro platform
#  X10QBi  - Super Micro X10QBi platform
platform_name=auto

# CPU fan controller: works based on CPU(s) temperature.
[CPU]
# Fan controller enabled (bool, default=0)
enabled=1
# IPMI zone(s) (comma- or space-separated list of int, default=0))
ipmi_zone=0
# Calculation method for CPU temperatures (int, [0-minimum, 1-average, 2-maximum], default=1)
temp_calc=1
# Discrete steps in mapping of temperatures to fan level (int, default=6)
steps=6
# Threshold in temperature change before the fan controller reacts (float, C, default=3.0)
sensitivity=3.0
# Polling time interval for reading temperature (int, sec, default=2)
polling=2
# Minimum CPU temperature (float, C, default=30.0)
min_temp=30.0
# Maximum CPU temperature (float, C, default=60.0)
max_temp=60.0
# Minimum CPU fan level (int, %, default=35)
min_level=35
# Maximum CPU fan level (int, %, default=100)
max_level=100


# HD fan controller: works based on SATA or SAS HDDs/SSDs temperature.
[HD]
# Fan controller enabled (bool, default=0)
enabled=1
# IPMI zone(s) (comma- or space-separated list of int, default=1))
ipmi_zone=1
# Calculation of HD temperatures (int, [0-minimum, 1-average, 2-maximum], default=1)
temp_calc=1
# Discrete steps in mapping of temperatures to fan level (int, default=4)
steps=4
# Threshold in temperature change before the fan controller reacts (float, C, default=2.0)
sensitivity=2.0
# Polling interval for reading temperature (int, sec, default=10)
polling=10
# Minimum HD temperature (float, C, default=32.0)
min_temp=32.0
# Maximum HD temperature (float, C, default=46.0)
max_temp=46.0
# Minimum HD fan level (int, %, default=35)
min_level=35
# Maximum HD fan level (int, %, default=100)
max_level=100
# Names of the HDs (str multi-line list, default=)
# MUST BE specified in '/dev/disk/by-id/...' form, for example:
# hd_names=/dev/disk/by-id/ata-WDC_WD100EFAX-68LHPN0_8CH7T91E
#	/dev/disk/by-id/ata-WDC_WD100EFAX-68LHPN0_8CH7T813
#	/dev/disk/by-id/ata-WDC_WD100EFAX-68LHPN0_8CHUFFRE
hd_names=
# Path for 'smartctl' command (str, default=/usr/sbin/smartctl).
smartctl_path=/usr/sbin/smartctl
# Standby guard feature for RAID arrays (bool, default=0)
standby_guard_enabled=0
# Number of HDs already in STANDBY state before the full RAID array will be forced to it (int, default=1)
standby_hd_limit=1


# NVME fan controller: works based on NVMe SSD(s) temperature.
[NVME]
# Fan controller enabled (bool, default=0)
enabled=0
# IPMI zone(s) (comma- or space-separated list of int, default=1))
ipmi_zone=1
# Calculation of NVMe temperatures (int, [0-minimum, 1-average, 2-maximum], default=1)
temp_calc=1
# Discrete steps in mapping of temperatures to fan level (int, default=4)
steps=4
# Threshold in temperature change before the fan controller reacts (float, C, default=2.0)
sensitivity=2.0
# Polling interval for reading temperature (int, sec, default=10)
polling=10
# Minimum NVMe temperature (float, C, default=35.0)
min_temp=35.0
# Maximum NVMe temperature (float, C, default=70.0)
max_temp=70.0
# Minimum NVMe fan level (int, %, default=35)
min_level=35
# Maximum NVMe fan level (int, %, default=100)
max_level=100
# Names of the NVMe devices (str multi-line list, default=)
# MUST BE specified in '/dev/disk/by-id/...' form, for example:
# nvme_names=/dev/disk/by-id/nvme-ADATA_LEGEND_650_2OFF29AO8DKR
#	/dev/disk/by-id/nvme-CT4000P3PSSD7_2446E89408FA
nvme_names=


# GPU fan controller: works based on Nvidia GPU(s) temperature.
[GPU]
# Fan controller enabled (bool, default=0)
enabled=0
# IPMI zone(s) (comma- or space-separated list of int, default=1))
ipmi_zone=1
# Calculation of GPU temperatures (int, [0-minimum, 1-average, 2-maximum], default=1)
temp_calc=1
# Discrete steps in mapping of temperatures to fan level (int, default=5)
steps=5
# Threshold in temperature change before the fan controller reacts (float, C, default=2.0)
sensitivity=2.0
# Polling interval for reading temperature (int, sec, default=10)
polling=2
# Minimum GPU temperature (float, C, default=40.0)
min_temp=40.0
# Maximum GPU temperature (float, C, default=70.0)
max_temp=70.0
# Minimum GPU fan level (int, %, default=35)
min_level=35
# Maximum GPU fan level (int, %, default=100)
max_level=100
# GPU device IDs (comma- or space-separated list of int, default=0)
# These are indices in nvidia-smi temperature report.
gpu_device_ids=0
# Path for 'nvidia-smi' command (str, default=/usr/bin/nvidia-smi).
nvidia_smi_path=/usr/bin/nvidia-smi


# CONST fan controller: sets constant fan level (without any heat source) for IPMI zones(s).
[CONST]
# Fan controller enabled (bool, default=0)
enabled=0
# IPMI zone(s) (comma- or space-separated list of int, default=1))
ipmi_zone=1
# Polling interval for checking/resetting level if needed (int, sec, default=30)
polling=30
# Constant fan level (int, %, default=50)
level=50
```

Important notes:
1. `[Ipmi] remote_parameters=-U USERNAME -P PASSWORD -H HOST` parameter can be used for remote access for the IPMI interface. It could be useful for a VM setup where the hard disks are configured with PCI passthrough (e.g. a TrueNAS running in a VM on Proxmox), but IPMI needs to be accessed "remotely". Please note that the HOST is the BMC network address (not the VM host address).
2. `[HD] hd_names=` is a compulsory parameter for HD fan controller, and it must be specified in `/dev/disk/by-id/...` form. Please note that the `/dev/sda` form is not persistent and could change after a reboot!
3. `[NVME] nvme_names=` is a compulsory parameter for NVME fan controller, and it must be specified in `/dev/disk/by-id/...` form. Please note that the `/dev/nvme0n1` form is not persistent and could change after a reboot!
4. `[CPU] / [HD] / [NVME] min_level= / max_level=` should be configured in alignment with threshold configuration (see more details in [this chapter](https://github.com/petersulyok/smfc/blob/main/README.md#6-ipmi-fan-control-and-sensor-thresholds)). Be patient, several refinement cycles could happen.
5. Several sample configuration files are provided in `./config/samples` folder.
6. Save/backup your configuration file when you've got the final version. Avoid overwriting if you upgrade to a new version of `smfc`.


### 11. How to run `smfc`?
After manual installation, `smfc` can be started and stopped as a standard `systemd` service. Remember to reload `systemd` configuration after a new installation or if you changed the service definition file:

```
systemctl daemon-reload
systemctl start smfc.service
systemctl stop smfc.service
systemctl restart smfc.service
systemctl status smfc.service
● smfc.service - Super Micro Fan Control
     Loaded: loaded (/etc/systemd/system/smfc.service; enabled; preset: enabled)
     Active: active (running) since Tue 2026-03-03 21:32:22 CET; 7min ago
 Invocation: b613d841e1cf43f4ace80d472623ed4c
   Main PID: 82521 (smfc)
      Tasks: 1 (limit: 154231)
     Memory: 12M (peak: 19.5M)
        CPU: 1.271s
     CGroup: /system.slice/smfc.service
             └─82521 /usr/bin/python3 /usr/local/bin/smfc -c /etc/smfc/smfc.conf -l 3

Mar 03 21:37:27 nas smfc.service[82521]: Shared IPMI zone [0]: new level = 67% (winner: CPU=67%/51.0C, losers: NVME=35%/37.9C)
Mar 03 21:37:30 nas smfc.service[82521]: Shared IPMI zone [0]: new level = 35% (winner: CPU=35%/31.0C, losers: NVME=35%/37.9C)
Mar 03 21:38:46 nas smfc.service[82521]: Shared IPMI zone [0]: new level = 67% (winner: CPU=67%/49.0C, losers: NVME=35%/37.9C)
Mar 03 21:38:49 nas smfc.service[82521]: Shared IPMI zone [0]: new level = 35% (winner: CPU=35%/31.0C, losers: NVME=35%/37.9C)
```

The `smfc` program has the following parameters:

```
root@nas$ smfc --help
usage: smfc [-h] [-c CONFIG_FILE] [-v] [-l {0,1,2,3,4}] [-o {0,1,2}] [-nd] [-s] [-ne]

options:
  -h, --help      show this help message and exit
  -c CONFIG_FILE  configuration file (default is /etc/smfc/smfc.conf)
  -v, --version   show program's version number and exit
  -l {0,1,2,3,4}  set log level: 0-NONE, 1-ERROR(default), 2-CONFIG, 3-INFO, 4-DEBUG
  -o {0,1,2}      set log output: 0-stdout, 1-stderr, 2-syslog(default)
  -nd             no dependency checking at start
  -s              use sudo command
  -ne             no fan speed recovery at exit
```

`smfc` command-line options can be specified in `/etc/default/smfc` file if you run `smfc` as a systemd service. 

If you are testing your configuration, you can start `smfc` directly in a terminal (logging to the standard output on debug log level):

	smfc -o 0 -l 3

In case of Docker installation, `smfc` will be executed automatically when the container is started. Its command-line parameters can be specified in the docker-compose file. 

### 12. Checking the results and monitoring the logs
All messages will be logged to the specific output and the specific level.
With the help of command `journalctl` you can check logs easily. For example:

1. listing service logs of the last two hours:

		journalctl -u smfc --since "2 hours ago"

2. listing service logs from the last boot:

		journalctl -b -u smfc

### 13. FAQ

### Q: My fans are spinning up and loud. What's wrong?
Most probably, there was an assertion (i.e., the rotational speed of a fan went above or below an IPMI threshold) and IPMI switched back that zone to full rotational speed.
You can check the current fan rotational speeds:

	ipmitool sdr

and you can also check IPMI event log and list assertion events:

```
root@home:~# ipmitool sel list
   1 | 10/19/2023 | 05:15:35 PM CEST | Fan #0x46 | Lower Critical going low  | Asserted
   2 | 10/19/2023 | 05:15:35 PM CEST | Fan #0x46 | Lower Non-recoverable going low  | Asserted
   3 | 10/19/2023 | 05:15:38 PM CEST | Fan #0x46 | Lower Non-recoverable going low  | Deasserted
   4 | 10/19/2023 | 05:15:38 PM CEST | Fan #0x46 | Lower Critical going low  | Deasserted
   5 | 10/19/2023 | 05:20:59 PM CEST | Fan #0x46 | Lower Critical going low  | Asserted
```

If the problematic fan (causing the alert) is identified, then you must adjust its threshold. This process could take several adjustment cycles. Be patient :)
You may read [this chapter](https://github.com/petersulyok/smfc#7-ipmi-fan-control-and-sensor-thresholds) for more details. 

### Q: How does the author test/use this service?
The configuration is the following:

 - [Super Micro X11SCH-F motherboard](https://www.supermicro.com/en/products/motherboard/X11SCH-F)
 - [Intel (R) Xeon (R) E-2276G processor](https://www.intel.com/content/www/us/en/products/sku/191035/intel-xeon-e2276g-processor-12m-cache-3-80-ghz/specifications.html)
 - 128 GB ECC DDR4-2666MHz RAM
 - [Fractal Design Node 804 case](https://www.fractal-design.com/products/cases/node/node-804/black/), with separate chambers for the motherboard and the hard disks:
 
	<img src="https://www.legitreviews.com/wp-content/uploads/2014/05/fractal-design-node-804-vendor-fans.jpg" align="center" width="500">

 - Proxmox 9
 - 8 x [WD Red 12TB (WD120EFAX)](https://shop.westerndigital.com/en-ie/products/outlet/internal-drives/wd-red-plus-sata-3-5-hdd#WD120EFAX) hard disks in ZFS RAID
 - 4 x [Noctua NF-F12 PWM](https://noctua.at/en/products/fan/nf-f12-pwm)  fans (FAN1, FAN2, FAN3, FAN4) in IPMI CPU zone
 - 2 x [Noctua NF-F12 PWM](https://noctua.at/en/products/fan/nf-f12-pwm) on an Y-adapter + [Noctua NF-A14 PWM](https://noctua.at/en/products/fan/nf-a14-pwm) fans (FANA, FANB) in IPMI HD zone

### 15. References
Further readings:

#### Super Micro
 - [BMC IPMI User's Guide 1.1b (X10/X11/H11)](https://www.supermicro.com/manuals/other/IPMI_Users_Guide.pdf)
 - [BMC resources](https://www.supermicro.com/en/solutions/management-software/bmc-resources)
 - [IPMI Utilities](https://www.supermicro.com/en/solutions/management-software/ipmi-utilities)
 - [IPMICFG download](https://www.supermicro.com/wdl/utility/IPMICFG/)
 - [IPMICFG User's Guide 1.15 ](https://www.supermicro.com/wdl/utility/IPMICFG/IPMICFG_UserGuide.pdf)

#### Forums/blogs
 - [\[STH forums\] Reference Material: Supermicro X9/X10/X11 Fan Speed Control](https://forums.servethehome.com/index.php?resources/supermicro-x9-x10-x11-fan-speed-control.20/)
   - [\[STH forums\] Addition to X9 motherboards](https://forums.servethehome.com/index.php?threads/supermicro-x9-x10-x11-fan-speed-control.10059/post-339801) 
 - [\[TrueNAS forums\] How To: Change IPMI Sensor Thresholds using ipmitool](https://www.truenas.com/community/resources/how-to-change-ipmi-sensor-thresholds-using-ipmitool.35/)
 - [\[TrueNAS forums\] Script to control fan speed in response to hard drive temperatures](https://www.truenas.com/community/threads/script-to-control-fan-speed-in-response-to-hard-drive-temperatures.41294/)
 - [\[Pcfe's blog\] Set fan thresholds on my Super Micro H11DSi-NT](https://blog.pcfe.net/hugo/posts/2018-08-14-epyc-ipmi-fans/)

#### Linux kernel
 - [coretemp] [documentation](https://www.kernel.org/doc/html/latest/hwmon/coretemp.html)
 - [drivetemp] [documentation](https://www.kernel.org/doc/html/latest/hwmon/drivetemp.html) and its [GitHub repository](https://github.com/groeck/drivetemp)
 - How to install [hddtemp](https://www.cyberciti.biz/tips/howto-monitor-hard-drive-temperature.html) from a source package

#### Similar projects
 - [\[GitHub\] Kevin Horton's nas_fan_control](https://github.com/khorton/nas_fan_control)
 - [\[GitHub\] Rob Urban's fork nas_fan control](https://github.com/roburban/nas_fan_control)
 - [\[GitHub\] sretalla's fork nas_fan control](https://github.com/sretalla/nas_fan_control)
 - [\[GitHub\] Andrew Gunnerson's ipmi-fan-control](https://github.com/chenxiaolong/ipmi-fan-control)
 - [\[GitHub\] supermicro-fancontrol by jvdillion](https://github.com/jvdillon/supermicro-fancontrol)

> Written with [StackEdit](https://stackedit.io/).
