1bmc-watchdog(8)                 System Commands                bmc-watchdog(8)
2
3
4

NAME

6       bmc-watchdog - BMC watchdog timer daemon and control utility
7

SYNOPSIS

9       bmc-watchdog command [OPTION...] [COMMAND_OPTIONS...]
10

DESCRIPTION

12       Bmc-watchdog  controls a Baseboard Management Controller (BMC) watchdog
13       timer. The bmc-watchdog tool typically executes as a cronjob or  daemon
14       to  manage the watchdog timer. A user must be root in order to run bmc-
15       watchdog.
16
17       Listed below are bmc-watchdog details, option  details,  examples,  and
18       known  issues.  For  a  general  introduction  to  FreeIPMI  please see
19       freeipmi(7).
20

BMC WATCHDOG DETAILS

22       A BMC watchdog timer is part of  the  Intelligent  Platform  Management
23       Interface  (IPMI)  specification and is only available to BMCs that are
24       compliant with IPMI. When a BMC watchdog timer is  started,  it  begins
25       counting  down  to  zero from some positive number of seconds. When the
26       timer hits zero, the timer will execute  a  pre-configured  pre-timeout
27       interrupt and/or timeout action.
28
29       In order to stop the pre-timeout interrupt or timeout action from being
30       executed, the watchdog timer must be periodically  reset  back  to  its
31       initial beginning value.
32
33       The  BMC  watchdog timer automatically stops itself when the machine is
34       rebooted. Therefore, when a machine is brought  up,  the  BMC  watchdog
35       timer must be setup again before it can be used.
36
37       Typically,  a  BMC  watchdog  timer  is  used  to automatically reset a
38       machine that has crashed. When the operating system  first  starts  up,
39       the BMC timer is set to its initial countdown value. At periodic inter‐
40       vals, when the operating system is functioning properly,  the  watchdog
41       timer  can  be  reset by the OS or a userspace program. Thus, the timer
42       never counts down to zero. When the system crashes, the timer cannot be
43       reset by the OS or userspace program. Eventually, the timer will count‐
44       down to zero and reset the machine.
45
46       See EXAMPLES below for examples of how bmc-watchdog is commonly used.
47

COMMANDS

49       The following commands are available to bmc-watchdog.
50
51       -s, --set
52              Set BMC Watchdog Configuration. BMC watchdog timer configuration
53              values  can  be  set  using the set command options listed below
54              under SET OPTIONS. If a particular  configuration  parameter  is
55              not  specified on the command line, the current configuration of
56              that parameter will not be changed.
57
58       -g, --get
59              Get BMC Watchdog Configuration and State. The current configura‐
60              tion and state is printed to standard output.
61
62       -r, --reset
63              Reset BMC Watchdog Timer.
64
65       -t, --start
66              Start BMC Watchdog Timer. Does nothing if the timer is currently
67              running. Identical to --reset command when the timer is  stopped
68              with  the  exception  of  the start command options listed below
69              under START OPTIONS.
70
71       -y, --stop
72              Stop BMC Watchdog Timer. Stops the current timer.
73
74       -c, --clear
75              Clear BMC Watchdog Configuration. Clears all configuration  val‐
76              ues  for the watchdog timer, except for timer use, which is kept
77              at its current value.
78
79       -d, --daemon
80              Run bmc-watchdog as a daemon. Configurable  BMC  watchdog  timer
81              options are listed below under DAEMON OPTIONS. The configuration
82              values are set once, then the daemon will  reset  the  timer  at
83              specified  periodic  intervals.  The daemon can be stopped using
84              the  --stop  command,  --clear  command,  or  by   setting   the
85              stop_timer flag on the --set command.
86

GENERAL OPTIONS

