Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | vos_release - Updates read-only volumes to match the read/write source volume | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<vos release> S<<< B<-id> <I<volume name or ID>> >>> | |
11 | [B<-force>] [B<-force-reclone>] | |
12 | S<<< [B<-cell> <I<cell name>>] >>> | |
13 | [B<-noauth>] [B<-localauth>] | |
14 | [B<-verbose>] [B<-encrypt>] [B<-noresolve>] | |
15 | S<<< [B<-config> <I<config directory>>] >>> | |
16 | [B<-help>] | |
17 | ||
18 | B<vos rel> S<<< B<-i> <I<volume name or ID>> >>> | |
19 | [B<-force>] [B<-force-r>] | |
20 | S<<< [B<-c> <I<cell name>>] >>> | |
21 | [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] | |
22 | S<<< [B<-co> <I<config directory>>] >>> | |
23 | [B<-h>] | |
24 | ||
25 | =for html | |
26 | </div> | |
27 | ||
28 | =head1 DESCRIPTION | |
29 | ||
30 | The B<vos release> command copies the contents of the indicated read/write | |
31 | source volume to each read-only site defined in the source volume's Volume | |
32 | Location Database (VLDB) entry. (Use the B<vos addsite> command to define | |
33 | sites as necessary before issuing this command). Each read-only copy has | |
34 | the same name as read/write source with the addition of a C<.readonly> | |
35 | extension. | |
36 | ||
37 | For users to have a consistent view of the file system, the release of the | |
38 | new volume version must be atomic: either all read-only sites receive the | |
39 | new version, or all sites keep the version they currently have. The B<vos | |
40 | release> command is designed to ensure that all copies of the volume's | |
41 | read-only version match both the read/write source and each other. In | |
42 | cases where problems such as machine or server process outages prevent | |
43 | successful completion of the release operation, AFS uses two mechanisms to | |
44 | alert the administrator. | |
45 | ||
46 | First, the command interpreter generates an error message on the standard | |
47 | error stream naming each read-only site that did not receive the new | |
48 | volume version. Second, during the release operation the Volume Location | |
49 | (VL) Server marks site definitions in the VLDB entry with flags (C<New | |
50 | release> and C<Old release>) that indicate whether or not the site has the | |
51 | new volume version. If any flags remain after the operation completes, it | |
52 | was not successful. The Cache Manager refuses to access a read-only site | |
53 | marked with the C<Old release> flag, which potentially imposes a greater | |
54 | load on the sites marked with the C<New release> flag. It is important to | |
55 | investigate and eliminate the cause of the failure and then to issue the | |
56 | B<vos release> command as many times as necessary to complete the release | |
57 | without errors. | |
58 | ||
59 | The pattern of site flags remaining in the volume's VLDB entry after a | |
60 | failed release operation can help determine the point at which the | |
61 | operation failed. Use the B<vos examine> or B<vos listvldb> command to | |
62 | display the VLDB entry. The VL Server sets the flags in concert with the | |
63 | Volume Server's operations, as follows: | |
64 | ||
65 | =over 4 | |
66 | ||
67 | =item * | |
68 | ||
69 | Before the operation begins, the VL Server sets the C<New release> flag on | |
70 | the read/write site definition in the VLDB entry and the C<Old release> | |
71 | flag on read-only site definitions (unless the read-only site has been | |
72 | defined since the last release operation and has no actual volume, in | |
73 | which case its site flag remains C<Not released>). | |
74 | ||
75 | =item * | |
76 | ||
77 | If necessary, the Volume Server creates a temporary copy (a I<clone>) of | |
78 | the read/write source called the ReleaseClone (see the following | |
79 | discussion of when the Volume Server does or does not create a new | |
80 | ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which | |
81 | the VL Server records in the C<RClone> field of the source volume's VLDB | |
82 | entry. | |
83 | ||
84 | =item * | |
85 | ||
86 | The Volume Server distributes a copy of the ReleaseClone to each read-only | |
87 | site defined in the VLDB entry. As the site successfully receives the new | |
88 | clone, the VL Server sets the site's flag in the VLDB entry to C<New | |
89 | release>. | |
90 | ||
91 | =item * | |
92 | ||
93 | When all the read-only copies are successfully released, the VL Server | |
94 | clears all the C<New release> site flags. The ReleaseClone is no longer | |
95 | needed, so the Volume Server deletes it and the VL Server erases its ID | |
96 | from the VLDB entry. | |
97 | ||
98 | =back | |
99 | ||
100 | By default, the Volume Server determines automatically whether or not it | |
101 | needs to create a new ReleaseClone: | |
102 | ||
103 | =over 4 | |
104 | ||
105 | =item * | |
106 | ||
107 | If there are no flags (C<New release>, C<Old release>, or C<Not released>) | |
108 | on site definitions in the VLDB entry, the previous B<vos release> command | |
109 | completed successfully and all read-only sites currently have the same | |
110 | volume. The Volume Server infers that the current B<vos release> command | |
111 | was issued because the read/write volume has changed. The Volume Server | |
112 | creates a new ReleaseClone volume and distributes a copy of the clone | |
113 | volume to all the read-only sites. In order to reduce the amount of data | |
114 | transferred during a release, the Volume Server sends incremental changes to | |
115 | remote sites during the release. The Volume Server only sends files and | |
116 | directories which have been changed in the read/write volume since the | |
117 | previous release. | |
118 | ||
119 | =item * | |
120 | ||
121 | If any site definition in the VLDB entry is marked with a flag, either the | |
122 | previous release operation did not complete successfully or a new | |
123 | read-only site was defined since the last release. The Volume Server does | |
124 | not create a new ReleaseClone, instead distributing the entire existing | |
125 | ReleaseClone to sites marked with the C<Old release> or C<Not released> | |
126 | flag. As previously noted, the VL Server marks each VLDB site definition | |
127 | with the C<New release> flag as the site receives the ReleaseClone, and | |
128 | clears all flags after all sites successfully receive it. | |
129 | ||
130 | =back | |
131 | ||
132 | To override the default behavior, forcing the Volume Server to create and | |
133 | release a new ReleaseClone to the read-only sites, include the B<-force> | |
134 | flag. This is appropriate if, for example, the data at the read/write site | |
135 | has changed since the existing ReleaseClone was created during the | |
136 | previous release operation. | |
137 | ||
138 | The B<-force-reclone> will force the creation of a new release clone volume, | |
139 | but will not force a full volume dump to be distributed to the remote sites. | |
140 | Instead, incremental changes will be distributed when possible. | |
141 | ||
142 | =head1 OPTIONS | |
143 | ||
144 | =over 4 | |
145 | ||
146 | =item B<-id> <I<volume name or id>> | |
147 | ||
148 | Specifies either the complete name or volume ID number of a read/write | |
149 | volume. | |
150 | ||
151 | =item B<-force> | |
152 | ||
153 | Creates a new ReleaseClone and distributes the entire clone volume to | |
154 | all read-only sites, regardless of the C<New release>, C<Old release>, or | |
155 | C<Not released> site flags. | |
156 | ||
157 | =item B<-force-reclone> | |
158 | ||
159 | Creates a new ReleaseClone and incrementally distributes the clone volume to | |
160 | all read-only sites, regardless of the C<New release>, C<Old release>, or | |
161 | C<Not released> site flags. | |
162 | ||
163 | =include fragments/vos-common.pod | |
164 | ||
165 | =back | |
166 | ||
167 | =head1 EXAMPLES | |
168 | ||
169 | The following command clones the read/write volume usr and releases it to | |
170 | the read-only sites defined in its VLDB entry. | |
171 | ||
172 | % vos release usr | |
173 | ||
174 | =head1 PRIVILEGE REQUIRED | |
175 | ||
176 | The issuer must be listed in the F</usr/afs/etc/UserList> file on the | |
177 | machine specified with the B<-server> argument and on each database server | |
178 | machine. If the B<-localauth> flag is included, the issuer must instead be | |
179 | logged on to a server machine as the local superuser C<root>. | |
180 | ||
181 | =head1 SEE ALSO | |
182 | ||
183 | L<vos(1)>, | |
184 | L<vos_addsite(1)>, | |
185 | L<vos_examine(1)>, | |
186 | L<vos_listvldb(1)> | |
187 | ||
188 | =head1 COPYRIGHT | |
189 | ||
190 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
191 | ||
192 | This documentation is covered by the IBM Public License Version 1.0. It was | |
193 | converted from HTML to POD by software written by Chas Williams and Russ | |
194 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |