File: bmc-watchdog.8.pre.in

package info (click to toggle)
freeipmi 1.4.11-1.1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 21,952 kB
  • ctags: 18,990
  • sloc: ansic: 299,490; sh: 11,087; makefile: 1,958; perl: 1,078
file content (319 lines) | stat: -rw-r--r-- 12,927 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
.\"#############################################################################
.\"$Id: bmc-watchdog.8.pre.in,v 1.30 2010-06-30 21:56:36 chu11 Exp $
.\"#############################################################################
.\"  Copyright (C) 2007-2014 Lawrence Livermore National Security, LLC.
.\"  Copyright (C) 2004-2007 The Regents of the University of California.
.\"  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
.\"  Written by Albert Chu <chu11@llnl.gov>
.\"  UCRL-CODE-155913
.\"  
.\"  This file is part of Bmc-Watchdog, a base management controller (BMC)
.\"  watchdog timer management tool.  For details, see http://www.llnl.gov/linux/.
.\"
.\"  Bmc-Watchdog is free software; you can redistribute it and/or modify it under
.\"  the terms of the GNU General Public License as published by the Free
.\"  Software Foundation; either version 3 of the License, or (at your option)
.\"  any later version.
.\"  
.\"  Bmc-Watchdog is distributed in the hope that it will be useful, but WITHOUT 
.\"  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
.\"  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License 
.\"  for more details.
.\"  
.\"  You should have received a copy of the GNU General Public License along
.\"  with Bmc-Watchdog.  If not, see <http://www.gnu.org/licenses/>.
.\"############################################################################
.TH bmc-watchdog 8 "@ISODATE@" "bmc-watchdog @PACKAGE_VERSION@" "System Commands"
.SH "NAME"
bmc-watchdog \- BMC watchdog timer daemon and control utility
.SH "SYNOPSIS"
.B bmc-watchdog 
command [\fIOPTION\fR...] [\fICOMMAND_OPTIONS\fR...]
.br
.SH "DESCRIPTION"
.B bmc-watchdog
controls a Baseboard Management Controller (BMC) watchdog timer.  The
.B bmc-watchdog
tool typically executes as a cronjob or daemon to manage the watchdog
timer.  A user must be root in order to run
.B bmc-watchdog. 
.LP
Listed below are
.B bmc-watchdog
details, option details, examples, and known issues.  For a general
introduction to FreeIPMI please see 
.B freeipmi(7).

.SH "BMC WATCHDOG DETAILS"
A BMC watchdog timer is part of the Intelligent Platform Management
Interface (IPMI) specification and is only available to BMCs that are
compliant with IPMI.  When a BMC watchdog timer is started, it begins
counting down to zero from some positive number of seconds.  When the
timer hits zero, the timer will execute a pre-configured pre-timeout
interrupt and/or timeout action.
.LP
In order to stop the pre-timeout interrupt or timeout action from
being executed, the watchdog timer must be periodically reset back to
its initial beginning value.
.LP
The BMC watchdog timer automatically stops itself when the machine is
rebooted.  Therefore, when a machine is brought up, the BMC watchdog
timer must be setup again before it can be used.
.LP
Typically, a BMC watchdog timer is used to automatically reset a
machine that has crashed.  When the operating system first starts up,
the BMC timer is set to its initial countdown value.  At periodic
intervals, when the operating system is functioning properly, the
watchdog timer can be reset by the OS or a userspace program.  Thus,
the timer never counts down to zero.  When the system crashes, the
timer cannot be reset by the OS or userspace program.  Eventually, the
timer will countdown to zero and reset the machine.
.LP
See EXAMPLES below for examples of how bmc-watchdog is commonly used.

