Command Reference Manual

vos release

Purpose

Updates the contents of ReadOnly volumes to match their ReadWrite source volume

Synopsis

vos release -id <volume name or ID>  [-f]  [-cell <cell name>] 
            [-noauth]  [-localauth]  [-verbose]  [-help]
    
vos rel -i <volume name or ID>  [-f]  [-c <cell name>]  [-n]  [-l]  [-v]  [-h]

Description

The vos release command clones the indicated ReadWrite volume and places a copy of the clone at each ReadOnly site indicated in the Volume Location Database (VLDB) entry. Each copy is named after the ReadWrite source, with the addition of a .readonly extension. The issuer must already have defined the ReadOnly sites using the vos command.

The vos release command is no more difficult to use than any other vos command, but exactly what happens internally during its execution is somewhat complicated. The complexity is necessary in order to ensure that all copies of the volume's ReadOnly version match both the ReadWrite source and each other. If all the ReadOnly copies are not the same, then users might see different data depending on which copy of the volume they happen to access--obviously not a satisfactory situation. To make sure that all ReadOnly copies match each other and the ReadWrite source, releases must be atomic: either all ReadOnly sites receive the new clone, or all sites keep the ReadOnly version they currently have.

The atomic requirement has two main implications that affect the issuer:

He or she needs to be alert for error messages that indicate an unsuccessful release, and/or check the VLDB entry to make sure certain error-signaling flags are not present
He or she needs to decide whether to use the -f flag

The following two subsections discuss these two implications.

Flags that indicate a failed release

If the vos release command fails before the ReadOnly volume is in place at every defined site, an error message specifies which sites did not receive the ReadOnly volume. To give the issuer a backup method for determining if a release has completed (and for its own internal use), the Volume Server and Volume Location (VL) Server set various flags while executing the following vos release command steps. The presence of some of these flags after an apparent completion signals failure. After determining the cause of the failure, attempt to eliminate the cause and then continue to issue the vos release commands as many times as necessary to make sure the release completes successfully.

The steps during a release, and the flags set, are:

Before cloning begins, the VL Server sets the site flag for the present ReadOnly entries in the VLDB to Old release.
The VL Server sets the site flag for the ReadWrite source to New release.
The Volume Server clones the ReadWrite source, if required. It assigns the clone a temporary volume ID number and the VL Server puts that number in the releaseClone field in the source's VLDB entry. (The discussion below on the use of the -f flag describes when it is appropriate for the Volume Server to make a new clone, and how it uses the releaseClone ID in case a release is not completely successful.)
The Volume Server distributes a copy of the ReleaseClone to each ReadOnly site previously defined in the VLDB (using the vos addsite command). The VL Server changes the site flag for each ReadOnly site from Old release to New release as soon as the site successfully receives the new clone.
When all the ReadOnly copies are successfully released, the VL Server clears all the New release site flags, leaving that part of the site flag field empty. Because it is no longer needed, the Volume Server deletes the ReleaseClone from the system and its ID from the VLDB.

The presence of New release and/or Old release site flags in the VLDB after the "completion" of a release indicates that it was not successful. As mentioned above, an unsuccessful release makes it possible for Cache Managers to access different versions of a volume, depending on which File Server they contact. To prevent this possibility, take whatever steps are necessary to make the release successful.

Using the -f flag

If the issuer wants to make sure that the Volume Server releases a brand new clone to the ReadOnly sites, he or she can include the -f flag. The flag "forces" the Volume Server to make a new clone of the ReadWrite source volume and distribute it to all the possible ReadOnly sites.

If the issuer does not include the -f flag, the Volume Server's course of action depends on whether all of the ReadOnly sites already have identical copies of the volume:

If all the sites currently have the same copy, the Volume Server infers that the previous vos release command must have completed successfully, and that no new ReadOnly sites have been defined since. Assuming that the issuer wants to release a brand new clone, the Volume Server makes one and distributes it to all the defined sites.
If all the sites do not have the same copy, then the Volume Server concludes that either the previous vos release command failed in the middle or else a system administrator has defined a new ReadOnly site since the last release. (A possible reason for failure of a release is that one or more sites were inaccessible at the time.) The Volume Server does not need to make an entirely new clone, however. Instead, it distributes the clone with the releaseClone volume ID to the sites that do not have it yet (Step 3 above defines the ReleaseClone). If this release also fails, the operator needs to issue more vos release commands until the same copy exists at all sites.

Cautions

There are maximum of fourteen sites defined in the VLDB entry for the volume (one ReadWrite site and up to thirteen ReadOnly sites).

Options

-id: Specifies either the complete name or volume ID number of a ReadWrite volume.
-f: Determines whether the Volume Server makes a new clone before distributing it to the ReadOnly sites, in interaction with the state of the ReadOnly copies already at sites. The previous section entitled Using the -f flag describes all the issues involved with using the -f flag.
-cell: Names the cell in which to run the command. Do not combine this argument with the -localauth flag. For more details, see the introductory vos reference page.
-noauth: Assigns the unprivileged identity anonymous to the issuer. Do not combine this flag with the -localauth flag. For more details, see the introductory vos reference page.
-localauth: Constructs a server ticket using a key from the local /usr/afs/etc/KeyFile file. The vos command interpreter presents it to the Volume Server and Volume Location Server during mutual authentication. Do not combine this flag with the -cell argument or -noauth flag. For more details, see the introductory vos reference page.
-verbose: Produces on the standard output stream a detailed trace of the command's execution. If this argument is omitted, only warnings and error messages appear.
-help: Prints the online help for this command. All other valid options are ignored.

Examples

The following command clones the ReadWrite volume usr and releases it to the ReadOnly sites defined in its VLDB entry.

% vos release usr

Privilege Required

The issuer must be listed in the /usr/afs/etc/UserList file on the machine specified with the -server argument and on each database server machine. If the -localauth flag is included, the issuer must instead be logged on to a server machine as the local superuser root.

Related Information