Ensure effective administration and security in Rational ClearCase 8.0.1

Using the access control lists introduced in this release

IBM® Rational® ClearCase® release 8.0.1 introduces access control lists (ACLs), which simplify the security of your versioned object bases (VOBs). This article advises administrators on ACL definitions and management, with a focus on replicated environments using Rational® ClearCase MultiSite® software.

John T. Kohl (jtk@us.ibm.com), Senior Software Engineer, IBM

author photoJohn Kohl, a senior software engineer at IBM, works on IBM Rational ClearCase configuration management software. He led the development team implementing ClearCase VOB ACLs and the team implementing parallel loading of CCRC web views. He has worked on many areas of ClearCase, including the kernel file system (MVFS), ClearCase MultiSite, security, and core business logic.



14 June 2013

Introduction

IBM® Rational® ClearCase®, Version 8.0.1 adds access control lists (ACLs) to govern access to objects in a versioned object base (VOB). With ACLs, you have more flexibility to assign and manage access permissions for VOB elements. You also gain a finer-grained access model that allows read-only access and independent control for different kinds of element modifications.

The Rational ClearCase Information Center covers many of the introductory concepts about Rational ClearCase ACLs (see the Resources section for a link). If you have not done so already, review the "Comparison of OS-defined groups and ACL authorization" topic.

This article briefly reviews the ACLs model for Rational ClearCase 8.0.1, explains some of the new access control capabilities, and suggests deployment and upgrade plans, with emphasis on the globally distributed enterprise using IBM® Rational® ClearCase MultiSite® replication for VOBs.


ACLs model, policies, and rolemaps

Rational ClearCase VOB ACLs are administered with two types of objects that are defined in the VOB: policies and rolemaps. Each rolemap is associated with one policy. Policies and rolemaps use principals to identify users.

Principal
A principal is the identity used as part of an access control entry (ACE). Principals come in several kinds, most notably Role, User, and Group.
 
Policies
Policies have four sections: VOB, policy, rolemap, and element. Each section specifies an access control list, or ACL, which is a list of ACEs. Each ACE identifies a principal and the permissions granted to that principal. Policies typically specify Role principals, thereby defining role names used in the policy. Policies can also list specific users or groups.
 
Rolemaps
Rolemaps assign specific users or groups to the roles defined in the associated policy.
 

The rolemap and policy pair generates an effective ACL (EACL) for each section. The EACL lists the authorized accounts and groups and specifies their permissions to operate on an object.

The VOB object (representing the VOB as a whole) and each policy, rolemap, and element are assigned to one controlling rolemap each. When a user attempts to access a VOB, a policy, a rolemap, or an element, ClearCase checks the controlling rolemap's EACL and verifies that the applicable section grants the user permission. If permission is not granted, the operation is blocked.

The following figures show a graphical representation of policies and rolemaps, as well as the policy and rolemap editors. They illustrate how an administrator can define policies and rolemaps and use them to protect elements. Figure 1 shows a policy, an implementing rolemap, and the resulting effective ACL. It also shows two objects protected by the rolemap (and its effective ACL). Figure 2 shows a policy and two implementing rolemaps, illustrating the ability to define a template in the policy and assign roles in the rolemap, and then assign protected objects to one rolemap or another.

Figure 1. A policy and rolemap
Rolemap, policy, and the generated effective ACL
Figure 2. A policy and two rolemaps
Two rolemaps, one policy, linked to objects

Figure 3 shows the Policy editor (available in ClearTeam Explorer). Principals are listed on the left; the ACLs for each metatype are on the right. Figure 4 shows the editing pane that allows changing permissions for the selected principal.

Figure 3. Policy editor showing summary
Principal list on left, permissions on right
Figure 4. Policy editor showing permission editor
Principals on left, permission editor on right

Figure 5 shows the rolemap editor. Role assignments are listed on the left; the associated policy's details are on the right.

Figure 5. Rolemap editor
Role assignments on left, permissions on right

Element protection in ACLs-enabled VOBs

When ACLs are enabled in a VOB, Rational ClearCase checks them when users operate on elements. Element access is controlled by multiple independent permission bits. For example, a user might have permission to make a new branch of an element (mod-branch permission), but not have permission to apply a new label to a version (mod-label permission).

For administrative convenience, the individual permission bits are grouped into levels: Read, Change, and Full. The levels are cumulative. Change incorporates all permissions from Read and includes more permissions (for example, mod-task). Likewise, Full adds more permissions to Change. You can specify any combination of levels or individual permission bits when you define your policies.

Figure 6 shows the groupings for element permissions, as displayed by ClearTeam Explorer. The Read group is on the left, with Change in the middle and Full on the right.

Figure 6. Element permission groupings
Read on left, Change in middle, Full on right

The "Grantable permissions" information center topic lists the permissions that can appear in policies. The reference pages for cleartool subcommands lists the required permissions for each operation. For example, the checkout command reference page indicates what permissions are needed to check out a version of an element (select Reference > Rational ClearCase command reference > Alphabetical list of all commands > checkout).

Because Rational ClearCase provides multiple independent permission bits, you have greater flexibility to grant limited permission to VOB users. For example, you can grant some users read-only access to elements and other users read-write access to those elements. Before ACLs were added in the 8.0.1 release, you could do this only by using custom-written pre-operation trigger scripts that determined which modification operations could proceed.

If you are upgrading VOBs created with earlier releases, and you define and enable ACLs in your VOBs, you might be able to retire certain triggers that you used for access control. However, triggers that are not access-related might still be useful. For example, you would still want triggers that trace check-ins and automatically start builds.


Tips on working with multiple VOBs (families)

If you administer multiple VOB families, you can copy policies and rolemaps between them. This helps you manage all of the families with similar access styles.

You can use cleartool cppolicy (with or without the -replace option) to copy a policy within a VOB or from one VOB to another. Likewise, you can copy rolemaps with cprolemap. Within a VOB, cprolemap will preserve the link between the rolemap and the policy that it implements. When copying between VOBs, cprolemap will make the new (or replaced) rolemap implement the DefaultPolicy.

If you want to copy the contents of a rolemap or policy but not change the other relations (protecting rolemap, implemented policy), you can dump a policy or rolemap's contents to a file, and then use the file as input to a replace operation. For example:

Listing 1. Copying a policy and replacing a target policy
cleartool lspolicy -out /tmp/policy.txt P1@/my/vobtag
cleartool mkpolicy -nc -replace -set /tmp/policy.txt P1@/my/other_vobtag

or

Listing 2. Copying a rolemap and replacing a target rolemap
cleartool lsrolemap -out /tmp/rm.txt R1a@/my/vobtag
cleartool mkrolemap -nc -replace -set /tmp/rm.txt R1a@/my/other_vobtag

ClearCase MultiSite guidance

This section offers guidance and suggestions for planning your VOB ACLs environment in replicated VOBs.

Be sure that you trust replica administrators

Whether or not ACLs are enabled in your VOB family, you must trust the VOB administrator of any replica to keep your data secure. The replica is a complete copy of the VOB. Either with ACLs disabled or enabled, the VOB administrator logged into the VOB server can examine any data in the replica. The administrator might have to take special steps to gain access (such as the security override used in case of accidental lock-out), but it is possible. Therefore, create replicas on VOB hosts only with trustworthy administrators.

The ability to modify VOB data in a family is controlled by object mastership (in addition to any ACLs that may be enforced at one or more replicas). Use object mastership to control which replicas may modify sensitive VOB contents.

ACLs behavior depends on replica-preserving modes

