1# Fan Monitor Configuration File 2 3## Table of Contents 4* [Overview](#overview) 5* [Data Format](#data-format) 6* [Example](#example) 7* [System Config Location](#system-config-location) 8* [Contents](#contents) 9* [Validation](#validation) 10* [Firmware Updates](#firmware-updates) 11* [Loading and Reloading](#loading-and-reloading) 12 13 14## Overview 15 16The `phosphor-fan-monitor` application is controlled by a configuration 17file (config file) to manage the `Functional` property's state on the 18`xyz.openbmc_project.State.Decorator.OperationalStatus` interface for fan 19inventory objects. The config file defines the method to use in determining the 20functional state and the logging of errors for each fan within a machine. It 21also provides the ability to adjust the determination of a fan being 22non-functional due to fan hardware limitations. 23 24 25## Data Format 26 27The config file is written using the [JSON (JavaScript Object 28Notation)](https://www.json.org/) data format and can be created using a text 29editor. 30 31 32## Example 33 34See [config.json](../../monitor/example/config.json). 35 36 37## System Config Location 38 39The config file name is `config.json`. 40 41### Supported Directory 42 43`/usr/share/phosphor-fan-presence/monitor/` 44 45The supported version of the config file is installed under this read-only 46directory location as part of the firmware image install. This is where the 47config file will be loaded from when no overriding config file exists. 48 49#### Default Location 50 51Where a single config file for 1-or-more system types can be used, 52the config file can be located at the base of the supported directory. 53 54i.e.) `/usr/share/phosphor-fan-presence/monitor/config.json` 55 56#### Compatible System Type Location 57 58The config file location can also be based on a system type. This is necessary 59where more than one type of machine is supported in a single BMC firmware image 60and those system types can not share a common config file. 61 62A system type sub-directory can be obtained from the `IBMCompatibleSystem` 63D-Bus interface's `Names` property. The `Names` property contains a list of one 64or more compatible system types, ordered from most specific to the most general. 65 66Example: 67* `ibm,rainier-2u` 68* `ibm,rainier` 69 70The `phosphor-fan-monitor` application then traverses the supported 71directory, appending each compatible system type entry as a sub-directory from 72most specific to most general until the config file is found. 73 74Example: 751. `/usr/share/phosphor-fan-presence/monitor/ibm,rainier-2u/` 76 * (directory/config file does not exist) 772. `/usr/share/phosphor-fan-presence/monitor/ibm,rainier/config.json` 78 * (config file found) 79 80If a config file is not found and the machine is powered on, an error is logged 81and `phosphor-fan-monitor` application terminates preventing the machine 82from successfully powering on. 83 84### Override Directory 85 86`/etc/phosphor-fan-presence/monitor/` 87 88A different version of the config file can be loaded by placing it into this 89writable directory location. This avoids the need to build and install a new 90firmware image on the BMC when changing the configuration, such as for testing 91purposes. 92 93The override directory may not exist on the BMC, therefore to be able to use 94an overriding config file it must be created using the following command: 95 96`mkdir -p /etc/phosphor-fan-presence/monitor` 97 98### Search Order 99 100The `phosphor-fan-monitor` application will search for the config file at 101the directory locations in the following order: 1021. Override directory 1032. Supported directory 104 * Default location 105 * Compatible System Type location 106 107 108## Contents 109 110### Structure 111 112The config file consists of an array of fan objects that define how to monitor 113their functional state and what fault handling should occur. Fault handling 114includes creating error logs and/or powering off the system for a configured 115number of fans that are missing or nonfunctional. 116``` 117{ 118 "fans": [ 119 { 120 ... 121 }, 122 . 123 . 124 . 125 ], 126 "sensor_trust_groups": [ 127 { 128 ... 129 }, 130 . 131 . 132 . 133 ], 134 "fault_handling": { 135 ... 136 } 137} 138``` 139 140### Syntax 141 142Fan object attributes: **(Required unless otherwise noted)** 143* [inventory](inventory.md) 144* [method](method.md) - *Optional, default = "timebased" 145* [deviation](deviation.md) 146* [num_sensors_nonfunc_for_fan_nonfunc](num_sensors_nonfunc_for_fan_nonfunc.md) - Optional, default = 0 147* [monitor_start_delay](monitor_start_delay.md) - Optional, default = 0 148* [fan_missing_error_delay](fan_missing_error_delay.md) - Optional 149* [nonfunc_rotor_error_delay](nonfunc_rotor_error_delay.md) - Optional 150* [sensors](sensors.md) 151 152Trust group attributes: **(Optional)** 153* [class](class.md) 154* [group](group.md) 155 156Fault handling attributes: **(Optional)** 157* [num_nonfunc_rotors_before_error](num_nonfunc_rotors_before_error.md) - 158Optional, default = 1 159* [power_off_config](power_off_config.md) - Optional 160 161*-See attribute page for more details 162 163### Comments 164 165The JSON data format does not support comments. However, an optional `comments` 166attribute name can be used to annotate any specific entry of the JSON 167configuration. It is suggested that the value of this `comments` attribute be 168an array of strings for comments containing line breaks. All `comments` objects 169are ignored when the JSON configuration is processed. 170 171***Note: Only 1 `comments` object can exist at any given 'layer' of the 172configuration hierarchy*** 173 174Example: 175``` 176{ 177 "comments": [ 178 "Fan monitoring configuration of X-number of fans", 179 "Where some fan sensors are not trusted at times", 180 "Faults create error logs and power off the system" 181 ], 182 "fans": [ 183 { 184 "comments": "Monitor this fan", 185 ... 186 }, 187 . 188 . 189 . 190 ], 191 "sensor_trust_groups": [ 192 { 193 "comments": "Only trust these fan sensors when all are not zero", 194 ... 195 }, 196 . 197 . 198 . 199 ], 200 "fault_handling": { 201 "comments": "Log errors and power off the system", 202 ... 203 } 204} 205``` 206 207## Validation 208 209TBD 210 211 212## Firmware Updates 213 214When a new firmware image is installed on the BMC, it will update the config 215file in the standard directory. 216 217The override directory will **not** be modified by a firmware update. If a 218config file exists in the override directory, it will continue to be used as 219the fan presence configuration instead of the config file located under the 220appropriate location within the supported directory. 221 222 223## Loading and Reloading 224 225The config file is loaded when the `phosphor-fan-monitor` application 226starts. 227 228To force the application to reload the config file, use the following command 229on the BMC: 230 231`systemctl kill -s HUP phosphor-fan-monitor@0.service` 232 233To confirm which config file was loaded, use the following command on the BMC: 234 235`journalctl -u phosphor-fan-monitor@0.service | grep Loading` 236