.SH "COMMANDS"
The following commands are available to
.B bmc-watchdog.
.TP
\fB\-s\fR, \fB\-\-set\fR
Set BMC Watchdog Configuration.  BMC watchdog timer configuration
values can be set using the set command options listed below under SET
OPTIONS.  If a particular configuration parameter is not specified on
the command line, the current configuration of that parameter will not
be changed.
.TP
\fB\-g\fR, \fB\-\-get\fR
Get BMC Watchdog Configuration and State.  The current
configuration and state is printed to standard output.
.TP
\fB\-r\fR, \fB\-\-reset\fR
Reset BMC Watchdog Timer.  
.TP
\fB\-t\fR, \fB\-\-start\fR                   
Start BMC Watchdog Timer.  Does nothing if the timer is currently
running.  Identical to \fB\-\-reset\fR command when the timer is
stopped with the exception of the start command options listed below
under START OPTIONS.
.TP
\fB\-y\fR, \fB\-\-stop\fR
Stop BMC Watchdog Timer.  Stops the current timer.
.TP
\fB\-c\fR, \fB\-\-clear\fR
Clear BMC Watchdog Configuration.  Clears all configuration values
for the watchdog timer, except for timer use, which is kept at 
its current value.
.TP
\fB\-d\fR, \fB\-\-daemon\fR
Run 
.B bmc-watchdog 
as a daemon.  Configurable BMC watchdog timer options are listed below
under DAEMON OPTIONS.  The configuration values are set once, then the
daemon will reset the timer at specified periodic intervals.  The
daemon can be stopped using the \fB\-\-stop\fR command,
\fB\-\-clear\fR command, or by setting the stop_timer flag on the
\fB\-\-set\fR command.
#include <@top_srcdir@/man/manpage-common-general-options-header.man>
These options are generic and can be used by any command.
.TP 
\fB\-D\fR \fIIPMIDRIVER\fR, \fB\-\-driver\-type\fR=\fIIPMIDRIVER\fR
Specify the driver type to use instead of doing an auto selection.
The currently available inband drivers are KCS, SSIF, OPENIPMI,
SUNBMC, and INTELDCMI.
#include <@top_srcdir@/man/manpage-common-inband.man>
.TP
\fB\-v\fR, \fB\-\-verbose\-logging\fR
Increase verbosity of logging.
.TP
\fB\-n\fR, \fB\-\-no\-logging\fR
Turns off all logging done by 
.B bmc-watchdog.  
#include <@top_srcdir@/man/manpage-common-config-file.man>
#include <@top_srcdir@/man/manpage-common-workaround-flags.man>
#include <@top_srcdir@/man/manpage-common-debug.man>
#include <@top_srcdir@/man/manpage-common-misc.man>
.SH "SET OPTIONS"
The following options can be used by the set command to set or clear
various BMC watchdog configuration parameters.
.TP
\fB\-u\fR \fIINT\fR, \fB\-\-timer\-use\fR=\fIINT\fR
Set timer use.  The timer use value can be set to one of the
following: 1 = BIOS FRB2, 2 = BIOS POST, 3 = OS_LOAD, 4 = SMS OS, 5 =
OEM.
.TP
\fB\-m\fR \fIINT\fR, \fB\-\-stop\-timer\fR=\fIINT\fR
Set Stop Timer Flag.  A flag value of 0 stops the current BMC watchdog
timer.  A value of 1 doesn't turn off the current watchdog timer.
.TP
\fB\-l\fR \fIINT\fR, \fB\-\-log\fR=\fIINT\fR
Set Log Flag.  A flag value of 0 turns logging on.  A value of 1 turns
logging off.
.TP
\fB\-a\fR \fIINT\fR, \fB\-\-timeout\-action\fR=\fIINT\fR
Set timeout action.  The timeout action can be set to one of the
following: 0 = No action, 1 = Hard Reset, 2 = Power Down, 3 = Power
Cycle.
.TP
\fB\-p\fR \fIINT\fR, \fB\-\-pre\-timeout\-interrupt\fR=\fIINT\fR
Set pre-timeout interrupt.  The pre timeout interrupt can be set to
one of the following: 0 = None, 1 = SMI, 2 = NMI, 3 = Messaging
Interrupt.
.TP
\fB\-z\fR \fISECONDS\fR, \fB\-\-pre-timeout-interval=\fISECONDS\fR  
Set pre-timeout interval in seconds.
.TP
\fB\-F\fR, \fB\-\-clear-bios-frb2\fR
Clear  BIOS FRB2 Timer Use Flag.
.TP
\fB\-P\fR, \fB\-\-clear-bios-post\fR
Clear BIOS POST Timer Use Flag.
.TP
\fB\-L\fR, \fB\-\-clear-os-load\fR
Clear OS Load Timer Use Flag.
.TP
\fB\-S\fR, \fB\-\-clear-sms-os\fR
Clear SMS/OS Timer Use Flag.
.TP
\fB\-O\fR, \fB\-\-clear-oem\fR
Clear OEM Timer Use Flag.
.TP
\fB\-i\fR \fISECONDS\fR, \fB\-\-initial\-countdown\fR=\fISECONDS\fR
Set initial countdown in seconds.
.TP
\fB\-w\fR, \fB\-\-start\-after\-set\fR
Start timer after set command if timer is stopped.  This is typically
used when
.B bmc-watchdog
is used as a cronjob.  This can be used to automatically start the
timer after it has been set the first time.
.TP
\fB\-x\fR, \fB\-\-reset\-after\-set\fR
Reset timer after set command if timer is running.
.TP
\fB\-j\fR, \fB\-\-start\-if\-stopped\fR
Don't execute set command if timer is stopped, just start timer.
.TP
\fB\-k\fR, \fB\-\-reset\-if\-running\fR
Don't execute set command if timer is running, just reset timer. This
is typically used when
.B bmc-watchdog
is used as a cronjob.  This can be used to reset the timer after it
has been initially started.

.SH "START OPTIONS"
The following options can be used by the start command.
.TP
\fB\-G\fR \fIINT\fR, \fB\-\-gratuitous\-arp\fR=\fIINT\fR
Suspend or don't suspend gratuitous ARPs while the BMC timer is
running.  A flag value of 1 suspends gratuitous ARPs.  A value of 0
will not suspend gratuitous ARPs.  If this option is not specified,
gratuitous ARPs will not be suspended.
.TP
\fB\-A\fR \fIINT\fR, \fB\-\-arp\-response\fR=\fIINT\fR
Suspend or don't suspend BMC-generated ARP responses while the BMC
timer is running.  A flag value of 1 suspends ARP responses.  A value
of 0 will not suspend ARP responses.  If this option is not specified,
ARP responses will not be suspended.