VOB replicas have one of three preserving modes. The three modes differ in their handling of ACLs.

Identities - and permissions-preserving replicas
Identities - and permissions-preserving (or just "fully preserving") replicas use the same user and group identities on replicated objects. They also preserve the permissions ("mode bits") of elements: read/write/execute for user, group, and other. For ACLs, preserving replicas maintain the same users and groups listed in policies and rolemaps. The preserving replicas in a VOB family can effectively share the administration and use of policies and rolemaps for access control. Mastership applies to determine which rolemaps or policies may be modified at which preserving replica.
 
Permissions-preserving replicas
Permissions-preserving replicas do not share user and group identities on replicated objects with other replicas, but they do share the mode bits of elements. For ACLs, a permission-preserving replica maintains its own users and groups listed in policies and rolemaps. It does not share any changes to policies or rolemaps with other replicas in the family. An administrator must define policies and rolemaps separately at each permissions-preserving replica.
 
Non-preserving replicas
Non-preserving replicas use their own user and group identities on replicated objects. They also administer permissions ("mode bits") of elements independently. For ACLs, a non-preserving replica is like a permissions-preserving replica in that it maintains its own users and groups, and it administers its own policies and rolemaps.
 

If your deployment can use fully preserving replicas, it will simplify administration of ACLs. See the "Identities and permissions strategy for VOB replicas" ClearCase information center topic for guidance on which replica models will work in your deployment.

Replacing permissions-preserving or non-preserving replicas with fully preserving replicas

If you have a permissions-preserving or non-preserving replica, and wish to convert it to a fully preserving replica (in order to share ACLs), you should not use chreplica to convert the replica. You should instead create a new fully preserving replica (exported from an existing fully preserving replica) and retire/remove the permissions-preserving or /non-preserving replica.

Rational ClearCase does not provide a tool that will convert all of the identities in a permissions-preserving or preserving replica to match the identities in a fully preserving replica in the family. Converting a replica with chreplica will leave your replica with divergent metadata compared to the other fully preserving replicas in the family.

Adding new VOB families to an existing environment

You might occasionally need to add a new VOB family to an existing environment. When you use the default options to create a VOB on a host at Rational ClearCase 8.0.1 or later, the newly created VOB will enforce ACLs.

If you want all of the replicas to enforce ACLs, create the new VOB and its replicas by using normal options. After you have created the VOB, define any required rolemaps and policies for the fully preserving replicas. You might wish to copy rolemaps and policies from other families (see the Tips on working with multiple VOBs section). If you are creating any non-preserving or permissions-preserving replicas, define new rolemaps and policies for those replicas (see Configure ACLs at each permissions-preserving and non-preserving replica).

If you want some of the replicas not to enforce ACLs, you must use special options when creating VOBs. (See Make a new VOB family with ACLs disabled.)

Adding new replicas to existing families

Each new replica will inherit its ACLs enforcement state from the originating replica. Choose the originating site for the mkreplica operation based on the preserving and ACLs-enabled mode you need.

New fully preserving replica

You must create new fully preserving replicas from an existing fully preserving replica. If ACLs are enforced in the existing fully preserving replicas, they will be enforced in the new replica as well.

New permissions-preserving or non-preserving replicas

You can create a permissions-preserving replica from a fully preserving replica or from a permissions-preserving replica. You can create a non-preserving replica from any existing replica.

To create a permissions-preserving or non-preserving replicas with ACLs disabled, make the replica from an existing replica that has ACLs disabled.

After you create a new permissions-preserving or non-preserving replica that enforces ACLs, or one where you plan to enable ACLs enforcement, you should configure its policies and rolemaps.

Configure ACLs at each permissions-preserving and non-preserving replica

When you create a new permissions-preserving or non-preserving replica in a family that already has ACLs defined, you must define the policies and rolemaps used at that replica. You must also create these policies and rolemaps when you are preparing to enable ACLs for such a replica in a family that you are upgrading to use ACLs.

Define separate policies, rolemaps

For each permissions-preserving or non-preserving replica, define and use separate, locally mastered rolemaps and policies.

Caution:
Sharing policies or rolemaps with other replicas, even though it is possible due to relaxed mastership requirements in permissions-preserving and non-preserving replicas, can lead to surprises when the rolemaps or policies are redefined by other replicas. Some operations replayed at permissions-preserving and non-preserving replicas will change the effective ACL of a rolemap. For example, mkrolemap -replace -policy newpolicy will redefine a rolemap to implement a different policy at all replicas.

Make new policies or rolemaps, and scan or reassign all elements

Choose a naming convention for policies and rolemaps so that you can tell which ones are used at each replica. The names are replicated throughout the VOB family, just like branch or label type names.

In each new permissions-preserving or non-preserving replica (or, during upgrade, in each permissions-preserving or non-preserving replica), make new policies and rolemaps for use at that replica.

  1. Make new policies defining the permissions granted to access the VOB, rolemaps, and policies in the new replica. Make new rolemaps to protect the VOB, rolemaps, and policies.
  2. Reprotect the VOB object, the new policies and the new rolemaps.
  3. Make additional rolemaps or policies for elements. If you make them with the GUI, immediately reprotect them as in the previous step. If you make them with cleartool, you can use the -rolemap local-protecting-rolemap option for either mkpolicy or mkrolemap.
  4. Scan elements to reassign them to the appropriate new rolemaps.

Step 1. Make a local policy and rolemap for metadata

Start by making a local policy to govern access to the VOB and the local rolemaps or policies. Here is a sample policy granting Everyone read access to the VOB, the policies and the rolemaps, and full access to the object's owner and the VOB owner.

Listing 3. Sample of a policy that grants everyone read access
[vob]
Everyone: Read
User:your.domain/vobowner Full
[policy]
Owner-User: Full
User:your.domain/vobowner Full
Everyone: Read
[rolemap]
Owner-User: Full
User:your.domain/vobowner Full
Everyone: Read

You can put this into a file, and then create a policy from that file.

cleartool mkpolicy -nc -set policy-file.txt P1-NPreplica

This policy will work with an empty rolemap, which you can create like this:

cleartool mkrolemap -nc -policy P1-NPreplica R1-NPreplica

You might also wish to copy an existing policy that was defined at a fully preserving replica, then modify it. You can copy a policy or rolemap with the CTE policy or rolemap editor, then edit and save the copy. To use the command line, copy an existing policy or rolemap with the cppolicy or cprolemap subcommands, and then edit the policy or rolemap with chpolicy or chrolemap.

Step 2. Protecting the VOB object and rolemaps with the local rolemap

After you have created policies and rolemaps to protect the VOB object and the local rolemaps or policies, change the protection of those objects.

Listing 4. Continue the previous example to change protection of objects
cleartool protect -chrolemap R1-NPreplica vob:/vobtag
cleartool protect -chrolemap R1-NPreplica policy:P1-NPreplica
cleartool protect -chrolemap R1-NPreplica rolemap:R1-NPreplica

Step 3. Make policies and rolemaps for elements

Once you have a local rolemap set up, you can create additional policies and rolemaps to protect elements. For example, you can set up one policy and two rolemaps, so that different effective ACLs are available for use on elements.

