repository(8)

Name

repository - Vesta repository server

Synopsis

repository [-h] [-d level] [-f first-ckp]

In the most common usage, all arguments are defaulted.

Contents

Description

See the Terminology section of the vesta-intro man page for definitions of terms.

The repository program is the Vesta repository server. It provides stable storage for immutable, versioned Vesta sources in a tree of appendable and immutable directories, for working sources that are still being edited in a tree of mutable directories, and for Vesta derived files. The server also provides a tree of volatile directories, which allow tools started by the evaluator to view Vesta bindings as filesystem directories, with the changes the tools make recorded by the repository and available to the evaluator.

NFS Interface

The repository's NFS interface makes the trees of appendable and immutable, mutable, and volatile directories visible as a part of the ordinary file system name space. The appendable/immutable tree is conventionally mounted under /vesta, the mutable tree under /vesta-work, and the volatile tree under /vesta-work/.volatile. These names can be customized with the [UserInterface]AppendableRootName and [UserInterface]MutableRootName settings in the Vesta configuration file (vesta.cfg).

The NFS interface provides a mildly distorted view of the repository's contents. All types of Vesta directories are manifested as NFS directories, and both mutable and immutable files are manifested as NFS files. Stubs and ghosts are normally manifested as empty files with unusual access permissions. On a master stub, the read and execute permissions are turned off, but the setuid bit is turned on. The write permissions are meaningful, so they are allowed to show through. Thus a master stub will typically appear in an "ls -l" listing with mode --wS------ or --wS-w----. On a non-master stub, all permissions are turned off, but the setgid bit is turned on, so "ls -l" will show ------S---. On a ghost, all permissions are turned off, but the sticky bit is turned on, so "ls -l" will show ---------T.

Exception: If a stub or ghost has a nonempty value for its symlink-to attribute, it is manifested as a symbolic link. The attribute should have a singleton value; the results are unspecified if it is multivalued. Normally, the attribute's value gives the symlink's value. However, if the attribute's value is the special token "$LAST", the symlink's value is the arc in the current directory that consists entirely of decimal digits, has no extra leading zeroes, is not bound to a ghost or stub, and has the largest numeric value of all such arcs. If there are no such arcs, the value is -1.

The NFS interface is exported on a nonstandard UDP port and is not registered with the portmapper or mount daemon. Instead, the host and port number must be obtained from the Vesta configuration file, settings NFS_host and NFS_port in the [Repository] section. A special program vmount(8) is available for mounting the repository. A pair of shell scripts provides a more convenient front-end to this program; see mountrepos(8), and umountrepos(8).

SRPC Interface

The repository also has a remote procedure call interface. This interface provides access to functions that do not map naturally onto the NFS interface, such as atomic checkin/checkout of packages, replication, etc. The interface is implemented using the Vesta-specific SRPC (simple remote procedure call) protocol, but this detail is not important to client programs; they use the interface by linking with a C++ library provided by the repository. This library layers a convenient set of classes and functions atop the raw SRPC calls.

The repository library's VDirSurrogate class provides access to all kinds of Vesta source objects, including all forms of directory, files, ghosts, and stubs. It is a subclass of VestaSource that implements its operations as SRPC calls to the repository server. Many operations that are not available through the NFS interface are provided in VDirSurrogate. Operations on the LongId class and most of the operations on the AccessControl class are also available.

The VestaSourceAtomic class provides a way to group several VDirSurrogate operations into an atomic unit. The repository user interface tools (see repos-ui(1)) are built on top of VDirSurrogate and VestaSourceAtomic, and the Vesta evaluator also makes use of VDirSurrogate.

Access to lower-level repository functions is provided through the SourceOrDerived class. These functions are used by the Vesta evaluator and weeder. The class gets its name from the fact that the repository stores both the files that hold sources and those that hold deriveds in one unified pool. The class contains methods for creating and/or opening files in the pool (used by the evaluator), for triggering the repository's part of the weeding process (used by the weeder), and for triggering a repository checkpoint to speed up crash recovery (also used by the weeder).

For low-level debugging and other sorts of wizardry, the TestVDirSurrogate(8) program is a test driver that can invoke most functions in VDirSurrogate and LongId, while the TestShortId(8) program can invoke most functions in SourceOrDerived.

Access Control

