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