Listing 5. Example of policy-file.txt
[element]
Role:Readers Read
Role:Developers Change
Role:Administrator Full
Listing 6. Example of rolemap-file.txt
Role:Readers --> Everyone
Role:Developers --> Group:your.domain/developers
Role:Administrator --> User:your.domain/admin
Listing 7. Example of rolemap2-file.txt
Role:Developers --> Group:your.domain/restricted
Role:Developers --> User:your.domain/userA
Role:Developers --> User:your.domain/userB
Role:Administrator --> User:your.domain/admin
Listing 8. Examples of mkpolicy and mkrolemap commands
cleartool mkpolicy -rolemap R1-NPreplica -nc -set policy-file.txt P1-elem-NPreplica
cleartool mkrolemap -rolemap R1-NPreplica -nc -policy P1-elem-NPreplica \
 -set rolemap-file.txt R1-elem-NPreplica
cleartool mkrolemap -rolemap R1-NPreplica -nc -policy P1-elem-NPreplica \
   -set rolemap2-file.txt R2-elem-NPreplica

Notice the use of the -rolemap R1-NPreplica option. It specifies the rolemap with effective ACL that guards access to read or modify the new policy or rolemap. We defined the effective ACL of R1-NPreplica above to specify who could read or modify rolemaps or policies. Because R1-NPreplica is mastered in this replica, we can change policy or rolemap permissions without consulting other replicas.

Caution:
You can make these policies and rolemaps using the CTE policy and rolemap editors, but it currently doesn't support the equivalent of the command line's -rolemap R1-NPreplica option. After creating a new rolemap or policy, open the property sheet for it and change the controlling rolemap. Figure 7 shows the property sheet's ACLs tab for a policy. Use the Change button to reprotect the policy. A similar tab is available for the VOB object, rolemaps, and elements.

Figure 7. Reprotecting a rolemap or policy
Controlling rolemap displayed with change button

Step 4, option 1. Reprotecting all elements identically

If you want to reprotect all elements in a VOB to use a single new rolemap, you can do this by listing all elements and processing the list.

To reprotect only the visible elements (those selected by your current view), use this command:

cleartool protect -recurse -chrolemap

To reprotect all elements, use cleartool find -all and process its output. This produces a list of regular names for visible elements and version-extended names for the non-visible elements, one line per element. Process each element with cleartool protect -chrolemap, being careful to quote any embedded spaces or special characters. Example (using Linux xargs):

cleartool find -all -print  | xargs --delim \\n cleartool protect -chrolemap NpreplicaRM

Step 4, option 2. Reprotect elements rolemap-by-rolemap

If the source replica has already divided elements and assigned them to rolemaps, you can use the same groupings of elements in the new replica.

  1. Create new rolemaps, one for each existing rolemap used for elements in the source replica.
  2. For each source replica rolemap, assign all elements protected by that rolemap to a new rolemap in the new replica.
  3. The new replica assigns elements to the same rolemaps that they were assigned in the originating replica. Use describe -fmt "%[objects_protected]Np" rolemap-name for each rolemap used in the originating replica.
  4. Save the output for use as input to a script to reprotect the objects. If you only want to reprotect elements, filter the output to remove policies, rolemaps, and the VOB object.

Listing 9 is an example for one rolemap, using Linux xargs:

Listing 9. Reprotecting all elements from one rolemap to another on Linux
cleartool mount /vob/tag
cleartool setview yourview
cd /vob/tag
cleartool describe -fmt "%[objects_protected]Np" rolemap:RM1 >/tmp/RM1.list
grep ^/ /tmp/RM1.list >/tmp/RM1.element.list
xargs --delim \\n cleartool protect -chrolemap NPreplicaRM </tmp/RM1.element.list

Configure some replicas with ACL enforcement and others without ACLs

If you need some replicas in your VOB family with ACLs disabled, you must prepare the VOB family before enabling ACLs.

Make a new VOB family with ACLs disabled (in the entire family or in one or more replicas)

To make a new VOB family with ACLs disabled in one or more replicas, you must use options when creating the VOB. You cannot disable ACLs in a VOB that has them enabled.

To create a VOB at feature level 8 with ACLs disabled:

  1. Create a VOB at feature level 7, by specifying the -flevel option when making the VOB.
  2. Raise the VOB family feature level to 8 using the chflevel subcommand.

Listing 10 shows an example of the code.

Listing 10. Create a VOB at feature level 8 with ACLs disabled
cleartool mkvob -nc -tag /var/tmp/vobby1 -flevel 7 /var/tmp/vobby1.vbs
cleartool chflevel -replica 8 original@/var/tmp/vobby1
cleartool chflevel -family 8  vob:/var/tmp/vobby1

If you raise the feature level before creating replicas (as shown), it takes fewer steps than raising the feature level after creating replicas. To do it later, you will have to raise the replica feature level at each replica and sync to the VOB mastering replica, and then raise the family feature level.

After you have created a VOB with ACLs disabled, you can make replicas for the family. If you want ACLs disabled in part of the family, you must make at least one non-preserving or permissions-preserving replica. Leave one of these replicas with ACLs disabled, so you can make future replicas with ACLs disabled.

Upgrade an existing VOB family from feature level 7 or lower

When you raise the family feature level to feature level 8, do so at one of the fully preserving replicas in the family (so that all fully preserving replicas will have the same contents for the default policy and rolemap). Raising the feature level to 8 creates the initial policy (DefaultPolicy) and rolemap (DefaultRolemap) but does not enable ACL enforcement.

After raising the family feature level to 8, define additional policies and rolemaps in one of the fully preserving replicas (if they are to enforce ACLs) and in each of the permissions-preserving and preserving replicas that will be set to enforce ACLs (as above). In any permissions-preserving or non-preserving replicas that will not enforce ACLs, you can skip creating local policies and rolemaps.

When you are satisfied with the policies and rolemaps, and the assignment of elements to policies or rolemaps, enable ACLs at one of the fully preserving replicas (cleartool protectvob -enable_acls) and at the permissions-preserving and non-preserving replicas that will enforce ACLs. Do not enable ACLs at other replicas.

ClearCase MultiSite ongoing maintenance

After you have configured your VOB family's replicas, there are some ongoing maintenance is necessary for element protection.

New elements in families with some permissions-preserving or non-preserving replicas

If your family has some permissions-preserving or non-preserving replicas, manage the protections and ownership of new elements in the permissions-preserving or non-preserving replicas and in one of the fully preserving replicas. The ownership (user) of new elements can be managed just as you would manage it without ACLs.

The "Group selection in replicas according to feature level" " information center topic and the mkelem reference page explain the rules used to assign the new element's group and rolemap during import to or from a permissions-preserving or non-preserving replica.

If you have new elements created in a permissions-preserving or non-preserving replica that should not share the parent directory's group or rolemap, you need to reprotect the elements in one fully preserving replica and in the other permissions-preserving and non-preserving replicas. Rational ClearCase cannot automatically determine what rolemap to use to protect these new elements.

The ClearCase MultiSite import log will warn you of imported elements that had a rolemap reassigned during import — an indication that reprotection might be necessary.

Changing the controlling rolemap on existing elements

When you need to reprotect an element to change its controlling rolemap, do it at every permissions-preserving and non-preserving replica and at one fully preserving replica. If you are reprotecting directories, beware that any elements created at other replicas at the same time will not necessarily be protected as you expect. A good practice is to suspend making new elements cataloged in the directory elements that you are reprotecting until all replicas have synchronized and processed the reprotection operation.

If you do have new elements created in parallel with a directory reprotection, you might have different rolemaps protecting that element in fully preserving replicas. You can synchronize all the fully preserving replicas by reprotecting the new elements at one fully preserving replica. This will reset the controlling rolemap in all other fully preserving replicas. You should also reprotect the new elements in the permissions-preserving and non-preserving replicas.


Upgrading existing VOBs and enabling ACLs

