vcheckagreement(8)

Name

vcheckagreement - Check that two Vesta repositories are in agreement (consistent).

Synopsis

vcheckagreement [-l level] repos1 [repos2] [path...]

Contents

• Description
• Replica Agreement Definition
• Flags
• Configuration
• Limitations
• See Also

Description

See the vesta-intro man page's Terminology section for definitions of terms, and its Name Interpretation section for an explanation of how names are looked up.

The vcheckagreement command checks that the contents of two repositories repos1 and repos2 agree. Because this checking can be expensive (as it requires reading the contents of both repositories over the network), there are several levels of agreement checking. If desired, you can limit the checking to one or more source paths within the repository. (If you don't specify any paths, the entire repository will be checked for agreement.) If repos2 is not specified it defaults to local repository.

If the two repositories are in agreement, vcheckagreement prints "true" and exits with status 0. Otherwise it prints information about the agreement violations which were found followed by "false" on a line by itself and and exits with status 1. It exits with status 2 in a case of wrong usage or another error.

Note that there is some ambiguity in the command-line arguments: the argument after repos1 might be repos2 or it might be the first source path to which the checking should be limited. If the second argument contains "/" is will be treated as the first path, otherwise it will be treated as repos2. The easiest way to make sure vcheckagreement doesn't treat the first path as repos2 is to always use absolute paths starting with "/vesta/".

Replica Agreement Definition

Two repositories agree (are consistent) if (1) there are no cases where the same name means something different in two different repositories, and (2) each name is designated as master in at most one repository.

To define agreement more precisely:

A.master denotes the master flag of A.
A.repos denotes the repository where A is stored.
A.names denotes the list of names that are bound to A if A is a directory.
A ~ B denotes agreement between two Vesta source objects A and B.

A ~ B if the following recursively defined conditions hold:

1. A.master and B.master => A.repos = B.repos and
2. At least one of the following holds:

   (a) A and B are files with identical contents.

   (b) A and B are immutable directories where

   i. A.names = B.names, and

   ii. For every n in A.names: A/n ~ B/n,

   (c) A and B are appendable directories where

   i. For every n in both A.names and B.names: A/n ~ B/n,

   ii. A.master => B.names is a subset of A.names,

   iii. B.master => A.names is a subset of B.names.

   (d) A and B are both master stubs

   (e) A or B is a nonmaster stub

   (f) A or B is a ghost

So, two repositories agree if their replicas of the root directory (/vesta) agree.

Vesta's replication design and replica agreement are further described in "Partial Replication in the Vesta Software Repository".

It's worth noting that agreement is not a transitive property. If reposA agrees with reposB and reposB agrees with reposC, that doesn't neccessarily mean that reposA agrees reposC.

Flags

-l level

Specifies the level of detail of the agreement check. level should be one of the following:

0

Stop checking at immutable directories assuming that their contents are the same.

1

Recursively compare immutable directories verifying that their directory structure is the same, including a comparison of immutable files attributes like size, executable status, fingerprint.

2

Verify that the contents of immutable files are identical.

Each higher level will take more time, more network bandwidth, and more resources on the repository servers. level defaults to 0 if the -l flag is not given.

Configuration

The following values are obtained from the [Repository] section of the Vesta configuration file.

VestaSourceSRPC_host

Host name of the default local repository.

VestaSourceSRPC_port

The default TCP port number for repositories.

From the [UserInterface] section:

TimeFormat

A format string for strftime(3) to produce time strings. A common setting is "%a %b %e %T %Z %Y".

Limitations

Agreement is defined to be reflexive (i.e. a repository agrees with itself). However, vcheckagreement cannot be used to check a repository against itself.

See Also

vesta-intro(1), vrepl(1), vmaster(1), "Partial Replication in the Vesta Software Repository" by Tim Mann