8.2.3. cctrl Commands

Table 8.11. cctrl Commands

OptionDescription
adminChange to admin mode
cdChange to a specific site within a multisite service
clusterIssue a command across the entire cluster
cluster validateValidate the cluster quorum configuration
create compositeCreate a composite dataservice
datasourceIssue a command on a single datasource
expertChange to expert mode
failoverPerform a failover operation from a master to a slave
helpDisplay the help information
lsShow cluster status
membersList the managers of the dataservice
physicalEnter physical mode
pingTest host availability
quit, exitExit cctrl
recover master usingRecover the master within a datasource using the specified master
replicatorIssue a command on a specific replicator
routerIssue a command on a specific router (connector)
serviceRun a service script
setSet management options
set masterSet the master within a datasource
switchPromote a slave to a master

8.2.3.1. cctrl admin Command

The admin command enables admin mode commands and displays. Admin mode is a specialized mode used to examine and repair cluster metadata. It is not recommended for normal use.

8.2.3.2. cctrl cd Command

The cd command changes the data service being administered. Subsequent commands will only affect the given data service name.

Using cd .. allows to go back to the root element. The given data service name can be either composite or physical Note that this command can only be used when cctrl is run with the '-multi' flag

8.2.3.3. cctrl cluster Command

The cluster command operates at the level of the full cluster.

8.2.3.3.1. cctrl cluster check Command

The cluster check command issues an MD5 consistency check on one or more tables in a database on the master data source. The consistency checks then replicate to each slave, whereupon the slave replicator repeats the check.

If the check fails, slaves may go offline or print a log warning depending on how the replicators are configured. The default is to go offline. You can return a replicator to the online state after a failed check by issuing a replicator online command.

The table name can also be a wildcard (*) in which case all tables will be checked. Users may optionally specify a range of rows to check using the -limit option, which takes a starting row option followed by a number of rows to check. Rows are selected in primary key order.

Usage:

The following example checks all tables in database accounting.

[LOGICAL] /alpha > cluster check accounting.*

The following command checks only the first 10 rows in a single table.

[LOGICAL] /alpha > cluster check accounting.invoices -limit 1,10

Warning

Consistency checks can be very lengthy operations for large tables and will lock them while they run. On the master this can block applications. On slaves it blocks replication.

8.2.3.3.2. cctrl cluster flush Command

The cluster flush command sends a heartbeat event through the local cluster and returns a flush sequence number that is guaranteed to be equal to or greater than the sequence number of the flush event. Slaves that reach the flush sequence number are guaranteed to have applied the flush event.

This command is commonly used for operations like switch that need to synchronize the position of one or more masters or slaves.

8.2.3.3.3. cctrl cluster heartbeat Command

The cluster heartbeat command sends a heartbeat event through the local cluster to demonstrate that all replicators are working. You should see the sequence numbers on all data sources advance by at least 1 if it is successful.

8.2.3.3.4. cctrl cluster offline Command

The cluster offline command brings all data services that are not offline into the offline state. It has no effect on services that are already offline.

8.2.3.3.5. cctrl cluster online Command

The cluster online command brings all data services that are not online into the online state. It has no effect on services that are already online.

8.2.3.3.6. cctrl cluster validate Command

The cluster validate validates the configuration of the cluster with respect to the quorum used for decision making. The number of active managers, active witnesses and passive witnesses within the cluster is validated to ensure that there are enough active hosts to make a decision in the event of a failover or other failure event.

When executed, the validation routine checks all the available hosts, including witness hosts, and determines whether there are enough hosts, and whether their membership of the cluster is valid. In the event of deficiency, corrective action will be recommended.

By default, the command checks all hosts within the configured cluster:

[LOGICAL] /alpha > cluster validate
HOST host1/192.168.2.20: ALIVE
HOST host2/192.168.2.21: ALIVE
HOST host3/192.168.2.22: ALIVE
CHECKING FOR QUORUM: MUST BE AT LEAST 2 MEMBERS, OR 1 MEMBERS PLUS ALL WITNESSES
QUORUM SET MEMBERS ARE: host2, host1, host3
SIMPLE MAJORITY SIZE: 2
VALIDATED MEMBERS ARE: host2, host1, host3
REACHABLE MEMBERS ARE: host2, host1, host3
WITNESS HOSTS ARE: 
REACHABLE WITNESSES ARE: 
MEMBERSHIP IS VALID
GC VIEW OF CURRENT MEMBERS IS: host1, host2, host3
VALIDATED CURRENT MEMBERS ARE: host2, host1, host3
CONCLUSION: I AM IN A PRIMARY PARTITION OF 3 MEMBERS OUT OF THE REQUIRED MAJORITY OF 2
VALIDATION STATUS=VALID CLUSTER
ACTION=NONE