The repository supports replication and remote access between sites under different administrations (called realms), with different sets of authorized users and groups. Therefore, the repository does access control based on a global (worldwide) namespace of principals, not simply the local Unix users and groups. The access controls that can be placed on sources in the repository are similar to ordinary Unix access controls, but written in terms of global principal names and slightly generalized.

Principal identification and authentication

Principals are identified by character string names of the form user@realm or ^group@realm. A calling process attempting to access the repository can claim and authenticate its identity as a principal in several ways, described in this subsection. An export file read by the repository at startup controls which forms of identification and authentication are accepted from which client hosts. The syntax of the export file is given in a later subsection.

First, a principal can identify itself to the repository using numeric Unix user and group identifiers. This form of identification is primarily for use by local NFS clients, and corresponds to the AUTH_UNIX authentication flavor of the NFS protocol. When the repository receives a Unix uid or gid, it uses the local operating system's user and group databases to translate the identifier to a character-string user or group name, prepends ^ for groups, then appends @realm to obtain a global name. Here realm is the local realm name, specified as [Repository]realm in the Vesta configuration file.

Unix identities are authenticated only by origin: if the repository's export table specifies that a particular client host is trusted for Unix identities, then any request coming from that host with a Unix identity is accepted as being from the identified principal. (A host is identified by its IP address.) This form of authentication obviously offers poor security, but it is by far the most common form used by NFS clients and thus must be supported. The repository currently does not check what port number an NFS request originates from.

Second, a principal can identify itself by directly giving a global user name, with the user@realm syntax. This form of identification is primarily for use by Vesta tools that communicate with the repository through its SRPC interface, such as the repos-ui(1) tools, vrepl(1), and vmaster(1). The current version of the repository client-side libraries uses global identities automatically. Older versions used Unix identities, so for compatibility the repository will still accept them.

Calling processes that identify themselves using global names do not supply and authenticate their group memberships. Instead, the repository has a table of global group memberships for global users, and it looks up a caller's user name in this table to determine which groups the caller belongs to. The repository's group table comes from two sources. First, group memberships for all locally-known users are obtained from the local operating system's user and group databases. Each uid and gid in these databases is translated into a global name as described above, and the results are entered into the repository's group membership table. Second, the repository reads a file of additional group memberships; the syntax of this file is given in a later subsection.

Currently global user names are also authenticated only by origin. The export file can specify that a particular host is trusted to give any global name, or that it is trusted only for global names with a specified @realm suffix.

Finally, in the future a principal may be able to identify and authenticate itself using GSS-API. The repository's export file can specify which hosts GSS-API authentication will be accepted from, and can optionally limit which realms the names can be from. We anticipate that GSS-API will most likely be used as an interface to Kerberos. Since Kerberos realm names are conventionally written in upper case, the repository makes case-independent comparisons in its access checking. Thus a Kerberos principal named "fred@EXAMPLE.COM" will match the Vesta global name "fred@example.com".

When authenticating itself to other processes, the repository determines which flavor to use from the [Repository]default_flavor configuration setting. NFS clients always use the unix flavor. Other clients use the [UserInterface]default_flavor configuration setting by default; this is normally global.

Access controls

The access control on a file or directory in the repository has an owner, a group, and mode bits, similar to ordinary Unix access controls, but there are some differences.

The owner and group are both sets, not singletons. They are represented as the mutable attributes #owner and #group, which are set-valued. Any global user in the owner set has ownership access to the object; any user that is a member of a global group in the group set has group access. The main reason we allow multiple owners and groups is so that replicated data can have a local owner and group in each realm that holds a copy, if desired.

The primary mode bits are represented in the #mode attribute, as the 3-digit octal number obtained by OR-ing the standard Unix mode bits for read, write, and search access by owner, group, or world: 

S_IRUSR   400   read permission: owner
S_IWUSR   200   write permission: owner
S_IXUSR   100   search permission: owner
S_IRGRP   040   read permission: group
S_IWGRP   020   write permission: group
S_IXGRP   010   search permission: group
S_IROTH   004   read permission: world
S_IWOTH   002   write permission: world
S_IXOTH   001   search permission: world
The setuid and setgid mode bits are represented by the #setuid and #setgid attributes. If the first value of #owner that is in the local realm (the owner that will be manifested through the NFS interface) is also a value of #setuid, the setuid bit is set, otherwise not. Similarly, if the first value of #group that is in the local realm is also a value of #setgid, the setgid bit is set, otherwise not.

