usr.sbin/nfsd/stablerestart.5

   1 .\" Copyright (c) 2009 Rick Macklem, University of Guelph
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd April 10, 2011
  28 .Dt STABLERESTART 5
  29 .Os
  30 .Sh NAME
  31 .Nm nfs-stablerestart
  32 .Nd restart information for the
  33 .Tn NFSv4
  34 server
  35 .Sh SYNOPSIS
  36 .Nm nfs-stablerestart
  37 .Sh DESCRIPTION
  38 The
  39 .Nm
  40 file holds information that allows the
  41 .Tn NFSv4
  42 server to restart without always returning the NFSERR_NOGRACE error, as described in the
  43 .Tn NFSv4
  44 server specification; see
  45 .%T "Network File System (NFS) Version 4 Protocol RFC 3530, Section 8.6.3" .
  46 .Pp
  47 The first record in the file, as defined by struct nfsf_rec in
  48 /usr/include/fs/nfs/nfsrvstate.h, holds the lease duration of the
  49 last incarnation of the server and the number of boot times that follows.
  50 Following this are the number of previous boot times listed in the
  51 first record.
  52 The lease duration is used to set the grace period.
  53 The boot times
  54 are used to avoid the unlikely occurrence of a boot time being reused,
  55 due to a TOD clock going backwards. This record and the previous boot times with this boot time added is re-written at the
  56 end of the grace period.
  57 .Pp
  58 The rest of the file are appended records, as defined by
  59 struct nfst_rec in /usr/include/fs/nfs/nfsrvstate.h and are used
  60 represent one of two things. There are records which indicate that a
  61 client successfully acquired state and records that indicate a client's state was revoked.
  62 State revoke records indicate that state information
  63 for a client was discarded, due to lease expiry and an otherwise
  64 conflicting open or lock request being made by a different client.
  65 These records can be used
  66 to determine if clients might have done either of the
  67 edge conditions.
  68 .Pp
  69 If a client might have done either edge condition or this file is
  70 empty or corrupted, the server returns NFSERR_NOGRACE for any reclaim
  71 request from the client.
  72 .Pp
  73 For correct operation of the server, it must be ensured that the file
  74 is written to stable storage by the time a write op with IO_SYNC specified
  75 has returned. This might require hardware level caching to be disabled for
  76 a local disk drive that holds the file, or similar.
  77 .Sh FILES
  78 .Bl -tag -width /var/db/nfs-stablerestart.bak -compact
  79 .It Pa /var/db/nfs-stablerestart
  80 NFSv4 stable restart file
  81 .It Pa /var/db/nfs-stablerestart.bak
  82 backup copy of the file
  83 .El
  84 .Sh SEE ALSO
  85 .Xr nfsv4 4 ,
  86 .Xr nfsd 8
  87 .Sh BUGS
  88 If the file is empty, the NFSv4 server has no choice but to return
  89 NFSERR_NOGRACE for all reclaim requests. Although correct, this is
  90 a highly undesirable occurrence, so the file should not be lost if
  91 at all possible. The backup copy of the file is maintained
  92 and used by the
  93 .Xr nfsd 8
  94 to minimize the risk of this occurring.
  95 To move the file, you must edit
  96 the nfsd sources and recompile it. This was done to discourage
  97 accidental relocation of the file.