reqmaster

Sets access controls for mastership requests, or requests mastership of a branch or branch type

Applicability

Product Command type
VersionVault cleartool subcommand
MultiSite multitool subcommand
Platform
UNIX®
Linux
Windows®

Synopsis

  • Display or set the ACL for mastership requests:
    reqmaster
    –acl [ –edi/t | –set pname | –get ] vob-selector
  • Set access controls for the replica, branches, or branch types:
    reqmaster
    [ –c/omment comment | –cq/uery | –nc/omment ] { { –enable | –dis/able } vob-selector | { –den/y | –allow } [ –inst/ances ] branch-type-selector ... | { –den/y | –allow } branch-pname ... }
  • Request mastership of a branch or branch type:
    reqmaster
    [ –c/omment comment | –cq/uery | –nc/omment ] [ –lis/t ] { [ branch-pname ... ] [ branch-type-selector ... ] }

Description

This command has three forms: two forms to configure access controls for mastership requests and one form to request mastership of a branch or branch type from the replica that masters the object.

Setting access controls

To allow requests for mastership, the MultiSite administrator must set access controls at each replica:

  • Add developers to the replica's access control list (ACL). Use the –acl option with –edit or –set to edit the ACL.
  • Enable replica-level access. By default, replica-level access is not enabled. To enable it, use the –enable option.

Also, the type and the object must allow mastership requests. By default, type-level and object-level access are enabled. You can enable replica-level access, but deny requests for mastership of specific branches or branch types, or all branches of a specific type. Even if replica-level access is enabled, the reqmaster command fails if requests are denied at the type level or object level. Use the –deny option to deny requests at the type and object level.

Note: Mastership request settings are not replicated. The describe command and the Mastership tab in the Properties Browser on Windows® display the current replica's settings.

Requesting mastership of a branch or branch type

This form of the reqmaster command contacts a sibling replica and requests that the replica transfer mastership to the current replica. You can also use reqmaster to display information about whether a mastership request will succeed.

If you specify multiple branches or branch types and the request fails for one or more items, reqmaster prints error messages for the failures and continues processing the other items.

Using a single port for mastership requests

To account for firewalls, you may specify a single port that is to be used for mastership requests at the host that holds mastership of the object. To do so, edit the file albd_rt_params.conf, which is stored in the following directories:
  • /var/adm/hcl/versionvault/config/ (UNIX and Linux)
  • Program Files\HCL\CCM\VersionVault\config\services\ (Windows)

Troubleshooting

If the reqmaster command fails, the error message indicates whether the failure occurred at the current replica or the sibling replica.

If the reqmaster command fails with the message can't get handle, reenter the command. If it continues to fail, ask the sibling replica's administrator to check the status of the VOB server.

When you request mastership, the reqmaster command may complete successfully, but the mastership is not transferred to your current replica. In this case, verify that the synchronization packet was sent from the sibling replica and that your current replica imported it successfully.

Errors that occur during the mastership request process, including errors occurring during the synchronization export, are written to the msadm log file. To view this log, use the cleartool getlog command or the VersionVault Administration Console (Windows®).

For more information about error messages from the reqmaster command, see the Help.

Restrictions

Setting access controls

Identities: To set the ACL, you must have write permission on the ACL or have one of the following identities:

  • VOB owner
  • root (Linux® and the UNIX® system)
  • Member of the VersionVault administrators group (Windows®)

To enable mastership requests at the replica level, you must have one of the following identities:

  • VOB owner
  • root (Linux® and the UNIX® system)
  • Member of the VersionVault administrators group (Windows®)

Locks: No locks apply.

Mastership: For you to allow or deny mastership requests for a branch or branch type, your current replica must master the object.

Other: You do not have to be logged on to a VOB server host to edit the mastership request ACL for a replica on that host. However, if you are not already on the ACL, both of the following conditions must be true in order for you to edit the ACL:

  • You must be the VOB owner or privileged user.
  • You must be logged on to a host in the same domain as the VOB server host.

Requesting mastership of a branch

Identities: You must be on the replica's ACL.

Locks: An error occurs if one or more of these objects are locked (even if you are on the –nusers list): branch, branch type, VOB.

Mastership: Your current replica must not master the branch.

Other: An error occurs in any of the following cases:

  • Mastership requests are denied at any of the following levels: replica, type object, object.
  • There are checkouts on the branch (except for unreserved, nonmastered checkouts).
  • You specify a branch associated with a stream.
  • Your host is running a later major version of HCL VersionVault than the master replica's host.

Requesting mastership of a branch type

Identities: You must be on the replica's ACL.

Locks: An error occurs if one or more of these objects are locked (even if you are on the –nusers list): branch type, VOB, branch instances that have default mastership.

Mastership: Your current replica must not master the branch type.

Other: An error occurs in any of the following cases:

  • Mastership requests are denied at any of the following levels: replica, type object, any branch type instances with default mastership.
  • There are checkouts on any branch type instances with default mastership (except for unreserved, nonmastered checkouts).
  • You specify a branch type associated with a stream.
  • Your host is running a later major version of HCL VersionVault than the master replica's host.
Exceptions to the restrictions: If all of the following conditions are true,
  • The replica feature level is 9 or greater
  • Request for mastership is enabled
  • Instances of the branch type are explicitly mastered
then the transfer of branch type mastership succeeds if any of the following conditions is true:
  • An instance of the branch type is locked
  • An instance has a checkout
  • All instances are blocked.

Options and arguments

Event records and comments

Default
Creates one or more event records, with commenting controlled by the standard VersionVault user profile (default: –nc). See Customizing comment handling in the multitool reference page. To edit a comment, use chevent.
–c/omment comment | –cq/uery | –nc/omment
Overrides the default with the specified comment option.