A source that does not have an #owner, #group, or #mode attribute inherits the corresponding value from its parent directory, while a missing #setuid or #setgid attribute defaults to empty. This form of inheritance is needed in order to provide objects that do not have their own attributes with an access control. It is also useful to save some space in the repository, since an object whose parent has the same value for some access control does not need to store its own copy of that attribute.

The repository does not store execute permission bits for files. Instead, each file has a single "executable" flag, which is immutable for immutable files, mutable for mutable files. If the executable flag is true, the file's execute permission bits are the same as its corresponding read bits; if not, they are all off. The executable flag and execute permission bits are implemented in the NFS glue layer above the repository proper. At the VestaSource interface, the 0111 bits of a #mode are always search permissions. When the Unix chmod() function is invoked on a file through the repository's NFS interface, the file's executable flag is formed as the logical OR of the three executable bits given. When stat() is invoked, the executable permission bits are formed as described above.

A few complications arise when the repository is accessed using the NFS protocol, since there is more information in a Vesta access control than can be represented by NFS. To obtain the numeric owner uid reported in an object's NFS attributes, we search for a global owner user@realm, where @realm is the local realm name. If one is found, the user portion is translated to a numeric id using the local operating system's user database. The group is then translated in the same way. If a locally known user and/or group is not found, special values vforeign_uid and vforeign_gid specified in the Vesta configuration file are used. If more than one locally known user or group is present, one of the alternatives is chosen arbitrarily. If the NFS setattr operation is used to change the owner of an object (that is, if the Unix chown command is used), we first search for all locally known owners and remove them, leaving any other owners unchanged, then add the new owner. Again groups are handled in the same way. Owners and groups that are removed in this way are also removed from the #setuid and #setgid attributes if present.

Access checking

Checking whether a calling process has access permission works as follows.

First, the requested operation is classified by type: unrestricted, agreement (could potentially violate the replica agreement invariant), administrative (restricted to the system administrator), ownership (for example changing the access control), read, write, search, execute, del, setuid, or setgid. The classification will generally be unsurprising; odd cases are treated specifically below.

If the client host is specified in the export file to have readonly access, operations of types administrative, ownership, write, del, setuid, and setgid are refused before considering any of the other rules below.

Almost all operation types are permitted if the requesting process is a Vesta administrator. Three Vesta administrators with slightly different privileges may be configured in vesta.cfg: [Repository]root_user, [Repository]vadmin_user, and [Repository]vwizard_user. The vadmin user is provided as a convenience, so that users can be authorized to administer Vesta without being given the root password. The root user has the same privileges as vadmin, except that root is granted granted blanket permission for setuid and setgid type operations. The vwizard user has the same privileges as vadmin, but is also allowed to perform agreement operations, such as deleting children of master appendable directories without leaving a ghost, creating children in nonmaster appendable directories, etc. Except for the initial creation of a globally unique name under /vesta for packages that originate at your site (see warning below), the vwizard feature should be used only in emergencies, since it can create inconsistencies between replicas. Typically the administrative user names will be root@realm (where realm is the local realm name), vadmin@realm, and vwizard@realm.

An unrestricted operation is always permitted, with no checking.

An administrative operation is permitted only if the requestor is a Vesta administrator.

An ownership operation is permitted if the requestor's principal name (or one of its aliases) matches one of the owner names in the access control.

Read, write, search, and execute operations are checked as follows: If the corresponding world permission bit is set, access is granted. If the requestor's principal name (or an alias) matches one of the owner names in the access control, and the corresponding owner permission bit is set, then access is granted. If one of the requestor's group names matches one of the group names in the access control, and the corresponding group permission bit is set, then access is granted. Otherwise access is denied. This algorithm is intentionally slightly more liberal than that used in Unix, but matches it in the common cases.

Operations on attributes are classified as follows: Reading attributes is unrestricted. Changing an attribute whose name does not begin with # is a write operation. With a few exceptions noted below, changing an attribute whose name begins with # is an ownership operation.

Changing #owner is normally an ownership operation; that is, as in Unix System V, users are allowed to "give away" their files. Some Vesta tools (such as vrepl with the -a flag) need this ability. However, if [Repository]chown_semantics is set to "BSD", changing #owner through the NFS interface is an administrative operation. Some Unix programs expect BSD semantics and may behave oddly with System V semantics.

Clearing or removing a value from the #setuid or #setgid attribute is an ownership operation, but setting or adding a value to #setuid is a setuid operation, to #setgid a setgid operation. A setuid operation is permitted if the requestor is root, or if the requestor is the owner and the value being added is his own name (including aliases). A setgid operation is permitted if the requestor is root, or if the requestor is the owner and the value being added is a group that he is a member of.

