| blob | 3003637830db7f81b06f201b2512ae1a167aa60f |
1 .\" $NetBSD: envsys.conf.5,v 1.11 2008/09/23 21:50:41 reed Exp $
2 .\"
3 .\" -
4 .\" Copyright (c) 2007, 2008 Juan Romero Pardines.
5 .\" All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 .\"
27 .\"
28 .Dd April 26, 2008
29 .Dt ENVSYS.CONF 5
30 .Os
31 .Sh NAME
32 .Nm envsys.conf
33 .Nd Configuration file for the envsys framework
34 .Sh SYNOPSIS
35 .Nm envstat
36 .Op Fl S
37 .Op Fl c Ar /etc/envsys.conf
38 .Sh DESCRIPTION
39 The
40 .Nm
41 file configures all the features provided by the
42 .Xr envsys 4
43 framework.
44 It consists of a series of device and sensor blocks.
45 Each sensor block defines a group of
46 .Em properties .
47 The file format is free-form: new line markers and indentation are
48 ignored.
49 Comments start with a
50 .Sq #
51 sign and extend until the end of line.
52 .Pp
53 A
54 .Em property
55 is like a variable assignment.
56 It has a name, which goes to the left of the equal sign, and a value,
57 which goes to the right.
58 The assignment ends with a semicolon.
59 It looks like:
60 .Pp
61 .Dl name = value;
62 .Pp
63 There is no difference between string or integer values when defining them.
64 The value must be surrounded by double quotes if it contains whitespace.
65 .Pp
66 There can be multiple groups of devices and multiple groups of sensors
67 in the configuration file.
68 .Pp
69 A device block consists of one or more sensor blocks and one or more global
70 properties.
71 It has the following syntax:
72 .Bd -literal -offset indent
73 device_name {
74 prop = value;
75 ...
76 sensor0 {
77 prop = value;
78 ...
79 }
80 ...
81 sensorN {
82 prop = value;
83 ...
84 }
85 }
86 ...
87 .Ed
88 .Pp
89 Device names are those shown by the
90 .Ql envstat -D
91 command; sensor blocks are named by the index position in which they are shown.
92 .Pp
93 For example, if we have the following output from the
94 .Xr envstat 8
95 command:
96 .Bd -literal -offset indent
97 CPU Temperature: 32.000 degC
98 MB Temperature: 37.000 degC
99 Vcore Voltage: 1.232 V
100 +3.3 Voltage: 3.248 V
101 +5 Voltage: 4.992 V
102 +12 Voltage: 11.985 V
103 CPU FAN Speed: 1250 RPM
104 .Ed
105 .Pp
106 .Ql sensor0
107 corresponds to the
108 .Em CPU Temperature
109 sensor and
110 .Ql sensor6
111 corresponds to the
112 .Em CPU FAN Speed
113 sensor.
114 .Pp
115 There is another way that will give you the correct index
116 sensor; the
117 .Ql envstat -x
118 command will print the raw XML property list.
119 You only have to find the
120 .Em index
121 object in the appropriate dictionary.
122 The object will be shown as:
123 .Bd -literal -offset indent
124 \*[Lt]key\*[Gt]index\*[Lt]/key\*[Gt]
125 \*[Lt]string\*[Gt]sensor2\*[Lt]/string\*[Gt]
126 .Ed
127 .Pp
128 Invalid sensors and devices will be detected by the
129 .Xr envstat 8
130 parser and will be reported as errors.
131 .Pp
132 The following properties are provided for sensor blocks (please note that
133 not all properties apply to all type of sensors):
134 .Bl -tag -width ident
135 .It critical-capacity = 10;
136 .Pp
137 Sets a critical capacity limit property of 10
138 percent in a battery sensor.
139 Battery sensors are those that report a percentage from the
140 .Xr envstat 8
141 output.
142 .Pp
143 It is possible to find out if the sensor accepts this property
144 by running
145 .Ql envstat -x
146 and looking if the
147 .Em want-percentage
148 object is defined as
149 .Em true
150 on its dictionary.
151 For example:
152 .Bd -literal -offset indent
153 \*[Lt]key\*[Gt]want-percentage\*[Lt]/key\*[Gt]
154 \*[Lt]true/\*[Gt]
155 .Ed
156 .Pp
157 Only a value between 0 and 100 is allowed.
158 When the limit is reached in the sensor, a
159 .Em user-capacity
160 event will be sent to the
161 .Xr powerd 8
162 daemon (if running) and will execute the block for this event in
163 .Pa /etc/powerd/scripts/sensor_battery .
164 .Pp
165 If this property is set, its value will be shown in the
166 .Xr envstat 8
167 display output with a column named
168 .Ar CritCap .
169 .It warning-capacity = 20;
170 .Pp
171 Sets a warning capacity limit property of 20
172 percent in a battery sensor.
173 Battery sensors are those that report a percentage from the
174 .Xr envstat 8
175 output.
176 .Pp
177 It is possible to find out if the sensor accepts this property
178 by running
179 .Ql envstat -x
180 and looking if the
181 .Em want-percentage
182 object is defined as
183 .Em true
184 on its dictionary.
185 For example:
186 .Bd -literal -offset indent
187 \*[Lt]key\*[Gt]want-percentage\*[Lt]/key\*[Gt]
188 \*[Lt]true/\*[Gt]
189 .Ed
190 .Pp
191 Only a value between 0 and 100 is allowed.
192 When the limit is reached in the sensor, a
193 .Em user-warn-capacity
194 event will be sent to the
195 .Xr powerd 8
196 daemon (if running) and will execute the block for this event in
197 .Pa /etc/powerd/scripts/sensor_battery .
198 .Pp
199 If this property is set, its value will be shown in the
200 .Xr envstat 8
201 display output with a column named
202 .Ar WarnCap
203 when the
204 .Fl -W
205 option is specified.
206 .It critical-max = 70C;
207 .Pp
208 Sets a critical maximum limit property in a sensor.
209 Note that in this example, we are specifying the
210 .Ql C
211 keyword at the end; that means that this will only be valid for
212 .Em temperature
213 sensors and that the value is specified as degrees
214 .Em Celsius .
215 If degrees Fahrenheit are wanted, just change use the letter
216 .Em F ,
217 like:
218 .Bd -literal -offset indent
219 critical-max = 140F;
220 .Ed
221 .Pp
222 To know sensor type, you have to look at the
223 .Em type
224 object in the XML property list.
225 Remember: the XML property list has
226 all the information that the application uses to print the values!
227 .Pp
228 Other sensors that are not of
229 .Em temperature
230 type must not include the final character for the unit.
231 A dot is allowed in the value, if it corresponds to the
232 range that the sensor is reporting.
233 When the limit has been reached in the sensor, a
234 .Em critical-over
235 event will be sent to the
236 .Xr powerd 8
237 daemon (if running) and will execute the block for this event in
238 the appropriate
239 .Pa /etc/powerd/scripts/sensor_foo
240 script (depending on the sensor's type).
241 .Pp
242 Please note that this property cannot be set in battery sensors
243 (those that have the
244 .Em want-percentage
245 object in their dictionary).
246 This rule applies for the
247 .Ql critical-min ,
248 .Ql warning-max ,
249 and
250 .Ql warning-min
251 properties too.
252 .Pp
253 If this property is set, its value will be shown in the
254 .Xr envstat 8
255 display output with a column named
256 .Ar CritMax
257 unless the
258 .Fl W
259 option is specified.
260 .It critical-min = 1.230;
261 .Pp
262 Sets a critical minimum limit property in a sensor.
263 The rules for
264 .Em critical-max ,
265 .Em critical-min ,
266 .Em warning-max ,
267 and
268 .Em warning-min
269 are the same.
270 When the limit has been reached in the sensor, a
271 .Em critical-under
272 event will be sent to the
273 .Xr powerd 8
274 daemon (if running) and will execute the block for this event in
275 the appropriate
276 .Pa /etc/powerd/scripts/sensor_foo
277 script (depending on the sensor's type).
278 .Pp
279 If this property is set, its value will be shown in the
280 .Xr envstat 8
281 display output with a column named
282 .Ar CritMin .
283 .It warning-max = 70C;
284 .Pp
285 Sets a warning maximum limit property in a sensor.
286 The rules for
287 .Em critical-max ,
288 .Em critical-min ,
289 .Em warning-max ,
290 and
291 .Em warning-min
292 are the same.
293 When the limit has been reached in the sensor, a
294 .Em warning-over
295 event will be sent to the
296 .Xr powerd 8
297 daemon (if running) and will execute the block for this event in
298 the appropriate
299 .Pa /etc/powerd/scripts/sensor_foo
300 script (depending on the sensor's type).
301 .Pp
302 Please note that this property cannot be set in battery sensors
303 (those that have the
304 .Em want-percentage
305 object in their dictionary).
306 This rule applies for the
307 .Ql warning-min
308 property too.
309 .Pp
310 If this property is set, its value will be shown in the
311 .Xr envstat 8
312 display output with a column named
313 .Ar WarnMax
314 if the
315 .Fl W
316 flag is specified.
317 .It warning-min = 1.230;
318 .Pp
319 Sets a critical minimum limit property in a sensor.
320 The rules for
321 .Em critical-max ,
322 .Em critical-min ,
323 .Em warning-max ,
324 and
325 .Em warning-min
326 are the same.
327 When the limit has been reached in the sensor, a
328 .Em warning-under
329 event will be sent to the
330 .Xr powerd 8
331 daemon (if running) and will execute the block for this event in
332 the appropriate
333 .Pa /etc/powerd/scripts/sensor_foo
334 script (depending on the sensor's type).
335 .Pp
336 If this property is set, its value will be shown in the
337 .Xr envstat 8
338 display output with a column named
339 .Ar WarnMin
340 if the
341 .Fl W
342 option is specified.
343 .It description = string
344 .Pp
345 Sets a new description in a sensor.
346 You can set this property in
347 all sensors, except that you won't be able to set a description
348 that is currently used for the specified device.
349 .It rfact = 56000
350 .Pp
351 Sets a new resistor factor property in a sensor.
352 This property is only allowed in
353 .Em Voltage
354 sensors and
355 .Em only
356 if the driver has enabled the appropriate flag for the mentioned
357 sensor.
358 The resistor factor may be used to change the behavior
359 of the value returned by the driver.
360 .Pp
361 If a sensor supports this, the
362 .Em allow-rfact
363 object appears enabled (true) in the dictionary.
364 .El
365 .Pp
366 The following properties are available for device blocks:
367 .Bl -tag -width ident
368 .It refresh-timeout = 10s
369 .Pp
370 This property sets the refresh timeout value in a driver, and will be used
371 to refresh data and check for critical conditions any time the timeout
372 is met.
373 The value may be specified in seconds, minutes or hours.
374 To specify the value in seconds, the
375 .Em s
376 character must be appended last, if minutes is desired, a
377 .Em m
378 and a
379 .Em h
380 for hours.
381 For example
382 .Em 10s
383 for 10 seconds or
384 .Em 1h
385 for one hour.
386 .El
387 .Sh FILES
388 .Bl -tag -width /etc/envsys.conf -compact
389 .It Pa /etc/envsys.conf
390 Default configuration file.
391 .El
392 .Sh SEE ALSO
393 .Xr proplib 3 ,
394 .Xr envstat 8 ,
395 .Xr powerd 8
396 .Sh HISTORY
397 The
398 .Nm
399 configuration file first appeared in
400 .Nx 5.0 .