Chapter 4. User-Level Access to ClearCase Data

“Smooth running” with ClearCase requires careful coordination of:

This chapter discusses the architecture of the user base, along with the UNIX-compatible access-permissions model for VOBs, views, and the file system objects they contain. We also discuss ClearCase-specific mechanisms, which control access to VOB databases.

(Procedural details on implementing your desired data-access strategy are deferred to Chapter 6, “Setting Up ClearCase VOBs”.)

Users: Usernames and Groups

ClearCase relies on standard UNIX facilities for identifying users and assigning them to groups:

  • Each user has a username (“login” name) and a principal group, which are established by an entry in the password database.

  • The user can also belong to any number of additional groups; the group list is specified by entries in the group database.

Each host has a local passwd(4) and group(4) file. Many organizations supplement these local files with network-wide NIS maps, named passwd and group. Figure 4-1 shows how a user named derek gets his principal group and an additional group-list assignment.

Figure 4-1. Establishing a User's Group Assignments

Note: On HP-UX hosts, the file /etc/logingroup establishes a user's initial group assignments. See group(4) for details.

Since ClearCase is a distributed application, it is essential that user/group identities be consistent across the network. For example, ClearCase will not work properly if a developer has user-ID 453 on one host, and user-ID 309 on another host.

Network-Wide ClearCase Administrator

We recommend that you create a “ClearCase administrator” identity in your network's user base, and that all shared ClearCase data structures—VOBs and shared views—be owned by that user. This is not a requirement, but it will facilitate ClearCase administration.

In the remainder of this manual, we assume that a ClearCase administrator, vobadm, has been created. If most developers belong to a single group, make vobadm a member of that group, too.

Note: You may be tempted to let root perform all ClearCase administrative tasks. But many organizations prefer to have a separate identity for application-specific administration. Moreover, root is often not the “same user” throughout the network—one host's root is another host's nobody.

VOBs and Views: Owner and Groups

For purposes of determining access permissions, each ClearCase VOB and view has an owner, a principal group, and an optional group list. (Note the similarity to the user-identification structures introduced in the preceding section.) The multiple-group facility for these data structures supports development environments where (1) users don't all belong to the same group, and (2) non-group members are prohibited from accessing data:

  • Rule: For a user to have permission to read a VOB's data, one of the user's groups must be the VOB's principal group.

  • Rule: To read a VOB's data through a particular view, one of the view_server's groups must be the VOB's principal group.

  • Rule: For a user to have permission to modify a VOB's data, the user's principal group must be (any) one of the VOB's groups.

Figure 4-2 illustrates these access paths; the mechanics are discussed in “Read Access by Processes”.

Figure 4-2. Multiple-Group Support for VOBs and Views

The .identity Directory

At the operating system level, each file system object has a single group, not a list. Accordingly, a ClearCase-specific mechanism is required to implement the group list of a VOB or view. Each VOB storage directory and view storage directory has a .identity subdirectory. Entries in this directory establish the group list, and also the owner and principal group (Figure 4-3).

Figure 4-3. The .identity Directory of a VOB or View

Use the describe -vob command to list a VOB's identity information. (There is no “-view” option to the describe command; use a standard ls -l command on the .identity subdirectory of the view storage directory.)

To modify a VOB's identity information, use the protectvob command. You must be the root user to use this command:

% su
Password: <enter root password>
# cleartool protectvob -add_group demos,guest /vobstore/proj.vbs

 <messages and verification prompts>

VOB ownership:
  owner drp
  group dvt
Additional groups:
  group demos
  group guest

Caution: Do not try to change this information directly, using standard UNIX commands.

Note: There is no comparable command for modifying a view's identity information.

Effect of Creator's `umask' Setting

A user's current umask(1) setting affects the way in which a mkvob or mkview command creates a new data structure. In general, a more restrictive umask produces a VOB or view that has more limited accessibility:

  • For a new VOB, the user's umask determines the access permissions on the VOB's top-level directory element—its root directory. (The umask is subtracted from mode 777, in the standard manner.) This directory is the “gateway” to the entire VOB, and thus provides an important access-control point. To access any file system object that appears in that VOB (including view-private objects created in VOB directories), a user process must have permission to traverse the VOB's directory element hierarchy, starting with the VOB root directory.

  • For a new view, the user's umask determines the access permissions on the view storage directory itself, and on all directories within the view's private storage area. (Again, the umask is subtracted from mode 777, in the standard manner.) To access a view-private object, a user process must have permission to traverse the directory structure in the view's private storage area.