Deletion from an appendable directory, leaving a ghost, is a del operation. If [Repository]restrict_delete is set to 1, del operations have the same permission checking as administrative operations. If it is set to 0, del operations have the same permission checking as write operations on the directory.

When an object is created, if the caller's user name (not including aliases) is one of the owners of the new object's parent, then the new object's #owner attribute is not automatically set, allowing the object to inherit its parent's owner list. Otherwise, the caller's user name (but not any of its aliases) is automatically set into the new object's #owner attribute as the sole owner.

Each volatile root is owned by the "runtool" user with mode 755. Because sources under a volatile root do not have attributes, these permissions are inherited by all their descendents. Thus, anyone can examine the files and directories in the volatile tree, but only the special runtool user can make changes.

Export file

As mentioned above, the repository's export file specifies which client hosts may access the repository and what forms of identification and authentication they may use. The file format is as follows.

A pattern can be an Internet hostname, an Internet hostname pattern with "?" or "*" characters as wildcards, an IP address in dotted notation, or an IP subnet in the form address/netmask, where address is in dotted notation, and netmask either is in dotted notation, or is a single integer indicating how many bits are set from the left (for example, /24 = /255.255.255.0) . The "?" wildcard matches any one character except a dot ("."), while the "*" wildcard matches zero or more characters that are not dots. Ordinary characters match regardless of case.

A level can be one of the following strings, case insensitive: allow, readwrite, rw, readonly, ro, deny. The levels readwrite and rw are synonyms for allow; ro is a synonym for readonly.

A flavor can be one of the following strings, case insensitive: unix, global, gssapi, all, any. Any is a synonym for all.

If no (level, flavor, arg) tuples appear for a given pattern, "allow all" is supplied by default. If the flavor is omitted from a tuple, it defaults to all.

The optional arg is an argument to the flavor. Only "allow global", "readonly global", "allow gssapi", and "readonly gssapi" take an argument. This argument is a pattern for the realm that the global name must originate from, with "?" and "*" wildcards matched as in hostname patterns. If this argument is omitted, any global name is accepted.

When checking whether a request should be admitted, the repository scans the export file looking for the last (pattern: level, flavor, arg) tuple whose pattern, flavor, and arg match. If one is found, its level applies to this request. If not, the request is denied.

Here is an example: 

; Sample export file
16.0.0.0/8: readonly global *.example.com 
*.x.example.com: allow unix, allow global x.example.com
badguy.x.example.com: deny
*.z.example.com: allow global y.example.com
The first line says that any host on network 16.0.0.0 may have read-only access to the repository if it supplies a global identity of the form user@*.example.com. The second line says that hosts whose names match the pattern *.x.example.com may have read/write access to the repository if they supply either a Unix identity, or a global identity of the form user@x.example.com. If a request matches both lines, the second one will take precedence. The third line makes the host badguy.x.example.com an exception; it is not granted any access. The fourth line allows hosts from the domain *.z.example.com to use names in the global realm y.example.com.

Group file

As mentioned above, the repository's group file gives a (partial) list of which global groups various global principals belong to. The file format is as follows.

Here name is a global user name (user@realm) and each group is a global group name (^group@realm). The line says that name is a member of each group listed. If the same name appears on several lines, the memberships accumulate.

Here is an example: 

// Vesta repository group file for x.example.com
tom@x.example.com: ^users@y.example.com ^admins@y.example.com
dick@x.example.com: ^users@y.example.com
harry@y.example.com: ^users@y.example.com ^admins@y.example.com
The first line says that besides the locally-known groups he is a member of, tom@x.example.com is also a member of some y.example.com groups. This could be useful if some sources from y.example.com are replicated in the x.example.com repository and tom needs access to them. The situation is similar for dick. On the third line, harry@y.example.com is indicated to be a member of some y.example.com groups. This line could be useful if harry accesses the x.example.com repository remotely when logged in at y.example.com. Without it, harry would not obtain his group memberships when accessing the x.example.com repository, since this repository does not preload its group table with the local user and group database from y.example.com.

Aliases and the alias file

As an added convenience feature, the repository can be told to recognize a global user or group name as having one or more aliases. When a client authenticates itself as possessing a name that has some aliases, it is given the privileges of the aliases as well as those of the authenticated name. Aliases are applied after the client's principal identification is translated to a global name, so they work even with Unix identification. The [Repository]root_user is not allowed as an alias.