When you upgrade existing VOBs to Rational ClearCase v8.0.1 and prepare to enable ACLs, you should understand the supported platforms in v8.0.1, as well as the interoperability restrictions when a VOB enables ACLs.

Older clients and CCRC WAN servers cannot access ACLs-enabled VOBs
A VOB that enforces ACLs rejects clients or WAN servers running older Rational ClearCase releases. All clients and WAN servers need to install v8.0.1 before using such VOBs.
 
Full Rational ClearCase clients or CCRC WAN servers that cannot upgrade to v8.0.1
The supported operating system versions and application server versions have changed in v8.0.1. If you have older clients or WAN servers, you might need to upgrade them. If you have systems that cannot be upgraded to support v8.0.1, you might need to set up a separate VOB replica environment for older clients.
 

Support for older clients when enabling ACLs for new clients

If you must support older clients in a VOB that will enforce ACLs, you can set up a separate replicated environment for the old clients.

  1. Create a non-preserving or permissions-preserving replica for this environment before enabling ACLs in other replicas.
  2. Reconfigure the clients to use the replica environment.
  3. Administer mastership of branch types, branches, elements, UCM streams, and so forth to enable the older clients to complete their work by using the new replicas.
  4. For UCM environments, use posted deliver to complete deliveries between streams mastered at different replicas. See the "About posting work to deliver in Rational ClearCase MultiSite" information center topic.
  5. For non-UCM environments, transfer mastership as necessary to enable merges between branches.

The ClearCase MultiSite guidance section above covers several related topics that apply to this upgrade scenario.

Upgrading without ClearCase MultiSite, or with it when using only fully preserving replicas in the family

If you do not use ClearCase MultiSite in your environment, or you do but all replicas in the family are fully preserving replicas, you can use this procedure to upgrade and enable ACLs.

  1. Upgrade the family feature level, following the guidance in the "Raising the VOB family feature level" information center topic"
  2. Create new rolemaps and policies as needed to protect your elements.
  3. Assign elements to rolemaps (see hints in the Examples section of this article for suggestions on how to protect elements to achieve certain security goals).
  4. If you are using replicas, transfer mastership of new policies or rolemaps to sites that will administer them by using the chmaster operation, such as cleartool chmaster other_replica policy:Policy2 rolemap:Rolemap2
  5. Enable ACLs in the VOB, using protectvob, such as cleartool protectvob -enable_acls /vobs/vobtag
  6. For more guidance, see the "Set up ACLs on new and existing VOBs" "information center topic

Upgrading a family with permissions-preserving or non-preserving replicas

Follow the guidance in the Upgrading an existing VOB family section.


Ongoing maintenance

This section suggests administrative tasks that you might need to perform occasionally, as needed.

Users or groups added or removed from the environment

When users or groups are removed from the operating system environment, you must make appropriate changes to VOBs that reference the deleted users or groups.

  • Before removing the user or group from the environment, use lsrolemap -principal and lspolicy -principal to find references to the user or group that is going to be removed. Modify each rolemap and policy to remove or replace the user or group.
  • Before you remove groups from the VOB group list, find elements owned by the group and change them to another group that will remain in the VOB group list. For example:

    cleartool find -all -group xxx -print | xargs --delim \\n cleartool protect -chgrp
    NEWGRP
  • Before you remove a user from the operating system, find elements owned by the user and change their ownership. For example:

    cleartool find -all -user xxx -print | xargs --delim \\n cleartool protect -chown 
        NEWOWNER
  • If a user or group has been removed from the environment but is still referenced as the owner (group) of elements in a VOB, you can search for such elements and reprotect them by using the elem-owner-check.pl script. See the "Check VOB health before enabling ACLs" information center topic.

Caution:
Filer-hosted UNIX VOBs are especially sensitive to account or group changes, because the NFSv4 protocol uses account and group names in its network protocol. Such VOBs must use only accounts or groups known by name to both the VOB server host and the filer. The accounts or groups are referenced by elements (owner or group field of the element object) and in rolemaps and policies (as User or Group principals).

Changing the element directory structure (refactoring)

ClearCase supports refactoring of a directory structure through its versioned directories capability. You can move or rename elements to reflect changes in how you use the contents. For example, in a Java project, if you rename a class, you must rename the source file to match the class name. With ClearCase versioning, your view's configuration specification can select an older or newer version of each directory, allowing you to "go back in time" to see the project as it existed in a previous state. For example, one view can see the Java classes as they existed before a refactoring operation, and another view can see them after the refactoring.

When you refactor or otherwise move or rename elements, you are changing only the references to the elements; you are not creating new elements. Because each element has only one rolemap controlling it, you must be careful when changing protections of elements involved in past refactoring operations.

Reprotecting elements in directories that have been refactored

Each element has only one protection. Even if different views show the element in different parent directories, the element still has only one protection. You cannot set the protection based on the pathname used to access the element.

When you change the protections (controlling rolemap, owner, group, mode bits) of a tree of elements in a VOB, be careful to find all of the appropriate elements in all versions of directories in your VOB.

In existing directories, you might have elements that are not visible due to prior refactoring, rmname operations, or new elements added on a branch that are not visible in your selected branch or version. You can search the entire VOB for elements not visible in your current view with cleartool find -all -nvisible -print. Carefully analyze whether any of these elements should be reprotected. If you determine that any elements reported by cleartool find should have their protection changed, you can protect them individually with cleartool protect. Listing 11 shows an example.

Listing 11. Reprotecting all non-visible elements
% cleartool find -all -nvisible -print
/vobs/sourcevob/share_dir/lib@@/main/1/removed_file.txt@@
/vobs/sourcevob/otherdir/lib@@/main/1/removed_file2.txt@@
…
% cleartool protect -chrolemap SharedComponentRolemap \
 /vobs/sourcevob/share_dir/lib@@/main/1/removed_file.txt@@
Changed protection on "/vobs/sourcevob/share_dir/lib@@/main/1/removed_file.txt".

Here is an example of a VOB with some elements that have been added, renamed, and removed between releases. It illustrates some surprising results when you recursively protect elements in directories where elements have been renamed, moved between directories, added, or removed.

Listing 12. First release tree
vobroot
+-subdir
 +file1
 +file2
+-directory2
  +file3
Listing 13. Second release tree
+-subdir
 +file1
+-directory2
 +file2
 +file3 (moved from subdir to directory2)
  +file4
Listing 14. Third release tree
+-subdir
 +file1