Note that access to view-private objects is subject to two kinds of permissions checking: on the VOB's logical hierarchy of directory elements, and on the view's physical hierarchy of directories within its private storage area.

Example: Two VOBs and Two User Groups

Suppose that you wish to place two source trees libpub and monet, into separate VOBs, to be accessed by two groups, dvt and mon, as shown in Figure 4-4.

Figure 4-4. Planning Access to Development Sources

As suggested in “Network-Wide ClearCase Administrator”, suppose that you are the VOB administrator, belonging to both groups. (It really doesn't matter which of these is your principal group, and which is established in the group database.)

vobadm:@!bork%$:555:30:VOB administrator:/:/bin/csh
    (/etc/passwd or NIS passwd map entry: group 30 is dvt)
    (/etc/group or NIS group map entry: group 35 is mon)

Creating the VOBs

The following procedure creates the VOBs and adjusts their permissions. (For more on creating VOBs, see Chapter 6, “Setting Up ClearCase VOBs”.)

  1. Prepare a physical storage location—(This is the only step that requires root privileges. If you do not have root access, you can enlist the aid of someone who does, for this step only.) You will create VOB storage directories within a globally-accessible directory tree, at /vobstore on host sol.

    % su
    Password: <enter root password>
    # mkdir /vobstore

    With many UNIX variants, the disk partition mounted as the root file system ( / ) is quite small, and will not accommodate ClearCase VOBs. In such cases, create the actual directory in a large partition, and link it to /vobstore. For example:

    # mkdir /usr/vobstore
    # ln -s /usr/vobstore /vobstore
    # exit

  2. Assuming the appropriate user identity—Make sure that you are logged in as user vobadm, in group dvt.

    % newgrp dvt
    % id
    uid=555(vobadm) gid=30(dvt)

  3. Create the first VOB storage directory—Be sure to use the location you prepared in Step #1. This command creates the libpub VOB.

    % cd /vobstore
    % cleartool mkvob -tag /vobs/libpub -public libpub.vbs
    Vob tag registry password: <enter password>
    Comments for "libpub.vbs":
    Sources for libpub.a library
    Created versioned object base "libpub.vbs".
    VOB ownership:
      owner vobadm
      group dvt

  4. Switch your principal group—Remain user vobadm, but group mon your principal group.

    % newgrp mon
    % id
    uid=555(vobadm) gid=35(mon)

  5. Create the second VOB storage directory—This command creates the monet VOB.

    % cleartool mkvob -tag /vobs/monet -public monet.vbs
    Vob tag registry password: <enter password>
    Comments for "monet.vbs":
    Sources for monet project
    Created versioned object base "monet.vbs".
    VOB ownership:
      owner vobadm
      group mon

Controlling Access to the VOBs

You (vobadm) are the owner of both new VOBs, by virtue of having created them. By changing groups with the newgrp command, you created VOBs that belong to different groups. In general, all members of the dvt group will have complete access to the libpub VOB; likewise, all members of the mon group will have complete access to the monet VOB.

To complete implementation of the VOB-access scheme depicted in Figure 4-4, the only necessary adjustment is dictated by the first rule in “VOBs and Views: Owner and Groups”, all members of the mon group must have dvt as an additional group in order to enable read access to the libpub VOB:

    (all members of the mon group ....
    ... get group 30 (dvt—the libpub VOB's principal group) as an additional group
        assignment in the /etc/group file or NIS group map)

Access to Individual File System Objects

On a day-to-day basis, developers deal with individual file system objects, rather than entire VOBs and views. In general, the standard UNIX access-permissions model applies to ClearCase-controlled file system data. Files, directories, and links stored in VOBs and views all have stat(2) records, which contain the familiar user-group-other and read-write-execute information.

Access-Control Settings

To standard UNIX operations, a VOB appears to be a directory tree, containing directories, files, and links. Each of these file system objects has a single owner, a single group, and an access mode. That is, its access-control settings seems completely “ordinary” to the ls –l command:

% ls -l
total 50
-r--r--r--    1 drp      dvt          224 Feb 19 15:34 Makefile
-rwxrwxr-x    1 drp      dvt        14956 Feb 19 15:34 hello
-r--r--r--    1 drp      dvt           79 Feb 19 15:34 hello.c
-r--r--r--    1 drp      dvt          168 Feb 19 15:34 hello.h
-rw-rw-r--    1 drp      dvt         1504 Feb 19 15:34 hello.o
-r--r--r--    1 drp      dvt          232 Feb 19 15:34 msg.c
-rw-rw-r--    1 drp      dvt         2168 Feb 19 15:34 msg.o
-r--r--r--    1 drp      dvt          511 Feb 19 15:33 util.c
-rw-rw-r--    1 drp      dvt         3228 Feb 19 15:34 util.o

(Depending on the UNIX variant, the -g option to the ls command either turns off display of group memberships, or turns it on.)

What the developer sees is a combination of view-resident objects and VOB-resident objects (the view's virtual workspace). The distinction is important for this discussion, because different access-control mechanisms apply:

  • Each element and all of its versions have the same access-control settings. The protect command controls these settings, with -chown, -chgrp, and -chmod options. The -chmod option controls the “read” and “execute” (r and x) fields only, not the “write” (w) field—all versions in VOB storage are always read-only to standard UNIX commands.

    You might complain that checkout creates a version that is writable, not read-only. But the checked-out version that a user edits is not a VOB object—it is a view-private file. All the versions in VOB storage (that is, in the VOB's source storage pools) remain read-only after a checkout.

  • Each view-private object has a standard UNIX access-control settings. The standard chown(1), chgrp(1), and chmod(1) commands control these settings.

Notes on VOB/View Interactions

The mechanisms for changing access modes work intuitively. There are some special considerations, involving situations where both a VOB and view are involved:

  • The cleartool protect -chmod command is independent of the standard chmod(1) command. If a file is checked-out, changing the access mode of the element does not affect the mode of the view-private file which is the checked-out version.

  • The cleartool protect -chmod command cannot be used on an unshared derived object. Using this command on a shared derived object does not affect the current view, even if that derived object appears in the view. The standard chmod command can be used on any derived object that appears in a view—shared or unshared.

  • To create a new view-private file, directory, or link, a user must have “write” permission in the parent directory, which is a VOB object (a directory element).

Initialization of Access-Control Settings for VOB Objects

When a new element or VOB symbolic link is created (with mkelem, mkdir, or ln -s), its access-control settings are initialized in the standard UNIX manner:

  • The creator of the element or link becomes its owner.

  • The creator's principal group becomes the group of the element or link. (In some UNIX variants, a new object gets the group of its parent directory; but ClearCase always uses the creator's group.)

  • The creator's current umask determines the access mode of the element or link.

Initialization of Access-Control Settings for View Objects

When a view-private object is created, its access-control settings are initialized in the same way, from the creator.

Access-Control Settings for Physical Data Storage

All of the access-control information described in the preceding section is maintained in VOB and view databases. But ultimately, version-controlled data is stored in storage pool directories and data container files. (See Chapter 2, “ClearCase Data Storage”.) These are ordinary UNIX file system objects and, as such, are subject to standard UNIX access controls.

Note: Users don't reference these objects directly, and so should not be concerned with their access permissions.

ClearCase manages the permissions on storage pools and data containers automatically, preventing accidental (or mischievous) deletion of VOB data:

  • All storage pools and data containers are owned by the VOB owner and belong to the VOB's principal group. (This is also the principal group of the VOB owner, unless it has been “given away” with a cleartool protectvob -chgrp command.)

  • All storage pools have access mode 755, allowing them to be read and searched by anyone.

  • A version's data container has the same access mode as the version itself (which, in turn, has the same access mode as the element). Both the version and its data container are maintained in a read-only state.

All changes to a VOB's physical data storage is performed by its dedicated vob_server process, which runs as the VOB owner. As appropriate, this process temporarily makes certain data structures writable, performs the change, then restores the data structures to their read-only state.

How Processes Access ClearCase Data

On UNIX systems, all data access is performed by processes, which run with certain identities:

  • A ClearCase client process (cleartool, xclearcase, clearmake, and so on) runs with the user's UID and with all of the user's groups—principal group and entire group list.

  • All access to ClearCase data must go through a view. That is, data is accessed by the associated view_server process, which runs with the UID and all the groups of the view's owner.

Most often, users work in their own “private” views, which they have created themselves. This simplifies the access-control issues, since the user's ClearCase client processes and the view_server process run under the same identity. The effective question is:

Does the user have permission to access the VOB data? 

When users work in shared views, or attempt to “peek into” other users' views, the access-control issues become more involved. Some or all of the following access paths are traversed when a user attempts to use ClearCase data:

  • The user's process accesses data in view storage.

  • The user's process accesses data in VOB storage.

  • The view's view_server process accesses its view-private storage.

  • The view's view_server process accesses VOB storage.

Figure 4-5 illustrates these access paths, all of which are subject to permissions checking. Note that the view is “in the middle”—it is both a data repository, accessed by a user process, and a process that accesses VOB storage.

Figure 4-5. Data Access Paths

Usually, the owner of a file or directory has no trouble accessing it. The following sections apply in situations where access to data is to be granted at the group level—that is, where (1) users don't all belong to the same group, and (2) non-group members are prohibited from accessing data.

Read Access by Processes

A process gains “read by group member” access to VOB or view data if any of the process's groups matches the group of the data (Figure 4-6). Note that the process (potentially) has multiple groups; the data file or directory necessarily has a single group. In addition, there is a VOB-level restriction: one of the process's groups must be the VOB's principal group.

Figure 4-6. `Read' Access through Group Membership

Write Access by Processes

ClearCase's mechanism for determining who can modify VOB data is finer-grained than the standard UNIX mechanism. (See “ClearCase-Level Access Permissions”.) But there is also an overall VOB-level restriction: in order to create a new element or VOB symbolic link, a user's principal group must be (any) one of the VOB's groups. This follows from the fact that all file system objects in the VOB must belong to one of the VOB's groups.

Figure 4-7. `Write' Access through Group Membership

There are no comparable group-level restrictions on the creation of new view-private objects.

ClearCase-Level Access Permissions

The standard UNIX model for handling the “write” (w) permission is insufficient for ClearCase's needs. ClearCase relies on a more elaborate hierarchy to determine what in a VOB can be modified, and by whom:

  • the root user (superuser)

  • the VOB owner (that is, the user who owns the VOB storage area. The user who creates a VOB becomes its owner. A subsequent chown_vob command changes the owner.)

  • the owner of the corresponding element (for modifications to branches and versions)

  • the creator of a type object (for modifications to these objects)

  • the creator of a particular storage pool

  • the user associated with a particular event

  • the creator of a particular version or derived object

  • members of an element's or derived object's group

The root user and the VOB's owner can perform all operations that modify a VOB. Lower levels of the hierarchy have fewer permissions, and not all levels are relevant to every command.

Whenever you enter a cleartool command that modifies one or more VOB objects, this permissions hierarchy is applied automatically to each object, in a command-specific manner. For example:

  • Permission to remove an element with the rmelem command is granted to root, to the VOB owner, and to that element's owner. No one else can remove that element.

  • Permission to checkout an element is granted to all of the same users as in the preceding example, and also to users in the element's group. The command fails if anyone else tries to execute it.

See the ct_permissions manual page for details on how individual commands fit into the permissions hierarchy.

Locks on VOB Objects

The ClearCase permissions scheme is intended for use as a long-lived access-control mechanism. ClearCase also provides for temporary access control, through explicit locking of individual VOB objects. You can use the lock command to restrict or completely prohibit changes at various levels. At the lowest level, you can lock an individual element, or even an individual branch of an element. At the highest level, you can lock an entire VOB, preventing all modifications to it.

When an object is locked, it cannot be modified by anyone, even by root, the VOB owner, or the user who created the lock. (But these users have permission to unlock the object.) The lock command accepts an optional exception list, specifying users for whom the object will not be locked.

Locking Type Objects

As an administrator, you will often find it useful to lock type objects; this prevents changes to the instances of those types. For example:

  • You might lock the branch type main to all but a select group of users. This would allow the select group to perform integration or release-related cleanup work on the main branches of all elements. All other users can continue to work, but must do so on subbranches, not on the main branch.

  • Locking the label type RLS2.3 prevents anyone from creating or moving that label.