88       The following options are general options for configuring IPMI communi‐
89       cation and executing general tool commands.  These options are  generic
90       and can be used by any command.
91
92       -D IPMIDRIVER, --driver-type=IPMIDRIVER
93              Specify  the  driver type to use instead of doing an auto selec‐
94              tion.  The currently available inband  drivers  are  KCS,  SSIF,
95              OPENIPMI, SUNBMC, and INTELDCMI.
96
97       --disable-auto-probe
98              Do not probe in-band IPMI devices for default settings.
99
100       --driver-address=DRIVER-ADDRESS
101              Specify  the  in-band  driver  address to be used instead of the
102              probed value. DRIVER-ADDRESS should be prefixed with "0x" for  a
103              hex value and '0' for an octal value.
104
105       --driver-device=DEVICE
106              Specify the in-band driver device path to be used instead of the
107              probed path.
108
109       --register-spacing=REGISTER-SPACING
110              Specify the in-band  driver  register  spacing  instead  of  the
111              probed  value. Argument is in bytes (i.e. 32bit register spacing
112              = 4)
113
114       --target-channel-number=CHANNEL-NUMBER
115              Specify the in-band driver target channel number  to  send  IPMI
116              requests to.
117
118       --target-slave-address=SLAVE-ADDRESS
119              Specify  the  in-band  driver  target  slave number to send IPMI
120              requests to.
121
122       -v, --verbose-logging
123              Increase verbosity of logging.
124
125       -n, --no-logging
126              Turns off all logging done by bmc-watchdog.
127
128       --config-file=FILE
129              Specify an alternate configuration file.
130
131       -W WORKAROUNDS, --workaround-flags=WORKAROUNDS
132              Specify workarounds to vendor compliance issues. Multiple  work‐
133              arounds  can be specified separated by commas. A special command
134              line flag of "none", will indicate no workarounds (may be useful
135              for overriding configured defaults). See WORKAROUNDS below for a
136              list of available workarounds.
137
138       --debug
139              Turn on debugging.
140
141       -?, --help
142              Output a help list and exit.
143
144       --usage
145              Output a usage message and exit.
146
147       -V, --version
148              Output the program version and exit.
149

SET OPTIONS

151       The following options can be used by the set command to  set  or  clear
152       various BMC watchdog configuration parameters.
153
154       -u INT, --timer-use=INT
155              Set timer use. The timer use value can be set to one of the fol‐
156              lowing: 1 = BIOS FRB2, 2 = BIOS POST, 3 = OS_LOAD, 4 = SMS OS, 5
157              = OEM.
158
159       -m INT, --stop-timer=INT
160              Set  Stop  Timer  Flag.  A flag value of 0 stops the current BMC
161              watchdog timer. A value of 1 doesn't turn off the current watch‐
162              dog timer.
163
164       -l INT, --log=INT
165              Set  Log  Flag. A flag value of 0 turns logging on. A value of 1
166              turns logging off.
167
168       -a INT, --timeout-action=INT
169              Set timeout action. The timeout action can be set to one of  the
170              following:  0  =  No action, 1 = Hard Reset, 2 = Power Down, 3 =
171              Power Cycle.
172
173       -p INT, --pre-timeout-interrupt=INT
174              Set pre-timeout interrupt. The pre timeout interrupt can be  set
175              to one of the following: 0 = None, 1 = SMI, 2 = NMI, 3 = Messag‐
176              ing Interrupt.
177
178       -z SECONDS, --pre-timeout-interval=SECONDS
179              Set pre-timeout interval in seconds.
180
181       -F, --clear-bios-frb2
182              Clear BIOS FRB2 Timer Use Flag.
183
184       -P, --clear-bios-post
185              Clear BIOS POST Timer Use Flag.
186
187       -L, --clear-os-load
188              Clear OS Load Timer Use Flag.
189
190       -S, --clear-sms-os
191              Clear SMS/OS Timer Use Flag.
192
193       -O, --clear-oem
194              Clear OEM Timer Use Flag.
195
196       -i SECONDS, --initial-countdown=SECONDS
197              Set initial countdown in seconds.
198
199       -w, --start-after-set
200              Start timer after set command if timer is stopped. This is typi‐
201              cally  used  when bmc-watchdog is used as a cronjob. This can be
202              used to automatically start the timer after it has been set  the
203              first time.
204
205       -x, --reset-after-set
206              Reset timer after set command if timer is running.
207
208       -j, --start-if-stopped
209              Don't execute set command if timer is stopped, just start timer.
210
211       -k, --reset-if-running
212              Don't execute set command if timer is running, just reset timer.
213              This is typically used when bmc-watchdog is used as  a  cronjob.
214              This  can be used to reset the timer after it has been initially
215              started.
216

START OPTIONS

218       The following options can be used by the start command.
219
220       -G INT, --gratuitous-arp=INT
221              Suspend or don't suspend gratuitous ARPs while the BMC timer  is
222              running.  A flag value of 1 suspends gratuitous ARPs. A value of
223              0 will not suspend gratuitous ARPs. If this option is not speci‐
224              fied, gratuitous ARPs will not be suspended.
225
226       -A INT, --arp-response=INT
227              Suspend  or  don't suspend BMC-generated ARP responses while the
228              BMC timer is running. A flag value of 1 suspends ARP  responses.
229              A  value  of 0 will not suspend ARP responses. If this option is
230              not specified, ARP responses will not be suspended.
231

DAEMON OPTIONS

233       The following options can be used by the daemon command to set the ini‐
234       tial BMC watchdog configuration parameters.
235
236       -u INT, --timer-use=INT
237              Set timer use. The timer use value can be set to one of the fol‐
238              lowing: 1 = BIOS FRB2, 2 = BIOS POST, 3 = OS_LOAD, 4 = SMS OS, 5
239              = OEM.
240
241       -l INT, --log=INT
242              Set  Log  Flag. A flag value of 0 turns logging on. A value of 1
243              turns logging off.
244
245       -a INT, --timeout-action=INT
246              Set timeout action. The timeout action can be set to one of  the
247              following:  0  =  No action, 1 = Hard Reset, 2 = Power Down, 3 =
248              Power Cycle.
249
250       -p INT, --pre-timeout-interrupt=INT
251              Set pre-timeout interrupt. The pre timeout interrupt can be  set
252              to one of the following: 0 = None, 1 = SMI, 2 = NMI, 3 = Messag‐
253              ing Interrupt.
254
255       -z SECONDS, --pre-timeout-interval=SECONDS
256              Set pre-timeout interval in seconds.
257
258       -F, --clear-bios-frb2
259              Clear BIOS FRB2 Timer Use Flag.
260
261       -P, --clear-bios-post
262              Clear BIOS POST Timer Use Flag.
263
264       -L, --clear-os-load
265              Clear OS Load Timer Use Flag.
266
267       -S, --clear-sms-os
268              Clear SMS/OS Timer Use Flag.
269
270       -O, --clear-oem
271              Clear OEM Timer Use Flag.
272
273       -i SECONDS, --initial-countdown=SECONDS
274              Set initial countdown in seconds.
275
276       -G INT, --gratuitous-arp=INT
277              Suspend or don't suspend gratuitous ARPs while the BMC timer  is
278              running.  A flag value of 1 suspends gratuitous ARPs. A value of
279              0 will not suspend gratuitous ARPs. If this option is not speci‐
280              fied, gratuitous ARPs will not be suspended.
281
282       -A INT, --arp-response=INT
283              Suspend  or  don't suspend BMC-generated ARP responses while the
284              BMC timer is running. A flag value of 1 suspends ARP  responses.
285              A  value  of 0 will not suspend ARP responses. If this option is
286              not specified, ARP responses will not be suspended.
287
288       -e, --reset-period
289              Time interval to wait before resetting timer. The default is  60
290              seconds.
291

ERRORS

293       Errors are logged to syslog.
294

WORKAROUNDS

