usr.sbin/sensorsd/sensorsd.conf.5

   1 .\" $OpenBSD: sensorsd.conf.5,v 1.23 2008/03/15 01:08:08 cnst Exp $
   2 .\" $DragonFly: src/usr.sbin/sensorsd/sensorsd.conf.5,v 1.5 2008/11/02 18:29:07 swildner 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@openbsd.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 October 19, 2008
  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 Ap s
  39 alert functionality is triggered and a command, if specified, is
  40 executed.
  41 .Pp
  42 The
  43 .Nm
  44 file follows the syntax of configuration databases as documented in
  45 .Xr getcap 3 .
  46 Sensors may be specified by their full
  47 .Va hw.sensors
  48 .Xr sysctl 8
  49 variable name or by type,
  50 with the full name taking precedence.
  51 For example, if an entry
  52 .Va hw.sensors.lm0.temp1
  53 is not found, then an entry for
  54 .Dq Li temp
  55 will instead be looked for.
  56 .Pp
  57 The following attributes may be used:
  58 .Pp
  59 .Bl -tag -width ".Li command" -offset indent -compact
  60 .It Li command
  61 Specify a command to be executed on state change.
  62 .It Li high
  63 Specify an upper limit.
  64 .It Li low
  65 Specify a lower limit.
  66 .It Li istatus
  67 Ignore status provided by the driver.
  68 .El
  69 .Pp
  70 The values for temperature sensors can be given in degrees Celsius or
  71 Fahrenheit, for voltage sensors in volts, and fan speed sensors take a
  72 unit-less number representing RPM.
  73 Values for all other types of sensors can be specified
  74 in the same units as they appear under the
  75 .Xr sysctl 8
  76 .Va hw.sensors
  77 tree.
  78 .Pp
  79 Sensors that provide status
  80 do not require boundary values specified
  81 and simply trigger on status transitions.
  82 If boundaries are specified nonetheless,
  83 then they are used in addition to automatic status monitoring,
  84 unless the
  85 .Dq Li istatus
  86 attribute is specified to ignore status values that are provided by the drivers.
  87 .Pp
  88 The command is executed when there is any change in sensor state.
  89 Tokens in the command are substituted as follows:
  90 .Pp
  91 .Bl -tag -width indent -offset indent -compact
  92 .It Li %l
  93 Whether the value exceeds or is within the user specified limits.
  94 Can be one of: "below", "above", "within", "invalid", or "uninitialised".
  95 .It Li %n
  96 The sensor number.
  97 .It Li %s
  98 The sensor status.
  99 .It Li %x
 100 The
 101 .Va xname
 102 of the device the sensor sits on.
 103 .It Li %t
 104 The type of sensor.
 105 .It Li %2
 106 The sensor's current value.
 107 .It Li %3
 108 The sensor's low limit.
 109 .It Li %4
 110 The sensor's high limit.
 111 .El
 112 .Pp
 113 By default,
 114 .Xr sensorsd 8
 115 monitors status changes on all sensors that keep their state.
 116 This behaviour may be altered by using the
 117 .Dq Li istatus
 118 attribute to ignore
 119 status changes of sensors of a certain type
 120 or individual sensors.
 121 .Sh FILES
 122 .Bl -tag -width ".Pa /etc/sensorsd.conf"
 123 .It Pa /etc/sensorsd.conf
 124 Configuration file for
 125 .Xr sensorsd 8 .
 126 .El
 127 .Sh EXAMPLES
 128 In the following configuration file,
 129 if
 130 .Va hw.sensors.lm0.temp0
 131 transitions 80C, the command
 132 .Pa /etc/sensorsd/log_warning
 133 will be executed,
 134 with the sensor type, number and current value passed to it.
 135 Alerts will be sent
 136 if
 137 .Va hw.sensors.lm0.volt3
 138 transitions to being within or outside
 139 a range of 4.8V and 5.2V;
 140 if the speed of the fan attached to
 141 .Va hw.sensors.lm0.fan1
 142 transitions to being below or above 1000RPM;
 143 however, no alerts will be generated for status changes on
 144 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.lm0.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 timedelta:istatus       #ignore status changes for timedelta
 154 .Ed
 155 .Sh SEE ALSO
 156 .Xr getcap 3 ,
 157 .Xr lm 4 ,
 158 .Xr sensorsd 8 ,
 159 .Xr sysctl 8
 160 .Sh HISTORY
 161 The
 162 .Nm
 163 file format first appeared in
 164 .Ox 3.5 .
 165 The format was altered in
 166 .Ox 4.1
 167 to accommodate hierarchical device-based sensor addressing.
 168 The
 169 .Dq Li istatus
 170 attribute was introduced in
 171 .Ox 4.2 .
 172 .Sh CAVEATS
 173 Alert functionality is triggered every time there is a change in sensor state;
 174 for example, when
 175 .Xr sensorsd 8
 176 is started,
 177 the status of each monitored sensor changes
 178 from undefined to whatever it is.
 179 One must keep this in mind when using commands
 180 that may unconditionally perform adverse actions (e.g.\&
 181 .Xr shutdown 8 ) ,
 182 as they will be executed even when all sensors perform to specification.
 183 If this is undesirable, then a wrapper shell script should be used instead.