+-directory2
 +file2
 +file4
  (file3 rmname'd)

If you recursively protect directory2 (with something like cleartool protect -chown -recurse directory2 or any of -chrolemap, -chgrp, or -chmod flags), the results differ depending on which view is used to change protection.

If you reprotect in a Release 1 view, the changes apply to directory2, file3.

  • Looking in a Release 2 view, file1, file2, and file4 have old protection, file3 has new protection.
  • Looking in a Release 3 view, file2, and file4 have old protection.
  • If you reprotect in a Release 2 view, the changes apply to directory2, file2, file3, file4.
  • Looking in a Release 1 view, file1 has old protection, file2 and file3 have new protection.
  • Looking in a Release 3 view, file1 has old protection, file2 and file4 have new protection.
  • If you reprotect in a Release 3 view, the changes apply to directory2, file2, file4.
  • Looking in a Release 1 view, file2 has new protection, file1 and file3 have old protection.
  • Looking in a Release 2 view, file2 and file4 have new protection, file1 and file3 have old protection.

The bold type shows where files in the same directory (as seen in a particular release view) do not share the same protections. However, in the view where the protections were changed, all elements in a given directory share the same protection.


Using Microsoft Windows and UNIX with the same VOBs

Rational ClearCase VOB ACLs are stored internally in the VOB database in numeric form, using the native ID style of the VOB server host. The internal IDs are translated to names when displayed by the CLI or GUI.

When you use both Microsoft Windows and UNIX systems to access a VOB, the user or group names are used to convert identities between UNIX form and Windows form. Whenever you put a User or Group principal into a rolemap or policy, you must ensure that the same name can be converted to a numeric ID on both Windows and UNIX platforms. If names do not match, then you will encounter errors accessing VOB objects, displaying ACLs, or modifying ACLs.

When using a filer to host UNIX VOBs, a similar condition applies. All of the User and Group entries in rolemaps or policies must be known by name to the NFSv4 protocol used between the VOB server and the filer. Those names must also be known to Windows computers so that ACL translation works properly.

Note:
You must not use an account name known only to UNIX in your VOB's ACLs if you have Windows clients (and vice versa for Windows VOBs and UNIX clients).

For more details on configuring a filer for ACLs-enabled VOBs, see the "Using a network filer for ACL-enabled VOB storage" information center topic.


Advanced protection

This section identifies several scenarios for protecting elements, rolemaps, policies, and VOBs.

Hide rolemaps or policies

If you do not want your end users to read the list of authorized users or groups in your VOBs, you can restrict the visibility of policies and rolemaps.

Each policy and rolemap has a controlling rolemap, just as each element has a controlling rolemap. The controlling rolemap's effective ACL has sections listing the accounts with access to read the policy or rolemap. If the effective ACL grants read-name permission, the user can read the name of the rolemap or policy. If the effective ACL grants read-info permission, the user can read the role mappings or policy definition. If users have read-info on both the rolemap and its policy, they can read the effective ACL applied by the rolemap.

By default, rolemaps and policies are protected by the DefaultRolemap. When you create new rolemaps and policies with cleartool, you can specify the controlling rolemap. This will govern who may read and/or modify the new rolemap or policy.

For example, you can create a policy and rolemap to hide contents of other policies or rolemaps.

Listing 15. Sample policy
[policy]
User:your.domain/vobowner Full
Role:VOB-Users read-name
[rolemap]
User:your.domain/vobowner Full
Role:VOB-Users read-name
Listing 16. Sample rolemap
Role:VOB-Users --> Group:your.domain/developers

If you apply this rolemap to protect other rolemaps or policies, only the administrator (User:your.domain/vobowner) can modify the policy or rolemap, and only members of the your.domain/developers group may see the names of the policy or rolemap. Users will not be able to see the contents of the rolemap or policy.

Warning:
When you restrict the visibility of rolemap or policy contents or names, the error messages displayed for users when they encounter a permission failure are much less useful for diagnosing what permissions need changing to permit the operation.

Delegate administration of rolemaps and policies

Through careful definition of policies and rolemaps, you can enable other users or groups to administer rolemaps and policies in a VOB. For example, you may trust a project leader to add or remove users from a rolemap protecting the project's elements.

To delegate permission to edit a rolemap or policy:

  1. Create a Delegating policy and Delegating rolemap that will, together, define an EACL that lists the users who are authorized to modify a project rolemap or policy. This policy and rolemap will be administered by the VOB administrator. The VOB administrator can change the contents of this policy or rolemap, thereby changing the users authorized to administer the project rolemap or policy.
  2. Create a project rolemap or policy, or both, that is protected by the delegating rolemap. Only this policy and rolemap will be administered by the project leader. The project leader is unable to modify other policies or rolemaps.
  3. Assign elements to the project rolemap. Whenever the project leader modifies the project policy or rolemap, the elements are reprotected.

Figure 8 shows multiple policies and rolemaps, linked together to delegate permission to administer a rolemap. A team administrator may modify the Team1 rolemap and Team2 rolemap rolemaps to add or remove access to the teams' elements.

Figure 8. A network of policies and rolemaps
Team rolemaps controlled by a delegating rolemap

Enforce ACLs for only a subset of clients

If you need to exempt a subset of your clients from ACLs controls on a VOB, you must use a VOB family with at least one permissions-preserving or non-preserving replica. Because permissions-preserving and non-preserving replicas can independently enable ACLs, you can have some replicas with ACLs enabled and some with ACLs disabled.

You can use the same methods described above in Supporting older clients. Assign the clients that should not enforce ACLs to a Rational ClearCase registry region that uses the replicas with ACLs disabled.

Recover from goofs

If you make a mistake when defining ACLs, and it's in a way that prevents you from accessing the policy or rolemap, you can log into the VOB server as the VOB owner and use a recovery mode to reset the ACLs. For details, see the "Recovering from incorrect policies and rolemaps" information center topic.


Examples: Using ACLs to protect elements in various ways

The remainder of this article presents several scenarios that achieve different security goals. It shows how to define policies and rolemaps to protect elements to achieve each goal. You can use it as a library of ideas and techniques for administering your VOBs to achieve your own specific security goals.

Component and source directory maintained by one team, used by other teams

In this scenario, a UCM component or a directory should be readable and modifiable by a maintenance team and readable to other teams, but not world-readable. To configure this, assign users to groups in the OS: all developers are members of the alldev group; component maintainers are members of both the alldev and maintgroup groups. Next, create (1) a policy defining Reader and Maintainer roles, and (2) a rolemap assigning team members to those roles by group membership. Finally, use this rolemap to protect the UCM component root or the directory.

Listing 17. Example of a policy input file (/tmp/policy-file.txt)
[element]
Role:Admin Full
Role:Maintainer Change
Role:Reader Read

If your read-only users use dynamic views and need to create view-private files in these directories, then you should also grant them dir-write permission.

Listing 18. Example of a policy input file with extra permissions for Reader
[element]
Role:Admin Full
Role:Maintainer Change
Role:Reader Read,dir-write
Listing 19. Example of a rolemap input file (/tmp/rolemap-file.txt)
Role:Maintainer --> Group:yourdomain/maintgroup
Role:Reader --> Group:yourdomain/alldev
Role:Admin --> User:yourdomain/vobadm

If you would like to have only a few users be in the Maintainer role, without using an OS group, you can rearrange your rolemap as Listing 20 shows.

Listing 20. Example of a rolemap input file with users instead of a group
Role:Maintainer --> User:yourdomain/maint1
Role:Maintainer --> User:yourdomain/maint2
Role:Maintainer --> User:yourdomain/maint3
Role:Reader --> Group:yourdomain/alldev

After creating the policy and rolemap files, create the policy and the rolemap. Then make a new directory element with the new rolemap.

Listing 21. Policy, rolemap, and directory creation example
% cd /vobs/sourcevob
% cleartool mkpolicy -set /tmp/policy-file.txt -nc GeneralPolicy
% cleartool mkrolemap -set /tmp/rolemap-file.txt -nc -policy GeneralPolicy 
    SharedComponentRolemap
% cleartool co -nc .
% cleartool mkdir -nc -rolemap SharedComponentRolemap share_dir
% cleartool ci -nc .
% cleartool describe -eacl /vobs/sourcevob/component_dir
directory version "component_dir@@/main/1"
 created 2012-06-15T09:38:29-04:00 by Test User (testuser.alldev@testhost)
 protected by rolemap: "SharedComponentRolemap"
 Element Protection:
 User : testuser : rwx
 Group: alldev : rwx
 Other: : ---
 element type: directory
 predecessor version: /main/0
 effective access for user "testuser": Change
 effective access control lists:
 Group:atria.com/maintgroup Change
    Group:atria.com/alldev Read

New elements created inside this shared directory will be protected by the same rolemap (unless otherwise specified during mkelem or mkdir).

If you have existing sources to reprotect (or a new UCM component root directory), rather than the mkdir operation, run a recursive protect on the existing directory (be sure to consider the issues described in the Reprotecting elements in directories that have been refactored section):

Listing 22. Sample of code to run a recursive protect command
% cleartool protect -chrolemap SharedComponentRolemap -recurse /vobs/sourcevob/share_dir

After the elements are protected by this protecting rolemap, a user in the alldev group but not in the maintgroup group can read but not modify the elements.

Listing 23. Sample of commands blocked by an access check
% cleartool ls -dir share_dir
share_dir@@/main/1 Rule: /main/LATEST
% cleartool co -nc share_dir
cleartool: Error: No permission to perform operation "checkout".
Access Control List "directory element" in rolemap:SharedComponentRolemap 
 does not grant you modify-checkout permission.
cleartool: Error: Unable to check out "share_dir".

Common component directory shared by multiple teams, individual projects accessible by individual teams

In this scenario, a UCM component or a directory should be readable and modifiable by a maintenance team and readable to other teams, but not world-readable. Individual UCM components or directories are also protected such that individual teams each have full access only to their respective UCM component or directory, while the common UCM component is readable by all teams.

In this example, we'll create a single policy and four rolemaps to protect our one shared resource, and three projects. For the projects, we'll configure one project by individual OS user access, a second project by single group access, and a third project by multiple OS group access.

We first define our policy to give our administrators and developers complete access and our readers read access.

Listing 24. Example policy input file (/tmp/policy-file.txt)
[element]
Role:Admin Full
Role:Developer Full
Role:Reader Read

If your read-only users use dynamic views and need to create view-private files in these directories, then you should also grant them dir-write permission, as Listing 25 shows.

Listing 25. Example policy input file with extra permission for Reader
[element]
Role:Admin Full
Role:Developer Full
Role:Reader Read,dir-write

We now define a rolemap to protect our shared directory listing members of all three projects explicitly, by either user or group.

Listing 26. Example of a rolemap input file (/tmp/rolemap-shared-file.txt)
Role:Developer --> Group:yourdomain/maintgroup
Role:Admin --> User:yourdomain/vobadm
Role:Reader --> User:yourdomain/proj1_userA
Role:Reader --> User:yourdomain/proj1_userB
Role:Reader --> Group:yourdomain/proj2_group
Role:Reader --> Group:yourdomain/proj3_install_group
Role:Reader --> Group:yourdomain/proj3_doc_group

As in the previous example, create a policy and rolemap with the above entries. When that is done, you can reprotect the common directory tree with the cleartool protect command variant listed above.

We now want to isolate individual projects to specific groups. To do this, we reuse the same policy, but, as we define additional rolemaps, we do not specify any users or groups for the Reader role.

Listing 27. Example of a rolemap input file for the first project(/tmp/rolemap-project1.txt)
Role:Admin --> User:yourdomain/vobadm
Role:Developer --> User:yourdomain/proj1_userA
Role:Developer --> User:yourdomain/proj1_userB
Listing 28. Example of a rolemap input file for the second project(/tmp/rolemap-project2.txt):
Role:Admin --> User:yourdomain/vobadm
Role:Developer --> Group:yourdomain/proj2_group
Listing 29. Example of a rolemap input file for the third project(/tmp/rolemap-project3.txt):
Role:Admin --> User:yourdomain/vobadm
Role:Developer --> Group:yourdomain/proj3_install_group
Role:Developer --> Group:yourdomain/proj3_doc_group

As above, you can reprotect different UCM components and directories with the three newly created rolemaps. In this manner, a user in the proj2_group, for example, would have no access to the directories protected by the first or third rolemap, full access to the directories protected by the second rolemap, and read access to the directories protected by the shared rolemap defined earlier.

Most sources modifiable by entire team, small subset only visible to a few accounts

In this scenario, a source tree should be modifiable by the entire development team and unreadable to others. A small subset of the tree should be modifiable/accessible only by a few named users, and unreadable to the rest of the development team and to others.

In our example, we'll create a single policy and two rolemaps. One rolemap will protect most of the tree. The other will protect the restricted subset of the tree. For the main rolemap, we'll put a group into the role that grants maintenance access. For the restricted rolemap, we'll put just a few users into that role.

We first define our policy to give our administrators complete access and developers change access.

Listing 30. Example of a policy input file (/tmp/policy-file.txt):
[element]
Role:Admin Full
Role:Developer Change
Listing 31. Sample policy creation command
cleartool mkpolicy -nc -set /tmp/policy-file.txt GeneralPolicy

You now define a rolemap to protect the main source tree.

Listing 32. Example of a rolemap input file (/tmp/rolemap-main.txt):
Role:Developer --> Group:yourdomain/devgroup
Role:Admin --> User:yourdomain/vobadm
Listing 33. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy -set /tmp/rolemap-main.txt MainRolemap

As in the previous example, create a policy and rolemap with the above entries. After that is done, you can reprotect the source tree with the cleartool protect command variant listed above. Only the administrator and accounts that are members of devgroup will have access to the source tree.

Next, define a rolemap to restrict access to the small subset. To do this, we reuse the same policy but assign the roles differently.

Listing 34. Example of a rolemap input file for the first project (/tmp/rolemap-restricted.txt)
Role:Admin --> User:yourdomain/vobadm
Role:Developer --> User:yourdomain/restricted_userA
Role:Developer --> User:yourdomain/restricted_userB
Listing 35. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy -set /tmp/rolemap-restricted.txt \
  RestrictedRolemap

As above, you can reprotect the small subset of elements with this rolemap to limit access to the administrator and to restricted_userA and restricted_userB. No other accounts will have access to elements protected by this rolemap.

When users with access to the restricted subset load a web or snapshot view, they will get all of the elements. When normal users load a web or snapshot view, they will skip the restricted elements.

Listing 36. Example of a snapshot view load output (user with access to restricted and main elements)
% cleartool update -add var/tmp/myvob
Making dir "var/tmp/myvob".
Processing dir "var/tmp/myvob".
Making dir "var/tmp/myvob/lost+found".
Processing dir "var/tmp/myvob/lost+found".
End dir "var/tmp/myvob/lost+found".
Making dir "var/tmp/myvob/src".
Processing dir "var/tmp/myvob/src".
Making dir "var/tmp/myvob/src/open".
Processing dir "var/tmp/myvob/src/open".
Loading "var/tmp/myvob/src/open/open1.txt" (10 bytes).
Loading "var/tmp/myvob/src/open/open2.txt" (10 bytes).
End dir "var/tmp/myvob/src/open".
Making dir "var/tmp/myvob/src/restricted".
Processing dir "var/tmp/myvob/src/restricted".
Loading "var/tmp/myvob/src/restricted/restricted1.txt" (10 bytes).
Loading "var/tmp/myvob/src/restricted/restricted2.txt" (12 bytes).
End dir "var/tmp/myvob/src/restricted".
End dir "var/tmp/myvob/src".
End dir "var/tmp/myvob".
Done loading "/var/tmp/myvob" (Loaded 9 objects, copied 0 KB, skipped 0 unreadable 
objects).
Summary:
 Loaded Objects: 7 (0 skipped)
  Total size: 0 KB
Listing 37. Example of a snapshot view load output (user with access only to main elements)
% cleartool update -add var/tmp/myvob
Making dir "var/tmp/myvob".
Processing dir "var/tmp/myvob".
Making dir "var/tmp/myvob/lost+found".
Processing dir "var/tmp/myvob/lost+found".
End dir "var/tmp/myvob/lost+found".
Making dir "var/tmp/myvob/src".
Processing dir "var/tmp/myvob/src".
Making dir "var/tmp/myvob/src/open".
Processing dir "var/tmp/myvob/src/open".
Loading "var/tmp/myvob/src/open/open1.txt" (10 bytes).
Loading "var/tmp/myvob/src/open/open2.txt" (10 bytes).
End dir "var/tmp/myvob/src/open".
cleartool: Warning: Unable to load "var/tmp/myvob/src/restricted": Permission denied.
End dir "var/tmp/myvob/src".
End dir "var/tmp/myvob".
Done loading "/var/tmp/myvob" (Loaded 6 objects, copied 0 KB, skipped 1 unreadable 
objects).
Summary:
 Loaded Objects: 6 (1 skipped)
 Total size: 0 KB
cleartool: Warning: Total 0 unreadable scopes and 1 unreadable elements were not
 loaded due to insufficient permissions; please contact your ClearCase administrator
 and request access if these elements are required in your workspace.

Restricted team can see only its own code

In this scenario, a restricted team (say, employees of a subcontractor) can access only sources for their one component. The rest of the source tree is inaccessible to this team, but accessible to the main team. The main team can also access the restricted team's component (to integrate or build its code into the product).

We set up one policy to define a role that can access elements. Then we define three rolemaps: one for the restricted team's component, one for the other components, and one for the VOB root directory.

The VOB root directory element will be protected with a rolemap that grants read access to the restricted team and modify access to the main team.

Listing 38. Example of a policy input file (/tmp/policy-file.txt):
[element]
Role:Admin Full
Role:Developer Change
Role:Reader Read
Listing 39. Sample policy creation command
cleartool mkpolicy -nc -set /tmp/policy-file.txt GeneralPolicy
Listing 40. Example of a rolemap input file for the main team (/tmp/rolemap-source-tree.txt)
Role:Developer --> Group:yourdomain/maingroup
Role:Admin --> User:yourdomain/vobadm
Listing 41. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-source-tree.txt MainRolemap
Listing 42. Example of a rolemap input file for the restricted team (/tmp/rolemap-restricted.txt)
Role:Developer --> Group:yourdomain/restrictedgroup
Role:Developer --> Group:yourdomain/maingroup
Role:Admin --> User:yourdomain/vobadm
Listing 43. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-restricted.txt RestrictedRolemap
Listing 44. Example of a rolemap input file for the VOB root (/tmp/rolemap-vobroot.txt)
Role:Reader --> Group:yourdomain/restrictedgroup
Role:Developer --> Group:yourdomain/maingroup
Role:Admin --> User:yourdomain/vobadm
Listing 45. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-vobroot.txt VOBRootRolemap
Listing 46. Sample protection and mkdir commands
cd /your/vob/root
cleartool protect -chrolemap VOBRootRolemap -nc .
cleartool co -nc .
cleartool mkdir -nc -nco -rolemap RestrictedRolemap restrict
cleartool mkdir -nc -nco -rolemap MainRolemap src
cleartool ci -nc .

After the directories are created under the protection of their respective rolemaps, any future elements created beneath them will be initially protected by the same rolemap as their first parent directory. Elements created in /your/vob/root/src are protected by MainRolemap; elements created in /your/vob/root/restrict are protected by RestrictedRolemap.

Change role assignments for accounts

In this scenario, we start with the previous protection model of a source tree, which can be modified by the entire development team, and a small subset of the tree that is modifiable or accessible by only a few named users. If the project staffing changes, you might need to add or remove access to the restricted area for individual accounts.

Add access to the restricted subset for another user

To add access for another user, use the CTE Rolemap Editor to edit the rolemap or cleartool chrolemap to modify the RestrictedRolemap rolemap. Add restricted_userC to the Developer role.

Listing 47. Sample command adding a user to the restricted rolemap
cleartool chrolemap -role Developer -add User:yourdomain/restricted_userC \
  -c 'add userC' RestrictedRolemap

Remove access to the restricted subset from a user

To remove access from a user, use the CTE Rolemap Editor to remove the user from a role, or use cleartool chrolemap to modify the rolemap.

Listing 48. Sample command removing a user from the restricted rolemap
cleartool chrolemap -role Developer -remove User:yourdomain/restricted_userC \
  -c 'remove userC' RestrictedRolemap

Metadata-only user cannot load a view

In this scenario, a user is authorized to read metadata from the VOB but has no access to any elements in the VOB. The user will get errors on any attempt to load the VOB into a snapshot or web view.

To implement this scenario, protect the VOB object to allow read access to any user, and protect the VOB root directory element to allow access only by developers.

Listing 49. Example of a policy input file (/tmp/policy-file.txt)
[element]
Role:Admin Full
Role:Developer Change
Role:Reader Read
Listing 50. Sample policy creation command
cleartool mkpolicy -nc -set /tmp/policy-file.txt GeneralPolicy
Listing 51. Example of a rolemap input file for the VOB object (/tmp/rolemap-vobobj.txt)
Role:Reader --> Everyone:
Role:Admin --> User:yourdomain/vobadm
Listing 52. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-vobobj.txt VobObjRolemap
Listing 53. Example of a rolemap input file for the VOB root directory element (/tmp/rolemap-source-tree.txt):
Role:Developer --> Group:yourdomain/maingroup
Role:Admin --> User:yourdomain/vobadm
Listing 54. Sample rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-source-tree.txt MainRolemap
Listing 55. Sample protection commands
cleartool protect -chrolemap VobObjRolemap vob:/myvob
cleartool protect -chrolemap MainRolemap /myvob

After these protections are in place, any user not listed in MainRolemap will get failures attempting to load a snapshot or web view from the VOB, something like the code in Listing 53.

Listing 56. Sample code that fails to load a VOB into a snapshot view
% cleartool update -add myvob
cleartool: Error: Unable to determine version for VOB root directory element.
cleartool: Error: Unable to access "/myvob": Permission denied.
cleartool: Error: 1 config spec load rule problems encountered.
cleartool: Error: Unable to add config spec load rules for update.

Developer granted additional access to critical files, and then loads the view

In this scenario, a developer can access a subset of noncritical directories and files but does not have access to business-critical files and directories. A load of a developer's snapshot or web view will contain only the noncritical files. The developer can check out and update these files.

Later, the developer is promoted to a privileged developer who can access to both noncritical and critical directories and files.

To implement this scenario, create a developer policy that can support both developer and privileged developer rolemaps. Create two rolemaps, one for developer and one for privileged developer.

Listing 57. Example of a developer policy input file (/tmp/policy-dev.txt):
[element]
Role:Developer Change
Listing 58. Sample policy creation command
cleartool mkpolicy -nc -set /tmp/policy-dev.txt DevPolicy
Listing 59. Example of a privileged developer rolemap input file for the VOB object (/tmp/rolemap-priv-dev.txt)
Role:Developer --> User:yourdomain/priv-dev-user
Listing 60. Sample privileged developer rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy \
 -set /tmp/rolemap-priv-dev.txt PrivDevRolemap
Listing 61. Example of a developer rolemap input file for the VOB root directory element (/tmp/rolemap-dev.txt)
Role:Developer --> User:yourdomain/dev-user
Role:Developer --> User:yourdomain/priv-dev-user
Listing 62. Sample developer rolemap creation command
cleartool mkrolemap -nc -policy GeneralPolicy -set /tmp/rolemap-dev.txt DevRolemap

In the VOB, create two directories, directory-priv-dev and directory-dev, protected by PrivDevRolemap and DevRolemap, respectively (similar to the previous restricted team example). Under each directory, two file elements are created.

The developer creates a snapshot view and loads the VOB. The view contains only directory-dev and two file elements within in. These two noncritical files can be checked out and updated.

The developer is then promoted to a privileged developer with a change to the PrivDevRolemap rolemap.

Listing 63. Sample command to add a user to the privileged rolemap
cleartool chrolemap -role Developer -add User:yourdomain/dev-user PrivDevRolemap

After the rolemap change, the developer can update the snapshot view. The update will load directory-priv-dev with its two file elements. The developer can check out and update the business-critical files in the directory.

Manage access simply by using only operating system groups

In this scenario, we want to protect each element with an effective ACL that is defined in terms of an operating system group. To do this simply, we create a policy and a rolemap for each group. The policy grants the permission to the group directly (not using a role). The rolemap is empty.

Listing 64. Example of a policy input file (/tmp/g1-policy-file.txt):
[element]
User:yourdomain/vobadmin Full
Group:yourdomain/group1 Change
Listing 65. Sample policy creation command
cleartool mkpolicy -nc -set /tmp/policy-file.txt G1-policy
Listing 66. Sample rolemap creation command
cleartool mkrolemap -nc -policy G1-policy G1-rolemap

After the G1-rolemap has been created, you use it to reprotect existing elements so they can be modified by accounts that are members of the operating system group:
yourdomain/group1.

For each unique group (group2, group3, and so forth), you create the corresponding policy or rolemap pairs (G2-policy and G2-rolemap, G3-policyand G3-rolemap, and so on).

Add and remove access to an element for a user

In this scenario, we want to add/remove access to all elements protected by a policy (through all of its implementing rolemaps). To do this simply, we can use cleartool chpolicy or the CTE policy editor to grant/remove the user's permission.

Listing 67. Sample chpolicy command
cleartool chpolicy -nc -kind element -add User:mydomain/tester -permission Full POLICY0

In a dynamic view, the Tester user will immediately have access to all of the elements controlled by all of the rolemaps that are implementing the policy. In a snapshot or web view, the user can now load any of those elements.

Similarly, when the access in the policy is revoked, this user will have no access to those elements through a dynamic view. In a web or snapshot view, the elements will be unloaded during the next update.

Listing 68. Sample revocation command
cleartool chpolicy -nc -kind element -remove User:mydomain/tester POLICY0

Add a new employee to the team, with access to a project's directory

In this scenario, we would like to give a new developer who is joining an existing team full access to the source code so that she can start working immediately. In the initial state, all users or groups not explicitly mentioned in the policy or rolemap protecting an element are denied access to that element. We assume that the project directory has the following policy p1 and rolemap r1:

Policy "p1":
[element]
Role: Developer Full

This is with rolemap r1 implementing policy p1 and protecting the team project's top-level directory. We also assume that all subdirectories in the project's top-level directory are protected by r1.

To grant the new user suzie access to the project directory, we simply add her to the rolemap r1:

Listing 69. Grant a new user access to the project directory
cleartool chrolemap -role Developer -add user:DOMAIN\suzie \
  -c "Adding Suzie to the team" r1

Suzie will now have full access to the team's project directory.

Prevent users from accessing a VOB

There are two ways to accomplish this, depending on the ultimate goal. The VOB ACL section of the policy to which the VOB object belongs controls all access to the VOB. If a user is not listed in that section of the policy, either directly or through the rolemap that protects the VOB object, the user will not have access to the VOB at all. A new VOB or newly upgraded VOB uses DefaultPolicy and DefaultRolemap for this protection.

Listing 70. Remove the default ACE granting VOB read access to everyone
cleartool chpolicy -nc -kind vob -remove Everyone DefaultPolicy
cleartool chpolicy -nc -kind vob -add Role:Developer Full
cleartool lspolicy -l DefaultPolicy
…
 vob ACL:
 User:domain.com/vob_owner Full
 Role:Developer Full
…

At this point, the VOB owner has full access, as well as any user added to the Developer role in the DefaultRolemap. Any user in this role can access the VOB.

Listing 71. Sample of code showing access to VOB by authorized user
% cleartool desc vob:/var/tmp/private
versioned object base "/var/tmp/private"
 created 2012-09-06T10:09:25-04:00 by RandomUser
 protected by rolemap: "DefaultRolemap"
 …
% cd /var/tmp/private
% cat /var/tmp/private/d1/file2
Contents of file2
%

Any user not in the Developer role has no access.

Listing 72. Sample of code showing failed access to VOB by unauthorized user
% cleartool desc vob:/var/tmp/private
cleartool: Error: No permission to perform operation "read info".
cleartool: Error: ACL on "vob" kind does not grant you "read-info" permission.
cleartool: Error: VOB "/var/tmp/private" is not accessible to the current user.
cleartool: Error: Unable to determine VOB for pathname "/var/tmp/private".
Listing 73. Sample of code showing failure of dynamic view access
% cd /var/tmp/private
/var/tmp/private: Permission denied
% cat /var/tmp/private/d1/file2
cat: cannot open /var/tmp/private/d1/file2

As users are added to the Developer role in DefaultRolemap, they will be able to access the VOB.

A second protection method is to allow access to the VOB but not access to the elements in the VOB. As the VOB owner, in a newly created VOB, execute the following commands outside of a view context (because they will temporarily make the VOB inaccessible to the VOB owner).

Listing 74. Changing the policy and rolemap to allow VOB access but not element access
cleartool chpolicy -nc -kind element -remove Owner-User,Owner-Group DefaultPolicy@/
    var/tmp/private
cleartool chpolicy -nc -kind element -add Role:Developer -perm Full DefaultPolicy@/
    var/tmp/private
cleartool chrolemap -role Developer -add User:domain.com/vobowner,User:domain.com/
    user1,User:domain.com/user2 DefaultRolemap@/var/tmp/private

Now any users listed will have full access to the elements in the VOB. In this instance, the VOB owner is explicitly added back to the rolemap or policy to obtain access to the elements in the VOB.

Listing 75. User1 can access the VOB and its elements
% cleartool desc vob:/var/tmp/private
versioned object base "/var/tmp/private"
 created 2012-09-06T10:09:25-04:00 by RandomUser
 protected by rolemap: "DefaultRolemap"
 …
% cd /var/tmp/private
% cat /var/tmp/private/d1/file2
Contents of file2
%

As the code in Listing 76 shows, a user not listed can access VOB metadata, but not the elements.

Listing 76. User2 can access only metadata
% cleartool desc vob:/var/tmp/private
versioned object base "/var/tmp/private"
 created 2012-09-06T10:09:25-04:00 by RandomUser
 protected by rolemap: "DefaultRolemap"
 …
% cd /var/tmp/private
/var/tmp/private: Permission denied
% cat /var/tmp/private/d1/file2
cat: cannot open /var/tmp/private/d1/file2

Acknowledgements

Thanks to fellow IBMers Miran Badzak, Joe Zhou, HC Wu, and former IBMer Mark Zukowsky for some of the scenario examples in this article.

Resources

Learn

Get products and technologies

  • Download a free trial version of Rational software.
  • Evaluate other IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=933588
ArticleTitle=Ensure effective administration and security in Rational ClearCase 8.0.1
publish-date=06142013