vmaster - Acquire mastership of objects in the Vesta repository
vmaster [-r] [-s srchost[:[srcport][:srcuser]]] [-d dsthost[:[dstport][:dstuser]]] [-h hints] object ...
See the Terminology section of the vesta-intro man page for definitions of terms.
The vmaster command tells the destination (-d) repository to acquire mastership of the specified objects from the source (-s) repository. By default, the local repository is taken as the destination and the source repository is guessed; see below for details. The objects must be specified by their full global pathnames (that is, by names beginning with "/vesta"). The objects must already exist in the destination repository; use the Vesta replicator vrepl first if they do not. If the destination repository already has mastership, the command has no effect; this is not considered an error.
For mastership transfer on an object to be allowed, the user must have ownership permission in both the source and destination repositories. The source repository must be willing to cede mastership to the destination repository, and the destination repository must be willing to accept mastership from the source repository. A repository is willing to cede (or accept) mastership on an object from another repository if, when searching upward from the object's pathname in its copy of the namespace, the first object it finds that has a #mastership-to (or respectively #mastership-from) attribute includes the other repository's host:port name (or '*') in its value. If no object with the appropriate attribute is found, permission is denied.
- Recursively acquire mastership on all children of the specified objects, as well as the objects themselves. Default: off.
- -s srchost[:[srcport][:srcuser]]
- Specifies the source repository by host name and TCP port number. If not specified, vmaster tries to guess the correct source repository, by looking for "master-repository" attributes on the specified objects or their ancestor directories. If srchost is specified but srcport is omitted, srcport defaults to the local repository's port number as specified in the active Vesta configuration file (see the Configuration section below). Alternatively, the string "local" can be given to explicitly specify the local repository.
You can also specify the global user name under which you will access the source repository. The default is user@realm, where user is your local user name and realm is the value of [UserInterface]realm in the active Vesta configuration file. If vrepl cannot authenticate you to the source repository as being the specified user, the transfer will fail with an error message.
- -d dsthost[:[dstport][:dstuser]]
- Specifies the destination repository by host name and TCP port number. Both dsthost and dstport default to the values specified for the local repository in the active Vesta configuration file (see the Configuration section below). Alternatively, the string "local" can be given to explicitly specify the local repository.
You can also specify the global user name under which you will access the destination repository. The default is user@realm, where user is your local user name and realm is the value of [UserInterface]realm in the active Vesta configuration file. If vrepl cannot authenticate you to the destination repository as being the specified user, the transfer will fail with an error message.
- -h hints
- If you do not give the -s flag to specify the source repository explicitly, and vmaster fails to guess it, you can suggest additional repositories to look in using this option. The hints argument is a comma- or space-separated list of repositories, specified by host name and TCP port number in the format host:port. The :port portion may be omitted; it defaults to [Repository]VestaSourceSRPC_port.
Here are the most common error messages you are likely to see and what they generally mean.
Can't find master replica: The algorithm for guessing the appropriate source repository failed. The object's name and a list of repositories that were unsuccessfully tried follows on the same line. You can correct the problem by either explicitly specifying the source repository with the -s flag, supplying additional hints with the -h flag, or correcting the object's master-repository attribute in the destination repository.
Invalid argument: Returned for implementation errors where one of the two repositories supplies invalid data to the other; these should never occur.
Name too long: Overly long arc in pathname.
No permission: Permission to change either the destination or source repository was denied.
Not a directory: Invalid pathname that has arcs beyond a leaf.
Not found: The object was not found in the destination repository. You may need to use the Vesta replicator vrepl first to copy it in.
Not master replica: The specified source repository is not the master for this object. This includes the case where the source repository does not have a copy of the object (or a stub or ghost).
Operation not available on given source type: Mastership transfer is not permitted between the specified object types. The forbidden types of transfer are:
- To a stub from a non-stub.
- To an appendable directory from a ghost.
- To a ghost from a non-ghost. (Technically legal, but disallowed because it probably represents a mistake.)
- On an object that does not have independent mastership (e.g., a file in an immutable directory).
- Between types that should not occur together because they violate the replica agreement invariant (e.g., to an immutable directory from a file).
Remote call from repository to another server failed: A remote procedure call from destination to source repository failed. One of the following two messages will normally appear on the next line:
- Note: transfer was not started: The error occurred before the transfer protocol got under way. Neither repository was modified.
- Note: transfer is still in progress; may finish later: The error occurred after the transfer was partially done. The destination object is left with a "#master-request" attribute set, and the destination repository has forked a recovery thread to complete or abort the transfer. This thread runs periodically, persisting even after reboots, until the source repository can be contacted to resolve the transfer. If necessary, you can force the destination to give up on recovery by manually removing the "#master-request" attribute, but this may leave the object with no master replica, and/or leave a dangling "#master-grant" attribute on the source replica.
SRPC failure: The remote procedure call from vmaster to the destination repository failed. More information about the failure follows on the same line, and if it is possible that the call was started, the message "Note: transfer might have been started" appears on the next line. If the transfer was in fact started, it may either have finished successfully, have been aborted, or be still in progress as described above.
As with all Vesta tools, $VESTACONFIG can be used to override the default location for the Vesta configuration file. No other environment variables are used.
The following values are obtained from the Vesta configuration file (vesta.cfg).
From the [Repository] section:
- Host name of the default local repository.
- TCP port number of the default local repository.
From the [UserInterface] section:
- Name of the local realm. @realm is appended to local user names to obtain global user names.
!! It might be nice to optionally call the replicator for the specified objects (but not their children) first. -r should probably not make this recursive, but maybe a stronger (-R?) flag should be available to do so. What about all the flags the replicator can take, though?
!! When/if GSS-API authentication is added, your credentials for the source repository will have to be delegatable to the destination repository.
vesta-intro(1), vrepl(1), repository(8)
Vesta: A System for Software Configuration Management
This page was generated automatically by mtex software.
Last modified on Fri Nov 9 14:37:59 EST 2001 by email@example.com modified on Fri Jun 1 16:05:43 PDT 2001 by mann