usr.sbin/sensorsd/sensorsd.conf.5

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