Mac OS X Server: About the Watchdog Process

Watchdog is a process designed to start, monitor, and restart other processes and services as necessary to keep them running in versions 10.0.x through 10.3.x of Mac OS X Server. In versions 10.4 and later, its process monitoring role is replaced by launchd, and its restart function is replaced by watchdogtimerd.
This article has been archived and is no longer updated by Apple.

What is the Watchdog service?

Watchdog is a process designed to start, monitor and restart other processes and services as necessary to keep them running. It "watches" the programs it starts.

Software monitored

In Mac OS X Server 10.0.3 and later, Watchdog is set by default to keep the following services running:

  • slpd
    The SLP daemon
  • sambaadmin
    The SMB (Windows) administration daemon
  • serveradmin
    The Server Admin daemon
  • mailservice
    The Apple Mail Services daemon
  • mm
    The Macintosh Manager server

Note: Please see the Mac OS X Server Administrator's Guide to learn more about each of these services.

If a service stops working almost immediately after being started (the current default is less than 10 seconds), watchdog marks that service as "faulty" and stops trying to restart it. This is a safety measure to prevent a situation in which a failing process restarts indefinitely.

Automatic Restart (hardware)

Watchdog also helps restart the server if its operating system becomes unresponsive (a "hang"). On computers that support automatic restart, this option can be activated in the Energy Saver pane of System Preferences. Once activated, Watchdog periodically resets the computer's Power Management Unit (PMU) timer. If this timer expires (which happens if the system hangs), the PMU forces a restart.

Watchdog.conf

The file "watchdog.conf", located in the /etc/ directory, determines what services Watchdog starts and maintains. Each line in the file represents a single application to manage and follows the following form:

  • id:action:path args

id:
A unique way to identify the service.

action:
How to monitor a service and what to do if it stops working. The possible action options are:

  • off - If the specified service is not running, do not start it. If it is running, stop it.
  • boot - Only start the service when watchdog starts. If it stops after that, it is not restarted.
  • bootwait - Currently this behaves the same way as boot.
  • respawn - Watchdog will restart the application if it stops working.
  • now - Watchdog ignores this entry at startup and will actually change the entry in the configuration file to "off". If you change an entry to "now" and force watchdog to reread its configuration file, it will treat that entry as if it were marked "respawn".

path:
The pathname of the target application.

args:
Any command line options.

This is an example watchdog.conf entry from the default watchdog.conf file included with Mac OS X Server: 

slpd:respawn:/usr/sbin/slpd -f /etc/slpsa.conf    # SLP daemon

This entry would be read "identify this entry as 'slpd', start and restart the application as necessary, using the path and command line options /usr/sbin/slpd -f /etc/slpsa.conf." The last item is a comment used to document the entries. Anything after a pound sign (#) is considered a comment and ignored by watchdog.

Custom Events

You can modify watchdog.conf to suit your needs, including any other services or applications you want to start at system startup and keep active. Apple recommends including only command line or BSD-based applications to Watchdog's list of applications.

Event Log

Watchdog keeps a log of its activities in the file "watchdog.event.log", located in the directory /Library/Logs/. You can view this log from the Terminal application or from the Server Admin's Log Viewer module. You can use this log to monitor when Watchdog starts new applications, restarts unresponsive applications, or stops trying to start an application that fails to start. It should be a good first place to start troubleshooting new or modified watchdog.conf entries.

Other Sources of Information

You can find more detailed technical information about controlling the watchdog process, including command line options, signals, and examples, in the man page (accessible via the Terminal application) and the from watchdog.conf file itself.

Published Date: Feb 17, 2012