For example, if user mann has accounts in realms x.example.com and y.example.com, and he sometimes logs in at x.example.com and remotely accesses the repository at y.example.com, it would be useful for the y.example.com repository to regard mann@x.example.com as having the alias mann@y.example.com.

The aliasing mechanism is neither symmetric nor transitive by default:

A user alias can be employed as another way to get group-like functionality. For instance, if user manager@x.example.com should be automatically allowed access to files owned by tom, dick, and harry@x.example.com, they can be listed as aliases.

Groups can be aliased as well. For example, if realms x.example.com and y.example.com are working together on the Wonka project and both have a local group named wonka, it can be useful to alias ^wonka@x.example.com to ^wonka@y.example.com (and vice versa) at both sites. That way, users at either site can obtain group access to a directory replicated from the other site, even if only one of the two groups is on the directory's group access control list.

The alias file has the same syntax as the group file, except that user names may appear in place of group names. It is meaningless for a user name to be aliased to a group name, or vice versa. When a reciprocal alias is needed, both directions must be included explicitly. For the examples above, the aliases file would read: 

# Sample aliases file
mann@x.example.com: mann@y.example.com
mann@y.example.com: mann@x.example.com
manager@x.example.com: tom@x.example.com, dick@x.example.com, harry@x.example.com
^wonka@x.example.com: ^wonka@y.example.com
^wonka@y.example.com: ^wonka@x.example.com
Limitations

Changes to the local passwd and group databases are not all tracked automatically by the repository. This can result in users not getting quite the right privileges after a change until the next time the repository's access control tables are reloaded. The addition of a new user or new group is handled automatically, but other cases are not, such as when a user is added to a group, is removed from a group, is given a different uid, or is deleted from the system. (The repository has no way of knowing when such a change has happened, and for reasons of efficiency it maintains its own in-memory cache of the local passwd and group databases.)

In more detail, whenever the repository encounters a uid or gid that is unknown to it (i.e. that has been added since the repository last acquired user/group information from the OS), it attempts a complete reload of all access control data both from the host OS and from the export, alias, and group files. This can fail if there is a parsing error in the export, alias, or group file, in which case an error message is logged by the repository. If that happens, the repository simply adds an entry for the new uid/gid after getting information from the OS.

The vaccessrefresh utility can be used to explicitly ask the repository to pick up changes in the OS user/group databases and its own group, alias, and export files. When using vaccessrefresh, any errors in parsing the export, alias, and group files will be reported to the user. Restarting the repository will also cause it to pick up all access control changes, but this is no more effective than using vaccessrefresh.

Using the Unix newgrp command with a password to dynamically enter a new group that you are not a static member of is not supported by the repository. Currently you may get the group's privileges when going through the NFS interface, but you will never get them through the SRPC interface. In the future this feature is more likely to be disabled entirely than made to work in all cases.

If several different user names map to the same Unix uid, the repository will not treat them all as aliases for one another. A user logged in as this uid will get the privileges only of the first name that maps to it.

Although gssapi is recognized as a flavor in the export file, GSS-API authentication is not yet implemented, so allowing it has no effect.

Flags

-h
Print a brief usage message and exit.
-d level
Turn on additional debugging output (to standard error) or other debugging modes. The default is [Repository]debug_level. The level is the bitwise or of the following:
  • 0x0001 - SRPC - log a message when a client dies (or the like).
  • 0x0002 - NFS interface - log arguments and results.
  • 0x0004 - FdCache - log debugging messages.
  • 0x0008 - SourceOrDerived::doDeletions - log disposition of each ShortId.
  • 0x0010 - SourceOrDerived::doDeletions - log debugging messages.
  • 0x0020 - SourceOrDerived::doDeletions - suppress actual deletion (unlink).
  • 0x0040 - VDirEvaluator - log debugging messages.
  • 0x0080 - Recovery - do not try to finish an incomplete weed.
  • 0x0100 - VMemPool - log debugging messages.
  • 0x0200 - Startup - if a file named "core" exists in the current directory, rename it to core.DATE.TIME, where DATE.TIME are the current date and time.
  • 0x0400 - NFS interface - log references to stale handles.
  • 0x0800 - Mastership transfer - log debugging messages.
  • 0x1000 - File copy-on-write - log occurrences.
  • 0x2000 - Access control - log parsing of tables.
  • 0x4000 - Replication - log debugging messages.
