chmaster


Transfers mastership of an object

Applicability

Product
Command type
MultiSite
multiutil subcommand

Platform
UNIX
Windows

Synopsis

chmaster [ –cl·an clan-name ] [ –site site-name ] –fam·ily family-name
–u·ser username [ –p·assword ] password new-master-replica
{ { entity-selector... | { –all [ –l·ong ] | –workingmaster }
[ –force obsolete-replica | –forceall ] }
}

Description

This command transfers the mastership of one or more objects from one replica to another. Only the current replica is affected immediately; other replicas are notified of the mastership transfers through the normal exchange of update packets.

Restrictions

Identities: You must have Super User privileges.

Mastership: Your current replica must master the object. Using –force or –forceall overrides this restriction, but you must not use these options except in special circumstances.

Options and Arguments

Specifying the Clan, Site, and Family

Default
Clan: First clan replicated at this site. If there is more than one clan at the site, –clan is required.
Site: Current site. If there is more than one site on this host, –site is required.
Family: No default; you must specify a family.

–cl·an clan-name
Name of the replica’s clan.

–site site-name
Name of the replica’s site.

–fam·ily family-name
User database family: Database name given to the user database when it was created.

Schema repository family: The family name is MASTR. You must specify MASTR when you use the –workingmaster option.

Specifying a User Name and Password

Default
You must specify a user name and password.

–u·ser user
Name of a user with Super User privileges.

–p·assword password
Password associated with the specified user.

Specifying the New Master Replica

Default
None.

new-master-replica
The name of the replica to which you are transferring mastership.

Specifying Objects

Default
None. You must specify a particular object (entity-selector), all objects in a replica (–all), or only the working schema repository.

entity-selector
Specifies the object whose mastership you want to change. You can change mastership of the following objects:

Object
Syntax
Record
record-type:record-id
User or group
user:username
group:group-name
Public Workspace item
"workspace:Public Queries\folder-name\query-name"
Personal Workspace item
"workspace:Personal Queries(username)\folder-name\query-name"
Stateless record whose name is not unique
record-type:record-id<keysite-name>
Workspace item whose name is not unique
"workspace:query-name<keysite-name>"
User or group whose name is not unique
user:username<keysite-name>
group:group-name<keysite-name>

For information about making names unique, see Resolving Naming Conflicts.

–a·ll [ –l·ong ]
Transfers to new-master-replica mastership of all objects located in and mastered by the replica you specify with –clan, –site, and –family. If errors occur, the command continues, but after finishing, it reports that not all mastership changes succeeded.

With –long, chmaster lists the objects whose mastership is changing.

Note: To change mastership of a working schema repository, use –workingmaster.

–workingmaster
Transfers mastership of a working schema repository to the site you specify. You can use this option only at the site of the working schema repository.

When you use this option, you must specify –family MASTR.

–f·orce obsolete-replica
Warning: Incorrect use of the –force option can lead to divergence among the replicas in a family.

With –force, chmaster transfers mastership of all objects in the replica specified with obsolete-replica. Use this form of chmaster only when replica obsolete-replica is no longer available (for example, it was deleted accidentally).

–f·orceall
Warning: Incorrect use of the –forceall option can lead to divergence among the replicas in a family.

With –forceall, chmaster transfers mastership of an object to a specified replica, even if the current replica does not master the object.

Examples

In these examples, the lines are broken for readability. You must enter each command on a single physical line.

See Also

describe, syncreplica
Managing Mastership