1 This file provides a brief description of the commands of the FSSYNC
2 protocol, and how/why each are typically used.
4 -- vol op FSSYNC commands
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.
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
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).
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.
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.
33 -- FSYNC_VOL_LISTVOLUMES
35 This is currently a no-op; all it does is return success, assuming the
36 FSSYNC command is well-formed.
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.
42 -- FSYNC_VOL_NEEDVOLUME
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.
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.
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.
64 -- FSYNC_VOL_BREAKCBKS
66 Tells the fileserver to break all callbacks with the specified volume.
67 This is used when volumes are deleted or overwritten (restores,
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.
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'.
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.
87 -- FSYNC_VOL_QUERY_HDR
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
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
102 -- FSYNC_VOL_QUERY_VOP (DAFS only)
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.
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'.
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.
119 -- FSYNC_VOL_FORCE_ERROR (DAFS only)
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.
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
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.
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.
141 -- FSYNC_VOL_LEAVE_OFF
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.
150 -- FSYNC_VOL_QUERY_VNODE
152 Asks the fileserver for information about specific vnode. This takes a
153 different command header than other vol ops; it takes a struct
154 FSSYNC_VnQry_hdr which specifies the volume and vnode requested. The
155 response payload is a 'struct Vnode' if successful.
157 This responds with FSYNC_UNKNOWN_VNID if the fileserver doesn't know
158 anything about the given vnode. This command will not automatically
159 attach the associated volume; the volume must be attached before issuing
160 this command in order to do anything useful.
162 This is just a debugging tool, to see what the fileserver thinks about a
165 -- stats FSSYNC commands
167 FSSYNC commands involving statistics take a FSSYNC_StatsOp_command
168 struct as their command and arguments. Some of them use arguments to
169 specify what stats are requested, which are specified in sop->args, the
170 union in the FSSYNC_StatsOp_hdr struct.
172 -- FSYNC_VOL_STATS_GENERAL
174 Retrieves general volume package stats from the fileserver. Response
175 payload consists of a 'struct VolPkgStats'.
177 -- FSYNC_VOL_STATS_VICEP (DAFS only)
179 Retrieves per-partition stats from the fileserver for the partition
180 specified in sop->partName. Response payload consists of a 'struct
181 DiskPartitionStats64'.
183 -- FSYNC_VOL_STATS_HASH (DAFS only)
185 Retrieves hash chain stats for the hash bucket specified in
186 sop->hash_bucket. Response payload consists of a 'struct
187 VolumeHashChainStats'.
189 -- FSYNC_VOL_STATS_HDR (DAFS only)
191 Retrieves stats for the volume header cache. Response payload consists
192 of a 'struct volume_hdr_LRU_stats'.
194 -- FSYNC_VOL_STATS_VLRU (DAFS only)
196 This is intended to retrieve stats for the VLRU generation specified in
197 sop->vlru_generation. However, it is not yet implemented and currently
198 always results in a SYNC_BAD_COMMAND result from the fileserver.