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 In‐
23       terface  (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 ma‐
38       chine that has crashed. When the operating system first starts up,  the
39       BMC timer is set to its initial countdown value. At periodic intervals,
40       when the operating system is functioning properly, the  watchdog  timer
41       can  be  reset  by the OS or a userspace program. Thus, the timer never
42       counts down to zero. When the system crashes, the timer cannot be reset
43       by the OS or userspace program. Eventually, the timer will countdown to
44       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 un‐
54              der SET OPTIONS. If a particular configuration parameter is  not
55              specified on the command line, the current configuration of that
56              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 un‐
69              der 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 re‐
120              quests 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 in‐
305       dicated below. Similar machines from vendors may or may not exhibit the
306       same  problems.  Different  vendors may license their firmware from the
307       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 de‐
337       tectable. This option is confirmed to work around compliances issues on
338       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:
343               bmc-watchdog -d -u 4 -p 0 -a 1 -i 900
344

DIAGNOSTICS

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

KNOWN ISSUES

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

REPORTING BUGS

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

SEE ALSO

371       freeipmi(7)
372
373       http://www.gnu.org/software/freeipmi/
374
375
376
377bmc-watchdog 1.6.8                2021-05-20                   bmc-watchdog(8)
Impressum