doc/arch/fssync.txt

   1 This file provides a brief description of the commands of the FSSYNC
   2 protocol, and how/why each are typically used.
   3
   4  -- vol op FSSYNC commands
   5
   6 FSSYNC commands involving volume operations take a FSSYNC_VolOp_command
   7 struct as their command and arguments. They all deal with a specific
   8 volume, so "the specified volume" below refers to the volume in the
   9 FSSYNC_VolOp_hdr in the FSSYNC_VolOp_command.
  10
  11  -- FSYNC_VOL_ON
  12
  13 Tells the fileserver to bring the specified volume online. For DAFS,
  14 this brings the volume into the preattached state. For non-DAFS, the
  15 volume is attached.
  16
  17 This is generally used to tell the fileserver about a newly-created
  18 volume, or to return ('check in') a volume to the fileserver that was
  19 previously checked-out (e.g. via FSYNC_VOL_NEEDVOLUME).
  20
  21  -- FSYNC_VOL_OFF
  22
  23 Tells the fileserver to take a volume offline, so nothing else will
  24 access the volume until it is brought online via FSSYNC again. A volume
  25 that is offlined with this command and the FSYNC_SALVAGE reason code
  26 will not be allowed access from the fileserver by anything. The volume
  27 will be 'checked out' until it is 'checked in' by another FSYNC command.
  28
  29 Currently only the salvaging code uses this command; the only difference
  30 between it an FSYNC_VOL_NEEDVOLUME is the logic that determines whether
  31 an offlined volume can be accessed by other programs or not.
  32
  33  -- FSYNC_VOL_LISTVOLUMES
  34
  35 This is currently a no-op; all it does is return success, assuming the
  36 FSSYNC command is well-formed.
  37
  38 In Transarc/IBM AFS 3.1, this was used to create a file listing all
  39 volumes on the server, and was used with a tool to create a list of
  40 volumes to backup. After AFS 3.1, however, it never did anything.
  41
  42  -- FSYNC_VOL_NEEDVOLUME
  43
  44 Tells the fileserver that the calling program needs the volume for a
  45 certain operation. The fileserver will offline the volume or keep it
  46 online, depending on the reason code given. The volume will be marked as
  47 'checked out' until 'checked in' again with another FSYNC command.
  48
  49 Reason codes for this command are different than for normal FSSYNC
  50 commands; reason codes for _NEEDVOLUME are volume checkout codes like
  51 V_CLONE, V_DUMP, and the like. The fileserver will keep the volume
  52 online if the given reason code is V_READONLY, or if the volume is an RO
  53 volume and the given reason code is V_CLONE or V_DUMP. If the volume is
  54 taken offline, the volume's specialStatus will also be marked with VBUSY
  55 in the case of the V_CLONE or V_DUMP reason codes.
  56
  57  -- FSYNC_VOL_MOVE
  58
  59 Tells the fileserver that the specified volume was moved to a new site.
  60 The new site is given in the reason code of the request. On receiving
  61 this, the fileserver merely sets the specialStatus on the volume, and
  62 breaks all of the callbacks on the volume.
  63
  64  -- FSYNC_VOL_BREAKCBKS
  65
  66 Tells the fileserver to break all callbacks with the specified volume.
  67 This is used when volumes are deleted or overwritten (restores,
  68 reclones, etc).
  69
  70  -- FSYNC_VOL_DONE
  71
  72 Tells the fileserver that a volume has been deleted. This is actually
  73 similar to FSYNC_VOL_ON, except that the volume isn't onlined. The
  74 volume is 'checked in', though, and is removed from the list of volumes.
  75
  76  -- FSYNC_VOL_QUERY
  77
  78 Asks the fileserver to provide the known volume state information for
  79 the specified volume. If the volume is known, the response payload is a
  80 filled-in 'struct Volume'.
  81
  82 This is used as a debugging tool to query volume state in the
  83 fileserver, but is also used by the volserver as an optimization so it
  84 does not need to always go to disk to retrieve volume information for
  85 e.g. the AFSVolListOneVolume or AFSVolListVolumes RPCs.
  86
  87  -- FSYNC_VOL_QUERY_HDR
  88
  89 Asks the fileserver to provide the on-disk volume header for the
  90 specified volume, if the fileserver already has it loaded. If the
  91 fileserver does not already know this information, it responds with
  92 SYNC_FAILED with the reason code FSYNC_HDR_NOT_ATTACHED. Otherwise it
  93 responds with a filled-in 'struct VolumeDiskData' in the response
  94 payload.
  95
  96 This is used by non-fileservers as an optimization during attachment if
  97 we are just reading from the volume and we don't need to 'check out' the
  98 volume from the fileserver (attaching with V_PEEK). If the fileserver
  99 has the header loaded, it avoids needing to hit the disk for the volume
 100 header.
 101
 102  -- FSYNC_VOL_QUERY_VOP (DAFS only)
 103
 104 Asks the fileserver to provide information about the current volume
 105 operation that has the volume checked out. If the volume is checked out,
 106 the response payload is a filled-in 'struct FSSYNC_VolOp_info';
 107 otherwise the command fails with SYNC_FAILED.
 108
 109 This is useful as a debugging aid, and is also used by the volserver to
 110 determine if a volume should be advertised as 'offline' or 'online'.
 111
 112  -- FSYNC_VOL_ATTACH
 113
 114 This is like FSYNC_VOL_ON, but for DAFS forces the volume to become
 115 fully attached (as opposed to preattached). This is used for debugging,
 116 to ensure that a volume is attached and online without needing to
 117 contact the fileserver via e.g. a client.
 118
 119  -- FSYNC_VOL_FORCE_ERROR (DAFS only)
 120
 121 This tells the fileserver that there is something wrong with a volume,
 122 and it should be put in an error state or salvaged.
 123
 124 If the reason code is FSYNC_SALVAGE, the fileserver will potentially
 125 schedule a salvage for the volume. It may or may not actually schedule a
 126 salvage, depending on how many salvages have occurred and other internal
 127 logic; basically, specifying FSYNC_SALVAGE makes the fileserver behave
 128 as if the fileserver itself encountered an error with the volume that
 129 warrants a salvage.
 130
 131 Non-fileserver programs use this to schedule salvages; they should not
 132 contact the salvageserver directly. Note when a salvage is scheduled as
 133 a result of this command, it is done so in the background; getting a
 134 response from this command does not necessarily mean the salvage has
 135 been scheduled, as it may be deferred until later.
 136
 137 If the reason code is not FSYNC_SALVAGE, the fileserver will just put
 138 the volume into an error state, and the volume will be inaccessible
 139 until it is salvaged, or forced online.
 140
 141  -- FSYNC_VOL_LEAVE_OFF
 142
 143 This 'checks in' a volume back to the fileserver, but tells the
 144 fileserver not to bring the volume back online. This can occur when a
 145 non-fileserver program is done with a volume, but the volume's "blessed"
 146 or "inService" fields are not set; this prevents the fileserver from
 147 trying to attach the volume later, only to find the volume is not
 148 blessed and take the volume offline.
 149
 150  -- FSYNC_VG_QUERY (DAFS only)
 151
 152 This queries the fileserver VGC (volume group cache) for the volume
 153 group of the requested volume. The payload consists of an
 154 FSSYNC_VGQry_response_t, specifying the volume group and all of the
 155 volumes in that volume group.
 156
 157 If the VGC for the requested partition is currently being populated,
 158 this will fail with SYNC_FAILED, and the FSYNC_PART_SCANNING reason
 159 code. If the VGC for the requested partition is currently completely
 160 unpopulated, a VGC scan for the partition will be started automatically
 161 in the background, and FSYNC_PART_SCANNING will still be returned.
 162
 163 The demand-salvager uses this to find out what volumes are in the volume
 164 group it is salvaging; it can also be used for debugging the VGC.
 165
 166  -- FSYNC_VG_SCAN (DAFS only)
 167
 168 This discards any information in the VGC for the specified partition,
 169 and re-scans the partition to populate the VGC in the background. This
 170 should normally not be needed, since scans start automatically when VGC
 171 information is requested. This can be used as a debugging tool, or to
 172 force the VGC to discard incorrect information that somehow got into the
 173 VGC.
 174
 175 Note that the scan is scheduled in the background, so getting a response
 176 from this command does not imply that the scan has started; it may start
 177 sometime in the future.
 178
 179  -- FSYNC_VG_SCAN_ALL
 180
 181 This is the same as FSYNC_VG_SCAN, but schedules scans for all
 182 partitions on the fileserver, instead of a particular one.
 183
 184  -- FSYNC_VOL_QUERY_VNODE
 185
 186 Asks the fileserver for information about specific vnode. This takes a
 187 different command header than other vol ops; it takes a struct
 188 FSSYNC_VnQry_hdr which specifies the volume and vnode requested. The
 189 response payload is a 'struct Vnode' if successful.
 190
 191 This responds with FSYNC_UNKNOWN_VNID if the fileserver doesn't know
 192 anything about the given vnode. This command will not automatically
 193 attach the associated volume; the volume must be attached before issuing
 194 this command in order to do anything useful.
 195
 196 This is just a debugging tool, to see what the fileserver thinks about a
 197 particular vnode.
 198
 199  -- stats FSSYNC commands
 200
 201 FSSYNC commands involving statistics take a FSSYNC_StatsOp_command
 202 struct as their command and arguments. Some of them use arguments to
 203 specify what stats are requested, which are specified in sop->args, the
 204 union in the FSSYNC_StatsOp_hdr struct.
 205
 206  -- FSYNC_VOL_STATS_GENERAL
 207
 208 Retrieves general volume package stats from the fileserver. Response
 209 payload consists of a 'struct VolPkgStats'.
 210
 211  -- FSYNC_VOL_STATS_VICEP (DAFS only)
 212
 213 Retrieves per-partition stats from the fileserver for the partition
 214 specified in sop->partName. Response payload consists of a 'struct
 215 DiskPartitionStats64'.
 216
 217  -- FSYNC_VOL_STATS_HASH (DAFS only)
 218
 219 Retrieves hash chain stats for the hash bucket specified in
 220 sop->hash_bucket. Response payload consists of a 'struct
 221 VolumeHashChainStats'.
 222
 223  -- FSYNC_VOL_STATS_HDR (DAFS only)
 224
 225 Retrieves stats for the volume header cache. Response payload consists
 226 of a 'struct volume_hdr_LRU_stats'.
 227
 228  -- FSYNC_VOL_STATS_VLRU (DAFS only)
 229
 230 This is intended to retrieve stats for the VLRU generation specified in
 231 sop->vlru_generation. However, it is not yet implemented and currently
 232 always results in a SYNC_BAD_COMMAND result from the fileserver.
 233
 234  -- VGC update FSSYNC commands
 235
 236 FSSYNC commands involving updating the VGC (volume group cache) take an
 237 FSSYNC_VGUpdate_command struct as their command arguments. The parent
 238 and child fields specify the (parent,child) entry in the partName VGC to
 239 add or remove.
 240
 241  -- FSYNC_VG_ADD (DAFS only)
 242
 243 Adds an entry to the fileserver VGC. This merely adds the specified
 244 child volume to the specified parent volume group, and creates the
 245 parent volume group if it does not exist. This is used by programs that
 246 create new volumes, in order to keep the VGC up to date.
 247
 248  -- FSYNC_VG_DEL (DAFS only)
 249
 250 Deletes an entry from the fileserver VGC. This merely removes the
 251 specified child volume from the specified parent volume group, deleting
 252 the volume group if the last entry was deleted. This is used by programs
 253 that destroy volumes, in order to keep the VGC up to date.