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] |
–working/master } [ –f/orce 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 dbset connection registered on this host, –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 "Troubleshooting MultiSite operations - Resolving naming conflicts" in this guide.

–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.

–working/master

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

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

–f/orce obsolete-replica

Important: 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).

–forceall

Important: 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.

Transfer mastership of the user admin from the boston_hub replica to sanfran_hub.
multiutil chmaster -clan telecomm -site boston_hub -family DEV -user susan -p passwd sanfran_hub user:admin
Multiutil: The mastership of record 'admin' of type 'user' has been changed from 'BOSTON_HUB' to 'SANFRAN_HUB'. Multiutil: The mastership of some users or groups has been transferred from this site. The local user administrator must update user databases at the new mastering site 'sanfran_hub' before these changes will be visible to any user database.
At the tokyo replica, which contains the working schema repository, transfer mastership of all schemas and working schema repository tasks to the sydney replica.
multiutil chmaster -clan testclan -site tokyo -family MASTR -user masako -p passwd sydney -workingmaster
Multiutil: The working master has been changed from 'TOKYO' to 'SYDNEY'.
Transfer mastership of all objects in the DEV database, mastered by the sanfran_hub replica, to the boston_hub replica.
multiutil chmaster -clan telecomm -site sanfran_hub -family DEV -user jcole -p passwd boston_hub -all
Multiutil: Total number of objects changed: 5.
Similar to the previous example, but use the –long option.
multiutil chmaster -clan telecomm -site sanfran_hub -family DEV -user jcole -p passwd boston_hub -all -long
Multiutil: The mastership(s) of the following object(s) in database 'DEV' was(were) changed from 'SANFRAN_HUB' to 'BOSTON_HUB'.

Multiutil: Type: customer, display Name: John Smith. Multiutil: Type: customer, display Name: Ethan Hunt. Multiutil: Type: customer, display Name: Jane Smith. Multiutil: Type: customer, display Name: Anne Johnson. Multiutil: Type: customer, display Name: Joe Lee.
At the boston_hub replica, transfer mastership of all items mastered by the bangalore replica to the boston_hub replica. Assume that bangalore is no longer available.
multiutil chmaster -clan telecomm -site boston_hub -family DOC -user susan -password passwd boston_hub -all -force bangalore

Change mastership of users and groups from the bangalore schema repository to boston_hub.

multiutil chmaster -clan telecomm -site boston_hub -family MASTR -user susan -password passwd boston_hub -all -force bangalore

Change mastership of the working schema repository from bangalore to boston_hub:

multiutil chmaster -clan telecomm -site boston_hub -family MASTR -user susan -password passwd boston-hub -workingmaster -force bangalore
At boston_hub, use –forceall to change mastership of user admin from sanfran_hub to tokyo.
multiutil chmaster -clan telecomm -site boston_hub -family DEV -user susan -p passwd tokyo user:admin –forceall
Multiutil: The mastership of record 'admin' of type 'user' has been changed from 'SANFRAN_HUB' to 'TOKYO'.