-f first-ckp
Specifies which checkpoint recovery should begin with. By default, the newest committed checkpoint is used, if any. Checkpoints are numbered 1, 2, 3, etc. A checkpoint number of 0 means to recover entirely from logs, starting at the beginning of time. Recovery always continues to the end of the last log file.

Configuration

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

metadata_root
All files and directories in the underlying filesystem that are needed by the repository server are named relative to metadata_root. This value must begin and end with "/". The repository server does a chdir() to this directory.
log_dir
The recovery log and checkpoints go in metadata_root/log_dir. The log_dir must end with "/" (or be empty).
log_dir2
If set to a nonempty string, a backup copy of the recovery log goes in metadata_root/log_dir2. The log_dir2 must end with "/" if not empty.
backup_ckp
If set to 1, and log_dir2 is also set, a backup copy of each checkpoint is also stored in metadata_root/log_dir2.
sid_dir
The directory tree rooted at metadata_root/sid_dir is used to store source and derived files, with names derived from their ShortIds. The sid_dir must end with "/" (or be empty).
ShortId_sorter
External program to sort a ShortIdsFile and remove duplicates. Currently this is a pipeline involving Unix sort and uniq; in the future, if memory is a constraint, it could be a fast external sort using temporary disk files.
umask
The repository sets its file mode creation mask (umask) to the given value. The default is 022.
threads
Sets the number of threads to be forked by the NFS server. Zero means to use the process's main thread only.
bufreqs
Sets the size of the buffer associated with the UDP socket on which NFS requests are received. The units are (a generous estimate of) the maximum size of an NFS request.
dup_table_max
Number of NFS RPC replies to buffer for duplicate suppression. If a client retransmits a request that the server has recently replied to, it will be replied to from the buffer instead of being redone.
NFS_port
UDP port on which NFS service is exported.
NFS_host
Host from which NFS service is exported. This must be the host on which the repository process is running.
ShortIdSRPC_port
UDP port on which the SRPC interface that supports SourceOrDerived is exported.
ShortIdSRPC_host
Host from which ShortIdSRPC is exported. This must be the host on which the repository process is running.
VestaSourceSRPC_port
UDP port on which the SRPC interface that supports VDirSurrogate and related classes is exported.
VestaSourceSRPC_host
Host from which VestaSourceSRPC is exported. This must be the host on which the repository process is running.
debug_level
Sets the default value for the -d flag (see above).
realm
Name of the local access control realm. When translating numeric Unix user and group identifiers received through the NFS interface into global names, the repository first converts the numeric id to a name using values from the local /etc/passwd and /etc/group files (or equivalent), then appends @realm to the local name. In addition, the character "^" is used as a prefix for global group names to distinguish them more clearly from user names.
default_flavor
The identity flavor that the repository uses when authenticating itself to other processes. Normally set to global at present.
root_user
The user with this global name has system administrator access permission to the repository. The root user has complete access permission to all files and directories in the repository, but cannot violate their defined properties; for example, even he cannot modify immutable files and directories. This value is normally set to root@realm.
vadmin_user
The user with this global name has system administrator access permission to the repository. Also, this user owns the appendable root and mutable root unless they have explicit #owner attributes. The vadmin user has the same permissions as root, except that (1) vadmin cannot create setuid or setgid files that are owned by other users or groups, and (2) through the NFS interface, vadmin cannot read or write files or directories that he does not have permission for according to the ordinary permission bits, but he can freely chmod or chown any file or directory to grant himself access. The conventional setting for this value is vadmin@realm.
vwizard_user
The user with this global name has the same privileges as vadmin, but is also allowed to perform agreement operations, such as deleting children of master appendable directories without leaving a ghost, creating children in nonmaster appendable directories, etc. Except for the initial creation of a globally unique name under /vesta for packages that originate at your site (see warning below), the vwizard feature should be used only in emergencies, since it can create inconsistencies between replicas. A typical setting for this value would be vwizard@realm.
vadmin_group
This global group is the owning group of the appendable root, mutable root, and the roots of all volatile directory trees unless they have explicit #group attributes. A typical setting for this value might be ^vadmin@realm.
runtool_user
This user owns the roots of all volatile directory trees. In fact, because children of volatile and evaluator directories do not have attributes, they always inherit this user as their owner. This user should not be made the owner of anything in the appendable and mutable directory trees. A typical setting for this value would be vruntool@realm.
vforeign_uid
A numeric Unix user id. If none of the values of a source's #owner attribute is of the form user@realm, where realm is the local realm as defined above and user is a locally known user, then when viewed through the NFS interface, the source's owner appears to be vforeign_uid. Typically, one would define a special local Unix user named vforeign for this purpose, and set this value to that user's uid.
vforeign_gid
A numeric Unix group id. If none of the values of a source's #group attribute is of the form ^group@realm, where realm is the local realm as defined above and group is a locally known group, then when viewed through the NFS interface, the source's group appears to be vforeign_gid. Typically, one would define a special local Unix group named vforeign for this purpose, and set this value to that group's gid.
group_file
The file used to specify (additional) members for global groups. See the Access Control section above. Typically set to repos/group.
alias_file
The file used to specify equivalent alternative names for global users. See the Access Control section above. Typically set to repos/alias.
export_file
The file used to specify which remote hosts are allowed to access the repository and what authentication they must use. See the Access Control section above. Typically set to repos/export.
chown_semantics
If this parameter is set to BSD, only an administrator can change a source's #owner attribute through the NFS interface. If it is set to System-V, the current owner can also change it. The current owner can always change this attribute through the SRPC interface.
restrict_delete
If this parameter is set to 1, the NFS interface restricts the delete and rename operations in an appendable directory to the system administrator; if 0, they are available to the directory's owner.
allow_symlink
If this parameter is set to 1, symbolic links can be created through the NFS interface using the symlink() system call; if 0, they cannot. Note that symlinks can be created only in appendable directories even with this flag turned on, and that the "latest" symlink is created through the VestaSource SRPC interface and is unaffected by this flag.
VMemPool_size
Initial size of the repository's internal memory pool. The default is one machine page. A larger size is preferable, say 0x100000 (one megabyte).
VMemPool_minGrowBy
Minimum amount to grow the memory pool when it fills. The default is one machine page. A larger size is preferable, say 0x80000 (1/2 megabyte).
VMemPool_base
Address where the memory pool should be mmap'ed. This memory must remain contiguous as the pool grows, so a large address should be chosen, well above any other memory that may be allocated. A typical choice would be 0x26600000000. The default is to pass NULL to mmap and let it choose an address, but this does not work well; mmap does not guarantee it will be able to extend the resulting block contiguously.
cow_max
Maximum number of file copy-on-write operations in progress at once. If not set, the default is 4.
VestaSourceSRPC_max_running
Maximum number of VestaSource SRPC requests being serviced at once. This paramater is optional. If it's not set, it defaults to 32.
VestaSourceSRPC_max_blocked
Maximum number of VestaSource SRPC requests to queue up before rejecting connections. Requests are only queued up when there are already VestaSourceSRPC_max_running outstanding requests. This paramater is also optional. If it's not set, it defaults to 8.
VestaSourceSRPC_read_timeout
Maximum number of seconds the server will wait for data from a client during a VestaSource SRPC requests. This prevents the server from waiting indefinitely for suspended or misbehaving clients. If it's not set, it defaults to 3600 (1 hour). (Note that the time between individual calls on a connection can be longer than this.)
ShortIdSRPC_max_running
Maximum number of ShortId SRPC requests being serviced at once. This paramater is optional. If it's not set, it defaults to 32.
ShortIdSRPC_max_blocked
Maximum number of ShortId SRPC requests to queue up before rejecting connections. Requests are only queued up when there are already ShortIdSRPC_max_running outstanding requests. This paramater is also optional. If it's not set, it defaults to 8.
ShortIdSRPC_read_timeout
Maximum number of seconds the server will wait for data from a client during a ShortId SRPC requests. This prevents the server from waiting indefinitely for suspended or misbehaving clients. If it's not set, it defaults to 3600 (1 hour). (Note that the time between individual calls on a connection can be longer than this.)
EvaluatorDirSRPC_read_timeout
Maximum number of seconds the server will wait for data from an evaluator when calling it for information about the contents of a volatile directory to service a request. This prevents the server from waiting indefinitely for a suspended or misbehaving evaluator. If it's not set, it defaults to 3600 (1 hour). (Note that the time between individual calls on a connection can be longer than this.)
master_hint
Specifies the "hint" to be placed in the "master-repository" attribute for objects mastered in the local repository. (You can think of this as the "public address" of the repository, which may be different than the address local clients use to contact the repository.) This string can either be empty (in which case "master-repository" attributes will not be set) or a host name and TCP port number in the format host:port.