296       With  so  many different vendors implementing their own IPMI solutions,
297       different vendors may implement their IPMI protocols  incorrectly.  The
298       following describes a number of workarounds currently available to han‐
299       dle discovered compliance issues. When possible, workarounds have  been
300       implemented so they will be transparent to the user. However, some will
301       require the user to specify a workaround be used via the -W option.
302
303       The hardware listed below may only indicate the hardware that a problem
304       was  discovered  on.  Newer  versions  of hardware may fix the problems
305       indicated below. Similar machines from vendors may or may  not  exhibit
306       the  same  problems.  Different vendors may license their firmware from
307       the same IPMI firmware developer, so it may be worthwhile to try  work‐
308       arounds listed below even if your motherboard is not listed.
309
310       If  you  believe  your hardware has an additional compliance issue that
311       needs a workaround to be implemented, please contact the FreeIPMI main‐
312       tainers on <freeipmi-users@gnu.org> or <freeipmi-devel@gnu.org>.
313
314       assumeio  - This workaround flag will assume inband interfaces communi‐
315       cate with system I/O rather than being memory-mapped.  This  will  work
316       around  systems  that report invalid base addresses. Those hitting this
317       issue may see "device not supported" or "could not find inband  device"
318       errors.  Issue observed on HP ProLiant DL145 G1.
319
320       spinpoll  -  This workaround flag will inform some inband drivers (most
321       notably the KCS driver) to spin while polling rather than  putting  the
322       process to sleep. This may significantly improve the wall clock running
323       time of tools because an operating system scheduler's  granularity  may
324       be  much larger than the time it takes to perform a single IPMI message
325       transaction. However, by spinning, your system may be  performing  less
326       useful work by not contexting out the tool for a more useful task.
327
328       ignorestateflag  -  This  workaround  option  will ignore the BMC timer
329       state flag (indicating if the timer is running or stopped) when running
330       in  daemon mode. On some BMCs, the flag is broken and will never report
331       that a BMC timer is running, even if it is. The  workaround  will  take
332       notice  of  changes in the countdown seconds to determine if a timer is
333       running or stopped. With this type of implementation, the  reset-period
334       must be large enough to ensure minor fluctuations in the countdown will
335       not affect the workaround. Due to  the  implementation  of  this  work‐
336       around,  if  another  process  stops  the  watchdog  timer,  it  may be
337       detectable. This option is confirmed to work around compliances  issues
338       on Sun x4100, x4200, and x4500.
339

EXAMPLES

341       Setup  a  bmc-watchdog  daemon that resets the machine after 15 minutes
342       (900 seconds) if the OS has crashed (see default bmc-watchdog rc script
343       /etc/init.d/bmc-watchdog for a more complete example):
344               bmc-watchdog -d -u 4 -p 0 -a 1 -i 900
345

DIAGNOSTICS

347       Upon  successful  execution, exit status is 0. On error, exit status is
348       1.
349

KNOWN ISSUES

351       Bmc-watchdog may fail to reset the watchdog timer if it is  not  sched‐
352       uled  properly.  It is always recommended that bmc-watchdog be executed
353       with a high scheduling priority.
354
355       On some machines, the hardware based SMI Handler may disable a  proces‐
356       sor after a watchdog timer timeout if the timer use is set to something
357       other than SMS/OS.
358

REPORTING BUGS

360       Report bugs to <freeipmi-users@gnu.org> or <freeipmi-devel@gnu.org>.
361
363       Copyright (C) 2007-2015 Lawrence Livermore National Security, LLC.
364       Copyright (C) 2004-2007 The Regents of the University of California.
365
366       This program is free software; you can redistribute it and/or modify it
367       under  the  terms of the GNU General Public License as published by the
368       Free Software Foundation; either version 3 of the License, or (at  your
369       option) any later version.
370

SEE ALSO

372       freeipmi(7)
373
374       http://www.gnu.org/software/freeipmi/
375
376
377
378bmc-watchdog 1.6.2                2018-05-03                   bmc-watchdog(8)
Impressum