Additionally, a list of hosts to exclude from the check can be provided to verify the cluster capability when certain hosts have already failed or been shunned from the dataservice during maintenance.

To exclude hosts, add excluding and a comma-separated list of hosts to the command. For example:

[LOGICAL] /alpha > cluster validate excluding host3,host2
EXCLUDED host3 FROM VIEW
EXCLUDED host2 FROM VIEW
HOST host1/192.168.2.20: ALIVE
CHECKING FOR QUORUM: MUST BE AT LEAST 2 MEMBERS, OR 1 MEMBERS PLUS ALL WITNESSES
QUORUM SET MEMBERS ARE: host2, host1, host3
SIMPLE MAJORITY SIZE: 2
VALIDATED MEMBERS ARE: host1
REACHABLE MEMBERS ARE: host1
WITNESS HOSTS ARE: 
REACHABLE WITNESSES ARE: 
MEMBERSHIP IS VALID
GC VIEW OF CURRENT MEMBERS IS: host1
VALIDATED CURRENT MEMBERS ARE: host1
CONCLUSION: I AM IN A NON-PRIMARY PARTITION OF 1 MEMBERS OUT OF A REQUIRED MAJORITY SIZE OF 2
AND THERE ARE 0 REACHABLE WITNESSES OUT OF 0
VALIDATION STATUS=NON-PRIMARY PARTITION
ACTION=RESTART SAFE

Cluster validation can be used to provide validation only. To improve the support:

8.2.3.4. cctrl create composite Command

The create composite command creates a new composite data source or data service with the given name. Composite data services can only be create in the root directory '/' while composite data sources need to be created from a composite data service location. Composite data source names should be the same as the physical data services Composite data service name should be named after its composite data sources

Usage:

The following example creates a composite data service named 'sj_nyc'

create composite dataservice sj_nyc

The following example changes to the composite data service sj_nyc, then creates a composite data source named 'sj' in this composite data service

cd sj_nyc
  create composite datasource sj

8.2.3.5. cctrl datasource Command

The datasource command affects a single data source.

datasource
fail
host
offline
online
recover
restore
shun
welcome

Table 8.12. cctrldatasource Commands

OptionDescription
failFail a datasource
hostHostname of the datasource
offlinePut a datasource into the offline state
onlinePut a datasource into the online state
recoverRecover a datasource into operation state as slave
restoreRestore a datasource from a previous backup
shunShun a datasource
welcomeWelcome a shunned datasource back to the cluster

8.2.3.5.1. cctrl datasource backup Command

The datasource backup command invokes a backup on the data source on the named host using the default backup agent and storage agent. Backups taken in this way can be reloaded using the datasource restore command. The following command options are supported:

  • backupAgent — The name of a backup agent.

  • storageAgent — The name of a storage agent.

  • timeout — Number of seconds to wait before the backup command times out.

On success the backup URL will be written to the console.

Usage:

The following example performs a backup on host saturn using the default backup agent.

cctrl> datasource saturn backup 

The following example performs a backup on host mercury using the xtrabackup agent, which is named explicitly.

cctrl> datasource mercury backup xtrabackup
8.2.3.5.2. cctrl datasource backup Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.3. cctrl datasource host Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.4. cctrl datasource offline Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.5. cctrl datasource online Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.6. cctrl datasource recover Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.7. cctrl datasource restore Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.8. cctrl datasource shun Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.5.9. cctrl datasource welcome Command

When a datasource has been shunned, the datasource can be welcomed back to the dataservice by using the welcome command. The welcome command attempts to enable the datasource in the ONLINE state using the current roles and configuration. If the datasource was operating as a slave before it was shunned, the welcome command will enable the datasource as a slave.

For example, the host host3 is a slave and currently online:

+----------------------------------------------------------------------------+
|host3(slave:ONLINE, progress=157454, latency=1.000)                      |
|STATUS [OK] [2013/05/14 05:12:52 PM BST]                                    |
+----------------------------------------------------------------------------+
|  MANAGER(state=ONLINE)                                                     |
|  REPLICATOR(role=slave, master=host2, state=ONLINE)                     |
|  DATASERVER(state=ONLINE)                                                  |
|  CONNECTIONS(created=0, active=0)                                          |
+----------------------------------------------------------------------------+
[LOGICAL:EXPERT] /alpha > datasource host3 shun
DataSource 'host3' set to SHUNNED

To switch the datasource back to the online state, the welcome is used:

[LOGICAL:EXPERT] /alpha > datasource host3 welcome
DataSource 'host3' is now OFFLINE

The welcome command puts the datasource into the OFFLINE state. If the dataservice policy mode is AUTOMATIC, the node will be placed into ONLINE mode due to automatic recovery. When in MAINTENANCE or MANUAL mode, the node must be manually set online.

The welcome command may not always work if there has been a failure or topology change between the moment it was shunned and welcomed back. Using the recover command may be a better alternative to using welcome when bringing a datasource back online. The recover commands ensures that the replicator, connector and operation of the datasource are correct within the current cluster configuration. See Section 8.2.3.14, “cctrl recover Command”.

8.2.3.6. cctrl expert Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.7. cctrl failover Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.8. cctrl help Command

The help command provides help text from within the cctrl operation.

With no other arguments, help provides a list of the available commands:

[LOGICAL] /alpha &gt; <userinput>help</userinput>
--------
Overview
--------
Description: Overview of Tungsten cctrl Commands

Commands
--------
admin                          - Enter admin mode
cd <name>                      - Change to the specified SOR cluster element
cluster <command>              - Issue a command on the entire cluster
create composite <type> <name> - Create SOR cluster components
datasource <host> <cmd>        - Issue a command on a datasource
expert                         - Enter expert mode
failover                       - Failover from failed master to slave
help                           - Show help
ls [options]                   - Show generic cluster status
members                        - List all of the managers in the cluster
ping                           - Test host availability
physical                       - Enter physical mode
quit or exit                   - Leave cctrl
replicator <host> <cmd>        - Issue a command on a replicator
service               	       - Run a service script
set                            - Set management options
switch                         - Promote a slave to master

To get more information about particular commands type help followed by a 
command.  Examples: 'help datasource' or 'help create composite'.

To get specific information about an individual command or operation, provide the command name to the help command. For example, to get information about the ping command, type help ping at the cctrl prompt.

8.2.3.9. cctrl ls Command

The ls command displays the current structure and status of the cluster.

ls [-l] [host] [[resources] | [services] | [sessions]]

The ls command operates in a number of different modes, according to the options provided on the command-line, as follows:

  • No options

    Generates a list of the current routers, datasources, and the their current status and services.

  • -l

    Outputs extended information about the current status and configuration. The -l option can be used in both the standard (no option) and host specific output formats to provide more detailed information.

  • host

    Content Being Written

    This section of the documentation is currently being produced and may be incomplete and/or subject to change.

  • resources

    Content Being Written

    This section of the documentation is currently being produced and may be incomplete and/or subject to change.

  • services

    Content Being Written

    This section of the documentation is currently being produced and may be incomplete and/or subject to change.

  • sessions

    Content Being Written

    This section of the documentation is currently being produced and may be incomplete and/or subject to change.

Without any further options, the

[LOGICAL] /alpha &gt; <userinput>ls</userinput>

COORDINATOR[host1:AUTOMATIC:ONLINE]

ROUTERS:
+----------------------------------------------------------------------------+
|connector@host1[1179](ONLINE, created=0, active=0)                          |
|connector@host2[1532](ONLINE, created=0, active=0)                          |
|connector@host3[17665](ONLINE, created=0, active=0)                         |
+----------------------------------------------------------------------------+

DATASOURCES:
+----------------------------------------------------------------------------+
|host1(master:ONLINE, progress=60, THL latency=0.498)                        |
|STATUS [OK] [2013/03/22 02:25:00 PM GMT]                                    |
+----------------------------------------------------------------------------+
|  MANAGER(state=ONLINE)                                                     |
|  REPLICATOR(role=master, state=ONLINE)                                     |
|  DATASERVER(state=ONLINE)                                                  |
|  CONNECTIONS(created=0, active=0)                                          |
+----------------------------------------------------------------------------+