The following users, groups, files, and directories must be present to run the repository.

Users [Repository]root_user, [Repository]vadmin_user, [Repository]runtool_user, and [Repository]vforeign_uid must exist and must all be distinct. User root_user should be root, vadmin_user should be a special account for vesta administration, and everyone_user should be a dummy account with logins disabled. User vforeign_uid should probably also have logins disabled. Users who need access to sources replicated from a repository in another realm and with no local owner defined could be allowed to su to it, but it's probably better to add a local owner to the owner access control list of such sources.

Groups [Repository]vadmin_group and [Repository]vforeign_gid must exist and must be distinct. Group vadmin_group may be a special group for vesta administration, or some standard system group (such as group 0) may be used. Users who need privileged access to sources replicated from a repository in another realm could be made members of vforeign_group, but it's probably better to add a local group to the group access control list of such sources.

The filenames [Repository]group_file, [Repository]alias_file, and [Repository]export_file must all be defined, but they need not all exist. However, if the export file is empty or does not exist, no client hosts will have permission to access the repository.

The repository server must not be run by root! User [Repository]vadmin_user can run it, or another user can be chosen.

The directory configured as [Repository]metadata_root must exist and must be writable by the user who will be running the repository server. So must its subdirectories [Repository]log_dir and [Repository]sid_dir. This directory tree must be used by only one repository process at a time; the repository uses file locking on its log to ensure this.

