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* [set_func_on_present](set_func_on_present.md) - Optional, default = false
151* [sensors](sensors.md)
152
153Trust group attributes: **(Optional)**
154* [class](class.md)
155* [group](group.md)
156
157Fault handling attributes: **(Optional)**
158* [num_nonfunc_rotors_before_error](num_nonfunc_rotors_before_error.md) -
159Optional, default = 1
160* [power_off_config](power_off_config.md) - Optional
161
162*-See attribute page for more details
163
164### Comments
165
166The JSON data format does not support comments. However, an optional `comments`
167attribute name can be used to annotate any specific entry of the JSON
168configuration. It is suggested that the value of this `comments` attribute be
169an array of strings for comments containing line breaks. All `comments` objects
170are ignored when the JSON configuration is processed.
171
172***Note: Only 1 `comments` object can exist at any given 'layer' of the
173configuration hierarchy***
174
175Example:
176```
177{
178  "comments": [
179   "Fan monitoring configuration of X-number of fans",
180   "Where some fan sensors are not trusted at times",
181   "Faults create error logs and power off the system"
182  ],
183  "fans": [
184    {
185      "comments": "Monitor this fan",
186      ...
187    },
188    .
189    .
190    .
191  ],
192  "sensor_trust_groups": [
193    {
194      "comments": "Only trust these fan sensors when all are not zero",
195      ...
196    },
197    .
198    .
199    .
200  ],
201  "fault_handling": {
202    "comments": "Log errors and power off the system",
203    ...
204  }
205}
206```
207
208## Validation
209
210TBD
211
212
213## Firmware Updates
214
215When a new firmware image is installed on the BMC, it will update the config
216file in the standard directory.
217
218The override directory will **not** be modified by a firmware update. If a
219config file exists in the override directory, it will continue to be used as
220the fan presence configuration instead of the config file located under the
221appropriate location within the supported directory.
222
223
224## Loading and Reloading
225
226The config file is loaded when the `phosphor-fan-monitor` application
227starts.
228
229To force the application to reload the config file, use the following command
230on the BMC:
231
232`systemctl kill -s HUP phosphor-fan-monitor@0.service`
233
234To confirm which config file was loaded, use the following command on the BMC:
235
236`journalctl -u phosphor-fan-monitor@0.service | grep Loading`
237