protect

Changes permissions or ownership of a VOB object

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

protect [ -cho·wn login-name ] [ -chg·rp group-name ] [ -chm·od permissions ]

[-c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment ]
{ [ -fil·e | -d·irectory ] [ -r·ecurse ] [ -pna·me ] pname ...
| object-selector ...
}

DESCRIPTION

The protect command sets the owner, group, or permissions for one or more elements, shared derived objects, or named VOB objects. This information is maintained in the VOB database.

NOTE: This command does not apply to files loaded in a snapshot view.

The main use of protect is to control access by standard programs to an element or object's data. For example, you may make some elements readable by anyone, and make others readable by only their group members.

Modifying the permissions of an element changes the permissions of all of its source containers and (if applicable) cleartext containers. That is, the change affects all versions, not just the version selected by the current view. There is no way to change the permissions of an individual version.

Some forms of protect affect ClearCase access. For example, a checkout or checkin is permitted only if the user is the element's owner, or is a member of the element's group.

View-Private Objects

This command does not affect view-private objects. For this reason, entering a protect command sometimes seems to have no effect:

• Changing an element's permissions has no effect on its checked-out versions. After you check in the element, your view selects the checked-in version, thus making the updated permissions appear.
• Changing a DO's permission has no effect on the way the DO appears in the view where it was originally created, or in the dynamic views where it has been winked in. To have your dynamic view use a shared DO with updated permissions:
  1. Use protect to change the permissions on the DO in the VOB database.
  2. Use rm to remove the DO from your view.
  3. Use clearmake or the winkin command to wink in the DO, with its new permissions.

You can change the permissions on any view-private object (including a checked-out version), with the standard Windows commands. In particular, you can switch a view-private file between read-write and read-only states with the attrib command's -R and +R options.

A winked-in DO is not really a view-private object, but it behaves like one (so that users in different views can build software independently). Moreover, changing the permissions of a winked-in DO actually converts it to a view-private file in your view. See Working with Derived Objects and Configuration Records in Building Software with ClearCase.

Owner Setting

The initial owner of an element is the user who creates it with mkelem or mkdir. The initial owner of a named VOB object is the user who creates it. The initial owner of a derived object is the user who builds it with clearmake. When the derived object is winked in and becomes shared, its data container is promoted to a VOB storage pool. This process preserves the derived object's ownership, no matter who performs the build that causes the winkin.

See the permissions reference page for a list of operations that can be performed by an element's owner.

Group Setting

The initial group of an element or named VOB object is the primary group of its creator. The new group specified in a protect -chgrp command must be one of the groups on the VOB's group list.

See the permissions reference page for a list of operations that can be performed by members of an element's or derived object's group.

Read and Execute Permissions

The read and execute permissions of an element or shared derived object control access to its data in the standard manner. The permissions are also applied to all its associated data containers.

NOTE: protect sometimes adds group-read permission to your specification. This ensures that the owner of an element always retains read permission to its data containers.

Write Permission

The meaning of the write permission varies with the kind of object:

• For a file element, write permission settings are ignored. To obtain write permission to a file element, you must check it out.
• For a directory element, write permission allows view-private files to be created within it. ClearCase permissions control changes to the directory element itself. (See the permissions reference page.)
• For a shared derived object, write permission allows it to be overwritten with a new derived object during a target rebuild. (The shared derived object is not actually affected; rather, the view sees the new, unshared derived object in its place.)

Protection of Global Types and Local Copies

Changing the protection of a global type or a local copy of a global type changes the protection of the global type and all its local copies. You must have permission to change the protection of the global type.

If the protection cannot be changed on one or more of the local copies, the operation fails and the global type's protection is not changed. You must fix the problem and run the protect command again.

For more information, see Administering ClearCase.

PERMISSIONS AND LOCKS

Permissions Checking: For each object processed, you must be one of the following: owner, VOB owner, member of the ClearCase group. See the permissions reference page.

NOTE: With protect -chgrp, you must be a member of the new group, and it must also be in the VOB's group list.

Locks: An error occurs if any of the following objects are locked: VOB, element type, element, pool (non-directory elements only). For named objects, an error occurs if the VOB, object, or object's type is locked.

OPTIONS AND ARGUMENTS

SPECIFYING PERMISSION CHANGES.  Default: None.

-cho·wn login-name

New owner for the elements or VOB objects. The login-name must specify a domainwide user account.

-chg·rp group

New group for the elements or VOB objects. The group must be registered in the domainwide account database.

-chm·od permissions

New permissions-owner, group, other (world)-for the elements or VOB objects.

Specify permissions in one of more of the following forms:

identity+permission
identity-permission
identity=permission

where identity is any combination of

and permission is any combination of

To combine the forms, separate them with a comma (no white space). For example, to specify read and write permissions for an element's owner and no access by group or other:

cmd-context protect -chmod u=rw,go-rwx test.txt

EVENT RECORDS AND COMMENTS. Default: Creates one or more event records, with commenting controlled by your .clearcase_profile file (default: -nc). See CUSTOMIZING COMMENT HANDLING in the comments reference page. Comments can be edited with chevent.

-c·omment comment | -cfi·le comment-file-pname |-cq·uery | -cqe·ach | -nc·omment

Overrides the default with the option you specify. See the comments reference page.

SPECIFYING THE OBJECTS.  Default: None.

-fil·e

Restricts the command to changing file elements only. This option is especially useful in combination with the -recurse option.

-d·irectory

Restricts the command to changing directory elements only. This option is especially useful in combination with the -recurse option.

[ -pna·me ] pname ...

One or more pathnames, each of which specifies an element or shared derived object. If pname has the form of an object selector, you must use the -pname option to indicate that pname is a pathname. An extended pathname to a version or branch is valid, but keep in mind that protect affects the entire element. Shared derived objects can be referenced by DO-ID.

If you specify multiple pname arguments, but you do not have permission to change the permissions on a particular object, protect quits as soon as it encounters this error.

object-selector ...

One or more named VOB objects. Specify object-selector in one of the following forms:

PROCESSING OF DIRECTORY ELEMENTS.  Default: Any pname argument that specifies a directory causes the directory element itself to be changed.

-r·ecurse

Changes the entire tree of elements including and below any pname argument specifying a directory element. (Use -file or -directory to restrict the changes to one kind of element.)

EXAMPLES

Examples including wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

• Add read permission to the file element hello.c, for all users.

cmd-context protect -chmod +r hello.c
Changed protection on "hello.c".

• Change the group-ID for all elements in the src directory to user.

cmd-context protect -recurse -chgrp user src
Changed protection on "src".
Changed protection on "src\cm_fill.c".
Changed protection on "src\convolution.c".
Changed protection on "src\hello.c".
Changed protection on "src\msg.c".
Changed protection on "src\util.c".

• Change the owner of the branch type qa_test to tester.

cmd-context protect -chown tester brtype:qa_test
Changed protection on "qa_test".

• Allow users in the same group to read/write/execute the shared derived object hello, but disable all access by the world. Use an absolute permission specification.

cmd-context protect -chmod 770 hello
Changed protection on "hello".

SEE ALSO

protectvob