rpc.statd.8   [plain text]


.\"
.\" Copyright (c) 2002-2008 Apple Inc.  All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this
.\" file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_LICENSE_HEADER_END@
.\"
.\" -*- nroff -*-
.\"
.\" Copyright (c) 1995 A.R.Gordon, andrew.gordon@net-tel.co.uk
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd July 5, 2008
.Dt RPC.STATD 8
.Os
.Sh NAME
.Nm rpc.statd
.Nd host status monitoring daemon
.Sh SYNOPSIS
.Nm
.Op Fl d
.Nm
.Op Fl d
.Fl n
.Nm
.Op Fl d
.Op Fl l | Fl L | Fl N Ar hostname
.Sh DESCRIPTION
The
.Nm
utility is a daemon which cooperates with
.Nm
daemons on other hosts to provide
a status monitoring service.  The daemon accepts requests from
programs running on the local host (typically,
.Xr rpc.lockd 8 ,
the NFS file locking daemon) to monitor the status of specified
hosts.  If a monitored host crashes and restarts, the remote daemon will
notify the local daemon, which in turn will notify the local program(s)
which requested the monitoring service.  Conversely, if this host
crashes and restarts, the
.Cm statd.notify
service will be started to notify all of the hosts which were being
monitored at the time of the crash.
.Pp
The
.Nm
utility consists of two
.Xr launchd 8 Ns -controlled
services.  The
.Cm statd.notify
service is run whenever the system needs to notify remote hosts of
a restart.  The
.Cm statd
service is controlled by
.Xr rpc.lockd 8
so that the
.Nm
daemon is running whenever
.Xr rpc.lockd 8
is running.
.Pp
The following is a list of command line options that are available.
Note that since
.Nm
is normally started by
.Xr launchd 8 ,
configuration of these options should be controlled using the equivalent
settings in the NFS configuration file.  See
.Xr nfs.conf 5
for a list of tunable parameters.
.Bl -tag -width indent
.It Fl d
Sets the logging level to the maximum.  Note that finer grain control is
available via the
.Cm nfs.statd.verbose
option in
.Xr nfs.conf 5 Ns .
.Pp
Logging is performed via
.Xr syslog 3
using the LOG_DAEMON facility.  By default, only messages up to priority
LOG_WARNING are logged.  Setting the verbose level to one will add
LOG_NOTICE messages which includes logging failed mount attempts.  A
verbose level of two will increase the log level to LOG_INFO which
includes logging successful mount attempts.  A log level of three or
more will add LOG_DEBUG messages and cause increasing amounts of debug
information to be logged.  The debug information exposes lots of
information about
.Nm Ns 's
inner workings which is typically only useful to developers.
Note: the
.Xr syslog 8
configuration may need to be adjusted in order to see the increased
verbosity.
.El
.Pp
The following command line option causes the daemon to run in the
.Cm statd.notify
notification service mode:
.Bl -tag -width indent
.It Fl n
Send SM_NOTIFY messages to notify any hosts of a restart.
.El
.Pp
The remaining command line options may be useful for viewing or modifying
the contents of the status file.  They do not start up any daemon or service.
.Bl -tag -width indent
.It Fl l
List each host (and its status) in the status file.
.It Fl L
List each host (and its status) in the status file and then
continue to watch the file and report changes.
.It Fl N
Clear the "needs notification" status for
.Ar hostname
so the
.Cm statd.notify
service will no longer try to notify it.
.El
.Sh FILES
.Bl -tag -width /var/run/statd.notify.pid -compact
.It Pa /var/db/statd.status
non-volatile record of monitored hosts.
.It Pa /var/run/statd.pid
The pid of the current
.Cm statd
daemon.
.It Pa /var/run/statd.notify.pid
The pid of the current
.Cm statd.notify
daemon.
.It Pa /System/Library/LaunchDaemons/com.apple.statd.notify.plist
The
.Cm statd.notify
service's property list file for
.Xr launchd 8 .
.It Pa /usr/include/rpcsvc/sm_inter.x
RPC protocol specification used by local applications to register
monitoring requests.
.El
.Sh SEE ALSO
.Xr nfs.conf 5 ,
.Xr rpc.lockd 8 ,
.Xr syslog 3 ,
.Xr launchd 8
.Sh BUGS
There is no means for the daemon to tell when a monitored host has
disappeared permanently (eg. catastrophic hardware failure), as opposed
to transient failure of the host or an intermediate router.  At present,
it will pause and re-try notification at frequent intervals for 10
minutes, then hourly, and finally gives up after 24 hours.  The
.Fl N
option may be used to remove the "needs notification" status from such
hosts.
.Pp
The protocol requires that symmetric monitor requests are made to both
the local and remote daemon in order to establish a monitored relationship.
This is convenient for the NFS locking protocol, but probably reduces the
usefulness of the monitoring system for other applications.
.Sh STANDARDS
The implementation is based on the specification in X/Open CAE Specification
C218, "Protocols for X/Open PC Interworking: XNFS, Issue 4", ISBN 1 872630 66 9