1.\" $NetBSD: wdogctl.8,v 1.8 2003/02/25 10:35:12 wiz Exp $ 2.\" 3.\" Copyright (c) 2000 Zembu Labs, Inc. 4.\" All rights reserved. 5.\" 6.\" Author: Jason R. Thorpe <thorpej@zembu.com> 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by Zembu Labs, Inc. 19.\" 4. Neither the name of Zembu Labs nor the names of its employees may 20.\" be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY ZEMBU LABS, INC. ``AS IS'' AND ANY EXPRESS 24.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR- 25.\" RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DIS- 26.\" CLAIMED. IN NO EVENT SHALL ZEMBU LABS BE LIABLE FOR ANY DIRECT, INDIRECT, 27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 28.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 29.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 30.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 32.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd July 29, 2002 35.Dt WDOGCTL 8 36.Os 37.Sh NAME 38.Nm wdogctl 39.Nd Watchdog timer control utility 40.Sh SYNOPSIS 41.Nm 42.Nm 43.Fl k 44.Op Fl A 45.Op Fl p Ar seconds 46.Ar timer 47.Nm 48.Fl u 49.Op Fl A 50.Op Fl p Ar seconds 51.Ar timer 52.Nm 53.Fl d 54.Sh DESCRIPTION 55.Nm 56is used to manipulate watchdog timers. 57Watchdog timers provide a means of ensuring that a system 58continues to make progress. 59This is accomplished by use of a timer, provided by either hardware or 60software; when the timer expires, the watchdog resets the system. 61In this case of a hardware watchdog timer, this is accomplished by 62asserting the system's hardware reset signal. 63In the case of a software watchdog timer, 64this is accomplished by calling the kernel's normal reboot path. 65In order to prevent the system from rebooting, 66something must refresh the timer to prevent it from expiring. 67.Pp 68The 69.Nx 70kernel provides two basic modes in which watchdog timers may 71operate: kernel tickle mode and user tickle mode. 72In kernel tickle mode, a timer in the kernel refreshes the watchdog timer. 73In user tickle mode, 74.Nm 75runs in the background and refreshes the watchdog timer. 76In kernel tickle mode, progress of the kernel is ensured. 77In user tickle mode, the ability for user programs to run within a known 78period of time is ensured. 79Note that user tickle mode must be used with caution; 80on a heavily loaded system, the timer may 81expire accidentally, even though user programs may be making 82(very slow) progress. 83.Pp 84In both modes, an attempt is made to refresh the watchdog timer 85in one half the timer's configured period. 86That is, if the watchdog timer has a period of 30 seconds, a refresh attempt 87is made every 15 seconds. 88.Pp 89If called without arguments, 90.Nm 91will list the timers available on the system. 92When arming a watchdog timer, the 93.Ar timer 94argument is the name of the timer to arm. 95.Pp 96Only one timer may be armed at a time; if an attempt is made 97to arm a timer when one is already armed, an error message 98will be displayed and no action will be taken. 99.Pp 100The options are as follows: 101.Bl -tag -width indent 102.It Fl k 103Arm 104.Ar timer 105in kernel tickle mode. 106.It Fl u 107Arm 108.Ar timer 109in user tickle mode. 110.It Fl A 111When arming a timer, this flag indicates that an audible alarm is 112to sound when the watchdog timer expires and resets the system. 113If the selected timer does not support an audible alarm, this 114option will be silently ignored. 115.It Fl p Ar period 116When arming a timer, this flag configures the timer period to 117.Ar period 118seconds. 119If the specified period it outside the timer's range, 120an error message will be displayed and no action will be taken. 121.It Fl d 122This flag disarms the currently active timer. 123Note that not all watchdog timers can be disabled once armed. 124If the selected timer can not be disabled, 125an error message will be displayed and the 126timer will remain armed. 127.El 128.Sh FILES 129.Pa /dev/watchdog 130-- the system monitor watchdog timer device 131.Sh SEE ALSO 132.Xr envsys 4 , 133.Xr envstat 8 134.Sh HISTORY 135The 136.Nm 137command first appeared in 138.Nx 1.5.1 . 139.Sh AUTHORS 140The 141.Nm 142command and the 143.Nx 144watchdog timer framework were written by 145.An Jason R. Thorpe 146.Aq thorpej@zembu.com , 147and contributed by Zembu Labs, Inc. 148