The directories configured as [UserInterface]AppendableRootName and [UserInterface]MutableRootName must exist and must be owned by the user who will be mounting the repository (if root will not be mounting it). Normally these directories must be created separately on every Vesta client machine because they are on a non-shared filesystem ("/").

After the repository is started and mounted for the first time, the following directories must be created, with access permissions as described. You create these directories and set their permissions in the ordinary way with "mkdir" and "chmod"; you may of course need to "su" to root or to Vesta administrator ([Repository]vadmin_user) to be able to do this.

[UserInterface]DefaultPackageParent
The default directory to put new packages in. Ordinarily a subdirectory of the appendable root, named with an Internet domain name belonging to the repository's owner. See the warning below about creating new names under the appendable root. Must be writable by users who will be creating packages here. After creating this directory, you should also "cd" to it and type the command "vattrib -s type package-parent", which tells vcreate(1) that it is okay to create packages in it.
[UserInterface]DefaultWorkParent
The default parent directory for mutable working directory trees belonging to individual users. Typically the same as [UserInterface]MutableRootName (that is, /vesta-work), in which case it already exists. If you choose to make this directory writable by all Vesta users, vcheckout(1) will automatically create a subdirectory under it for each user when that user first checks out a package; if not, you will have to create those subdirectories by hand.
[UserInterface]TempDir
A temporary directory used by the repository tools. Typically /vesta-work/.tmp. Must be writable by all Vesta users.
[Run_Tool]VolatileRootName
A directory used as the mount point for the repository's volatile directory tree. Typically /vesta-work/.volatile. Must be readable and writable by the user(s) who will be mounting the repository.

Warning: Every name created directly under /vesta (more precisely, directly under [UserInterface]AppendableRootName) must be globally unique across all repositories in the universe in the past, present, or future. If you break this rule, your repository will have problems participating in the replication protocol with those repositories that have conflicting names. We strongly recommend that every name you create in this directory be an Internet domain name that belongs to you; if everyone does so, uniqueness is guaranteed. Do not reuse a name unless you are certain that the previous use of the name has been permanently deleted in all repository replicas, including replicas that might be recreated from backup media or the like.

Note: If you do not have a registered domain name of your own, a good alternative is to use a working email address that you intend to keep permanently. Change the "@" to "_" so that the name will not have to be quoted when used in the import section of a Vesta model. For example, if you are an ACM member and have registered the address johnsmith@acm.org, you could create the Vesta name /vesta/johnsmith_acm.org without fear of causing a naming conflict. This works because "_" is not a legal character in domain names.

See Also

vesta-intro(1), repos-ui(1), mountrepos(8), umountrepos(8), vmount(8), vaccessrefresh(8)

Author

Tim Mann 

Last modified on Tue May 25 10:05:42 EDT 2004 by ken@xorian.net
     modified on Tue Apr 29 23:17:11 PDT 2003 by mann
This page was generated automatically by mtex software.