Displaying or setting access controls

Default
None. You must specify access controls. Specifying –acl with no other option displays the ACL for the current replica in the VOB family specified by vob-selector.
–acl [ –edi/t | –set pname | –get ] vob-selector
By default or with –get, displays the ACL for the current replica in the VOB family specified by vob-selector. With –edit, opens the ACL for the current replica in the editor specified by (in order) the WINEDITOR (Linux® and the UNIX® system), VISUAL, or EDITOR environment variable. With –set, uses the contents of pname to set the ACL for the current replica.

Specify vob-selector in the form vob:pname-in-vob

pname-in-vob
Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted)
–enable vob-selector
Allows mastership requests to be made to the current replica in the VOB family specified by vob-selector.
–dis/able vob-selector
Denies all mastership requests made to the current replica in the VOB family specified by vob-selector.
{ –deny | –allow } [ –inst/ances] branch-type-selector ...
Denies or allows requests for mastership of the specified branch type. With –instances, denies or allows requests for mastership of all branches of the specified type. Specify branch-type-selector in the form brtype:type-name[@vob-selector]
type-name
Name of the branch type
vob-selector
VOB specifier; can be omitted if the current working directory is within the VOB.

Specify vob-selector in the form [vob:]pname-in-vob

pname-in-vob
Pathname of the VOB tag (whether or not the VOB is mounted) or of any file system object within the VOB (if the VOB is mounted)
{ –deny | –allow } branch-pname ...
Denies or allows requests for mastership of the specified branch object. Specify branch-pname in the form file-pname@@branch. For example: 
cmdsyn.c@@/main/v3.8
header.h@@\main\v1\bugfix

Requesting mastership

Default
Sends a request for mastership to the master replica of the object.
–lis/t
Displays information about whether a request would succeed, but does not send a request for mastership.
branch-pname
Branch whose mastership you are requesting. For example: 
cmdsyn.c@@/main/v3.8
header.h@@\main\v1\bugfix
branch-type-selector
Branch type whose mastership you are requesting. For example:


brtype:main@/vobs/doc brtype:v2.0_integration@vob:\tests

Examples

  • Display the ACL for the current replica in the VOB family /vobs/dev, and then change it to give full access to ccadmin and permission to request mastership to gail and paul.



    multitool reqmaster –acl –get vob:/vobs/dev


    # Replica boston_hub@/vobs/dev
    # Request for Mastership ACL:
    Everyone: Read


    cat > /tmp/boston_hub_aclfile


    # Replica boston_hub@/vobs/dev
    # Request for Mastership ACL:
    User:purpledoc.com/ccadmin Full
    User:purpledoc/ccadmin Full
    User:purpledoc.com/gail Change
    User:purpledoc/gail Change
    User:purpledoc.com/paul Change
    User:purpledoc/paul Change



    multitool reqmaster –acl –set /tmp/boston_hub_aclfile vob:/vobs/dev

    multitool reqmaster –acl –get vob:/vobs/dev
    # Replica boston_hub@/vobs/dev
    # Request for Mastership ACL:
    User:purpledoc.com/ccadmin Full
    User:purpledoc/ccadmin Full
    User:purpledoc.com/gail Change
    User:purpledoc/gail Change
    User:purpledoc.com/paul Change
    User:purpledoc/paul Change

  • Allow requests for mastership for all branches and branch types mastered by the current replica in VOB family \tests, except for the branch type v2.0_integration and all branches of that type.

    multitool reqmaster –enable vob:\tests
    Requests for mastership enabled in the replica object for "vob:\tests"



    multitool reqmaster –deny –instances brtype:v2.0_integration@vob:
    \tests
    Requests for mastership denied for all instances of
    "brtype:v2.0_integration@vob:\tests"
    multitool reqmaster –deny brtype:v2.0_integration@vob:\tests
    Requests for mastership denied for "brtype:v2.0_integration@vob:\tests"

  • Allow requests for mastership for all branches and branch types mastered by the current replica in VOB family \dev, except for the branch cmdsyn.m@@\main\v1.0_bugfix.

    multitool reqmaster –enable vob:\dev
    Requests for mastership enabled in the replica object for "vob:\dev"


    multitool reqmaster –deny \dev\cmdsyn.m@@\main\v1.0_bugfix
    Requests for mastership denied for branch "\dev\cmdsyn.m@@\main
    \v1.0_bugfix"

  • Deny requests for mastership for all branches and branch types mastered by the current replica.

    multitool reqmaster –disable vob:/vobs/dev
    Requests for mastership disabled in the replica object for
    "vob:/vobs/dev"

  • Deny requests for mastership of the branch type v2.0_integration.



    multitool reqmaster –deny brtype:v2.0_integration@vob:\tests


    Requests for mastership denied for "brtype:v2.0_integration@vob:\tests"

  • Display mastership information about the branches include.h@@\main\integ and acc.c@@\main.



    multitool reqmaster –list include.h@@\main\integ acc.c@@\main


    multitool: Error:  acc.c@@\main
    The following would block the "reqmaster" operation at replica "sydney".
    At least one checkout prevents the request.

  • Request mastership of the branch cmdsyn.m@@/main/v2.6_dev.



    multitool reqmaster cmdsyn.m@@/main/v2.6_dev


    cmdsyn.m@@/main/v2.6_dev: Change of mastership at sibling replica
    "boston_hub" was successful.
    Mastership is in transit to the new master replica.

  • Request mastership of the branch type v2.0_integration.



    multitool reqmaster brtype:v2.0_integration@vob:\tests


    brtype:v2.0_integration@vob:\tests: Change of mastership at sibling
    replica "sydney" was successful.
    Mastership is in transit to the new master replica.