+----------------------------------------------------------------------------+
|host2(slave:ONLINE, progress=31, latency=0.000)                             |
|STATUS [OK] [2013/03/22 02:25:00 PM GMT]                                    |
+----------------------------------------------------------------------------+
|  MANAGER(state=ONLINE)                                                     |
|  REPLICATOR(role=slave, master=host1, state=ONLINE)                        |
|  DATASERVER(state=ONLINE)                                                  |
|  CONNECTIONS(created=0, active=0)                                          |
+----------------------------------------------------------------------------+

+----------------------------------------------------------------------------+
|host3(slave:ONLINE, progress=35, latency=9.455)                             |
|STATUS [OK] [2013/03/21 06:47:53 PM GMT]                                    |
+----------------------------------------------------------------------------+
|  MANAGER(state=ONLINE)                                                     |
|  REPLICATOR(role=slave, master=host1, state=ONLINE)                        |
|  DATASERVER(state=ONLINE)                                                  |
|  CONNECTIONS(created=0, active=0)                                          |
+----------------------------------------------------------------------------+
8.2.3.9.1. cctrl ls host

You can also specify an individual component within the cluster on which to obtain information. For example, to get the information only for a single host:

[LOGICAL] /alpha &gt; <userinput>ls host2</userinput>

COORDINATOR[host1:AUTOMATIC:ONLINE]

ROUTERS:
+----------------------------------------------------------------------------+
|connector@host1[1179](ONLINE, created=0, active=0)                          |
|connector@host2[1532](ONLINE, created=0, active=0)                          |
|connector@host3[17665](ONLINE, created=0, active=0)                         |
+----------------------------------------------------------------------------+

DATASOURCES:
+----------------------------------------------------------------------------+
|host2(slave:ONLINE, progress=114, latency=92.487)                           |
|STATUS [OK] [2013/03/22 02:25:00 PM GMT]                                    |
+----------------------------------------------------------------------------+
|  MANAGER(state=ONLINE)                                                     |
|  REPLICATOR(role=slave, master=host1, state=ONLINE)                        |
|  DATASERVER(state=ONLINE)                                                  |
|  CONNECTIONS(created=0, active=0)                                          |
+----------------------------------------------------------------------------+
8.2.3.9.2. cctrl ls -l (Extended Information)

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.9.3. cctrl ls resources

The resources option generates a list of the configured resources and their current status.

8.2.3.9.4. cctrl ls services

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.9.5. cctrl ls sessions

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.10. cctrl members Command

The members command outputs a list of the currently identified managers within the dataservice.

members

For example:

[LOGICAL] /alpha &gt; <userinput>members</userinput>
alpha/host1(ONLINE)/192.168.1.60:7800
alpha/host2(ONLINE)/192.168.1.61:7800
alpha/host3(ONLINE)/192.168.1.62:7800

The command outputs each identified manager service within the current dataservice.

The format of the output information is:

DATASERVICE/HOST(STATUS)/IPADDR:PORT

Where:

  • DATASERVICE

    The name of the dataservice.

  • HOST

    The name of the host on which the manager resides.

  • STATUS

    The current status of the manager.

  • IPADDR

    The IP address of the manager.

  • PORT

    The primary TCP/IP port used for contacting the manager service.

The members service can be used as an indicator of the overall status of the dataservice. The information shown for each manager should within a single dataservice should be identical. If different information is shown, or an incomplete number of managers compared to the number of configured managers is provided, then it may indicate a communication or partition problem within the dataservice.

8.2.3.11. cctrl physical Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.12. cctrl ping Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.13. cctrl quit Command

Exits cctrl and returns the user to the shell. For example:

8.2.3.14. cctrl recover Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.15. cctrl recover master using Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.16. cctrl recover relay using Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.17. cctrl recover using Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.18. cctrl replicator Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.19. cctrl rm Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.20. cctrl router Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.21. cctrl service Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.22. cctrl set Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.23. cctrl set force Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.24. cctrl set master Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.

8.2.3.25. cctrl switch Command

Content Being Written

This section of the documentation is currently being produced and may be incomplete and/or subject to change.