.SH "DAEMON OPTIONS"
The following options can be used by the daemon command to set the
initial BMC watchdog configuration parameters.
.TP
\fB\-u\fR \fIINT\fR, \fB\-\-timer\-use\fR=\fIINT\fR
Set timer use.  The timer use value can be set to one of the
following: 1 = BIOS FRB2, 2 = BIOS POST, 3 = OS_LOAD, 4 = SMS OS, 5 =
OEM.
.TP
\fB\-l\fR \fIINT\fR, \fB\-\-log\fR=\fIINT\fR
Set Log Flag.  A flag value of 0 turns logging on.  A value of 1 turns
logging off.
.TP
\fB\-a\fR \fIINT\fR, \fB\-\-timeout\-action\fR=\fIINT\fR
Set timeout action.  The timeout action can be set to one of the
following: 0 = No action, 1 = Hard Reset, 2 = Power Down, 3 = Power
Cycle.
.TP
\fB\-p\fR \fIINT\fR, \fB\-\-pre\-timeout\-interrupt\fR=\fIINT\fR
Set pre-timeout interrupt.  The pre timeout interrupt can be set to
one of the following: 0 = None, 1 = SMI, 2 = NMI, 3 = Messaging
Interrupt.
.TP
\fB\-z\fR \fISECONDS\fR, \fB\-\-pre-timeout\-interval\fR=\fISECONDS\fR  
Set pre-timeout interval in seconds.
.TP
\fB\-F\fR, \fB\-\-clear-bios-frb2\fR
Clear  BIOS FRB2 Timer Use Flag.
.TP
\fB\-P\fR, \fB\-\-clear-bios-post\fR
Clear BIOS POST Timer Use Flag.
.TP
\fB\-L\fR, \fB\-\-clear-os-load\fR
Clear OS Load Timer Use Flag.
.TP
\fB\-S\fR, \fB\-\-clear-sms-os\fR
Clear SMS/OS Timer Use Flag.
.TP
\fB\-O\fR, \fB\-\-clear-oem\fR
Clear OEM Timer Use Flag.
.TP
\fB\-i\fR \fISECONDS\fR, \fB\-\-initial\-countdown\fR=\fISECONDS\fR
Set initial countdown in seconds.
.TP
\fB\-G\fR \fIINT\fR, \fB\-\-gratuitous\-arp\fR=\fIINT\fR
Suspend or don't suspend gratuitous ARPs while the BMC timer is
running.  A flag value of 1 suspends gratuitous ARPs.  A value of 0
will not suspend gratuitous ARPs.  If this option is not specified,
gratuitous ARPs will not be suspended.
.TP
\fB\-A\fR \fIINT\fR, \fB\-\-arp\-response\fR=\fIINT\fR
Suspend or don't suspend BMC-generated ARP responses while the BMC
timer is running.  A flag value of 1 suspends ARP responses.  A value
of 0 will not suspend ARP responses.  If this option is not specified,
ARP responses will not be suspended.
.TP
\fB\-e\fR, \fB\-\-reset\-period\fR
Time interval to wait before resetting timer.  The default is 60
seconds.
.SH "ERRORS"
Errors are logged to syslog.
#include <@top_srcdir@/man/manpage-common-workaround-heading-text.man>
#include <@top_srcdir@/man/manpage-common-workaround-inband-text.man>
.LP
\fIignorestateflag\fR - This workaround option will ignore the BMC
timer state flag (indicating if the timer is running or stopped) when
running in daemon mode.  On some BMCs, the flag is broken and will
never report that a BMC timer is running, even if it is.  The
workaround will take notice of changes in the countdown seconds to
determine if a timer is running or stopped.  With this type of
implementation, the reset-period must be large enough to ensure minor
fluctuations in the countdown will not affect the workaround.  Due to
the implementation of this workaround, if another process stops the
watchdog timer, it may be detectable.  This option is confirmed to
work around compliances issues on Sun x4100, x4200, and x4500.

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

#include <@top_srcdir@/man/manpage-common-diagnostics.man>
.SH "KNOWN ISSUES"
.B Bmc-watchdog
may fail to reset the watchdog timer if it is not scheduled properly.
It is always recommended that 
.B bmc-watchdog
be executed with a high scheduling priority.
.LP
On some machines, the hardware based SMI Handler may disable a
processor after a watchdog timer timeout if the timer use is set to
something other than SMS/OS.
#include <@top_srcdir@/man/manpage-common-reporting-bugs.man>
.SH COPYRIGHT
Copyright (C) 2007-2014 Lawrence Livermore National Security, LLC.
.br
Copyright (C) 2004-2007 The Regents of the University of California.
#include <@top_srcdir@/man/manpage-common-gpl-program-text.man>
.SH "SEE ALSO"
freeipmi(7)
#include <@top_srcdir@/man/manpage-common-homepage.man>