1.\" $OpenBSD: sensorsd.conf.5,v 1.29 2020/02/10 13:18:22 schwarze Exp $ 2.\" 3.\" Copyright (c) 2003 Henning Brauer <henning@openbsd.org> 4.\" Copyright (c) 2005 Matthew Gream <matthew.gream@pobox.com> 5.\" Copyright (c) 2007 Constantine A. Murenin <cnst@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: February 10 2020 $ 20.Dt SENSORSD.CONF 5 21.Os 22.Sh NAME 23.Nm sensorsd.conf 24.Nd configuration file for sensorsd 25.Sh DESCRIPTION 26The 27.Nm 28file is read by 29.Xr sensorsd 8 30to configure hardware sensor monitoring. 31Each variable in the 32.Xr sysctl 2 33.Va hw.sensors 34subtree represents a sensor. 35Each sensor is matched by at most one entry in 36.Nm , 37which may specify high and low limits, 38and whether sensor status changes provided by the driver should be ignored. 39Each time the limits are crossed in either direction 40or the status provided by the driver changes, 41.Xr sensorsd 8 Ns 's 42alert functionality is triggered and a command, if specified, is 43executed. 44.Pp 45.Nm 46follows the syntax of configuration databases as documented in 47.Xr cgetent 3 . 48Sensors may be specified by their full 49.Va hw.sensors 50.Xr sysctl 8 51variable name or by type, 52with the full name taking precedence. 53For example, if an entry 54.Dq hw.sensors.lm0.temp1 55is not found, then an entry for 56.Dq temp 57will instead be looked for. 58.Pp 59The following attributes may be used: 60.Pp 61.Bl -tag -width "commandXX" -offset indent -compact 62.It Li command 63Specify a command to be executed on state change. 64.It Li high 65Specify the largest acceptable value. 66.It Li low 67Specify the smallest acceptable value. 68.It Li istatus 69Ignore status provided by the driver. 70.El 71.Pp 72The values for temperature sensors can be given in degrees Celsius or 73Fahrenheit, for voltage sensors in volts, and fan speed sensors take a 74unit-less number representing RPM. 75For Boolean sensors, specify 0 for 76.Qq Off 77or 1 for 78.Qq On . 79Values for all other types of sensors can be specified 80in the same units as they appear under the 81.Xr sysctl 8 82.Va hw.sensors 83tree. 84.Pp 85Sensors that provide status (such as those from 86.Xr bio 4 , 87.Xr esm 4 , 88or 89.Xr ipmi 4 ) 90do not require boundary values specified 91and simply trigger on status transitions. 92If boundaries are specified nonetheless, 93then they are used in addition to automatic status monitoring, 94unless the 95.Dq istatus 96attribute is specified to ignore status values that are provided by the drivers. 97.Pp 98The command is executed when there is any change in sensor state. 99Tokens in the command are substituted as follows: 100.Pp 101.Bl -tag -width Ds -offset indent -compact 102.It %l 103Whether the value exceeds or is within the user specified limits. 104Can be one of: "below", "above", "within", "invalid", or "uninitialised". 105.It %n 106The sensor number. 107.It %s 108The sensor status. 109.It %x 110The xname of the device the sensor sits on. 111.It %t 112The type of sensor. 113.It %2 114The sensor's current value. 115.It %3 116The sensor's low limit. 117.It %4 118The sensor's high limit. 119.El 120.Pp 121For Boolean sensors, %2, %3, and %4 are substituted with 122.Qq On 123or 124.Qq Off . 125.Pp 126By default, 127.Xr sensorsd 8 128monitors status changes on all sensors that keep their state. 129This behaviour may be altered by using the 130.Dq istatus 131attribute to ignore 132status changes of sensors of a certain type 133or individual sensors. 134.Sh FILES 135.Bl -tag -width /etc/examples/sensorsd.conf -compact 136.It Pa /etc/sensorsd.conf 137Configuration file for 138.Xr sensorsd 8 . 139.It Pa /etc/examples/sensorsd.conf 140Example configuration file. 141.El 142.Sh EXAMPLES 143In the following configuration file, 144if hw.sensors.ipmi0.temp0 moves upwards beyond 80C 145or downwards to 80C or less or if its status as provided by 146.Xr ipmi 4 147changes, the command 148.Pa /etc/sensorsd/log_warning 149will be executed, 150with the sensor type, number and current value passed to it. 151Alerts will be sent 152if hw.sensors.lm0.volt3 moves into or out of 153the range from 4.8V to 5.2V, inclusive; 154if the speed of the fan attached to hw.sensors.lm0.fan1 155transitions to being below or above 1000RPM; 156if any RAID volume drive 157changes its status from, for example, 158.Dq OK , 159such as in the case of drive failure, rebuild, or a complete failure, 160the command 161.Pa /etc/sensorsd/drive 162will be executed, with the sensor number passed to it; however, 163no alerts will be generated for status changes on timedelta sensors. 164For all other sensors whose drivers automatically provide 165sensor status updates, alerts will be generated 166each time those sensors undergo status transitions. 167.Bd -literal -offset indent 168# Comments are allowed 169hw.sensors.ipmi0.temp0:high=80C:command=/etc/sensorsd/log_warning %t %n %2 170hw.sensors.lm0.volt3:low=4.8V:high=5.2V 171hw.sensors.lm0.fan1:low=1000 172drive:command=/etc/sensorsd/drive %n 173timedelta:istatus #ignore status changes for timedelta 174.Ed 175.Sh SEE ALSO 176.Xr cgetent 3 , 177.Xr bio 4 , 178.Xr ipmi 4 , 179.Xr sensorsd 8 , 180.Xr sysctl 8 181.Sh HISTORY 182The 183.Nm 184file format first appeared in 185.Ox 3.5 . 186The format was altered in 187.Ox 4.1 188to accommodate hierarchical device-based sensor addressing. 189The 190.Dq istatus 191attribute was introduced in 192.Ox 4.2 . 193.Sh CAVEATS 194Alert functionality is triggered every time there is a change in sensor state; 195for example, when 196.Xr sensorsd 8 197is started, 198the status of each monitored sensor changes 199from undefined to whatever it is. 200One must keep this in mind when using commands 201that may unconditionally perform adverse actions (e.g.\& 202.Xr shutdown 8 ) , 203as they will be executed even when all sensors perform to specification. 204If this is undesirable, then a wrapper shell script should be used instead. 205