> CommCell Console > Tools & Utilities > Developer Tools > Command Line > Command Line Interface > Agents

Command Line Interface - Configuration

Log On to the CommServe

To run command line operations, you must first login to the CommServe.

From Command prompt, navigate to <Software_Installation_Directory>/Base and run the following command:

 
qlogin -cs $[commserve name] -u $[user name]

For example, to log on to CommServe 'server1' with username 'user1':

qlogin -cs $[server1] -u $[user1]

Instance Configuration

Creating an Instance

  1. Download the create_instance_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

On a UNIX client:
 
qoperation execute -af create_instance_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] -userGroupName $[xxxxx] -BinaryDirectory $[xxxxx] -LogDataDirectory $[xxxxx] -configFile $[xxxxx] -port $[xxxxx] -SAUser/userName $[xxxxx] -SAUser/password $[xxxxx] -unixUser/userName $[xxxxx] -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[xxxxx] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[xxxxx]

Example:

 
qoperation execute -af create_instance_template.xml -appName '$[MySQL]' -clientName $[client1] -instanceName $[instance1] -BinaryDirectory $[/usr/bin] -LogDataDirectory $[var/log/mysql] -configFile $[etc/mysql/my.cnf] -port /var/run/mysqld/mysqld.sock -SAUser/userName '$[root]' -SAUser/password '$[mysql]' -unixUser/userName '$[root]' -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[SP1] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[SP1]

Example to create an instance with XtraBackup option enabled:

 
qoperation execute -af create_instance_template.xml -appName '$[MySQL]' -clientName $[client1] -instanceName $[instance1] -BinaryDirectory $[/usr/bin] -LogDataDirectory $[var/log/mysql] -configFile $[etc/mysql/my.cnf] -port $[/var/run/mysqld/mysqld.sock] -SAUser/userName '$[root]' -SAUser/password '$[mysql]' -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[SP1] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[SP1] -xtraBackupSettings/enableXtraBackup '$[true]' -xtraBackupSettings/xtraBackupBinPath '$[/usr/bin]'
On a Windows client:
 
qoperation execute -af create_instance_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] -userGroupName $[xxxxx] -BinaryDirectory $[xxxxx] -LogDataDirectory $[xxxxx] -configFile $[xxxxx] -port $[xxxxx] -SAUser/userName $[xxxxx] -SAUser/password $[xxxxx] -NTUser/userName $[xxxxx] -NTUser/password $[xxxxx] -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[xxxxx] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[xxxxx]

Example:

 
qoperation execute -af create_instance_template.xml -appName '$[MySQL]' -clientName $[client1] -instanceName $[instance1] -BinaryDirectory '$[C:\Program Files\MySQL\MySQL Server 5.1\bin]' -LogDataDirectory $['C:\Program Files\MySQL\MySQL Server 5.1]' -configFile '$[C:\Program Files\MySQL\MySQL Server 5.1\my.ini]' -port $[3306] -SAUser/userName $[root] -SAUser/password $[mysql] -NTUser/userName '$[testwin\administrator]' -NTUser/password '$[password]' -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[SP1] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[SP1]
Modifying an Instance

  1. Download the modify_instance_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute -af modify_instance_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] -userGroupName $[xxxxx] -associatedUserGroupsOperationType $[xxxxx] -BinaryDirectory $[xxxxx] -LogDataDirectory $[xxxxx] -ConfigFile $[xxxxx] -port $[xxxxx] -SAUser/userName $[xxxxx] -SAUser/password $[xxxxx] -enableAutoDiscovery $[xxxxx] -mysqlStorageDevice/logBackupStoragePolicy/storagePolicyName $[xxxxx] -mysqlStorageDevice/commandLineStoragePolicy/storagePolicyName $[xxxxx]

The following examples show some common modification operations.

Specifying the Configuration File
 
qoperation execute -af modify_instance_template.xml -appName '$[MySQL]' -clientName $[client1] -instanceName $[instance1] -ConfigFile '$[C:Program FilesMySQLMySQL Server 5.5my.ini]' -SAUser/userName '$[user1]' -SAUser/password '$[pwd1]'
Specifying the Binary and Log Data Directory
 
qoperation execute -af modify_instance_template.xml -appName '$[MySQL]' -clientName $[client1] -instanceName $[instance1] -BinaryDirectory '$[C:Program FilesMySQLMySQL Server 5.5bin]' -LogDataDirectory '$[C:Program FilesMySQLMySQL Server 5.5data]' -SAUser/userName '$[user1]' -SAUser/password '$[pwd1]'
Enabling Proxy Backup Operation

  1. Download the enable_proxy_instance_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute -af enable_proxy_instance_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] -isProxyEnabled $[true] -proxyInstance/clientName $[xxxxx] -proxyInstance/instanceName $[xxxxx] -runBackupOnProxy $[true] -isUseSSL $[true]

Example:

 
qoperation execute -af enable_proxy_instance_template.xml -appName '$[MySQL]' -clientName '$[client1]' -instanceName '$[instance1]' -isProxyEnabled $[true] -proxyInstance/clientName  ‘$[client2]’ -proxyInstance/instanceName '$[instance2]' -runBackupOnProxy $[true] -isUseSSL $[true]
Getting Instance Properties

  1. Download the get_instance_properties_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute -af get_instance_properties_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx]
Deleting an Instance

  1. Download the delete_instance_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute -af delete_instance_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx]
Available Parameters for Instance Configuration

The following table displays all the parameters you can use with the commands mentioned in the above sections. To add a parameter to your command, use the following syntax: (A example is provided at the end of the table.)

qoperation execute -af $[template XML file] -$[parameter name] $[value]

Parameter

Description of Parameter Values

clientName

Name of the client computer.

appName

Name of the application. In this case it would be 'MySQL'.

instanceName

Name of the MySQL instance. If you are specifying an instance other than the default instance, the name must be entered along with the client name, e.g. client1\instance1.

userGroupName

Name of the user group to be associated to the instance. This is the user group that you associate from the Security tab of the instance properties dialog box in the CommCell Console.

associatedUserGroupsOperationType

Specifies the operation that you want to perform on the user groups. Valid values are:

  • ADD, to add a new user group.

  • OVERWRITE, to change the existing user groups with others.

  • DELETE, to delete a user group.

BinaryDirectory

Path of the binary directory for the database instance.

LogDataDirectory

Path of the directory where the logs are stored for the database instance.

ConfigFile

Path of the configuration file for the database instance.

port

The port (on Windows) or socket file (on Unix) to open the communication between the MySQL server and its clients.

enableAutoDiscovery

Option to search in the MySQL instance for databases that are not configured in order to add them to the system. This discovery process runs on the entire instance prior a backup operation.

Valid values are True/False.

logStoragePolicy/storagePolicyName

Name of the storage policy used to back up this instance.

SAUser/userName

Name of the MySQL database administrator who has permissions to perform jobs.

SAUser/password

Password for the MySQL database administrator.

newName

New name of the MySQL instance.

The following example show how to add a parameter for a command:

Specifying the Configuration File

qoperation execute -af modify_instance_template.xml -appName '$[MySQl]' -clientName $[client1] -instanceName $[instance1] -ConfigFile '$[C:Program FilesMySQLMySQL Server 5.5my.ini]' -SAUser/userName '$[user1]' -SAUser/password '$[pwd1]'

Subclient Configuration

Creating a Subclient

  1. Download the create_subclient_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute –af create_subclient_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] –subclientName $[xxxxx] -dataBackupStoragePolicy/storagePolicyName $[xxxxx]
Modifying a Subclient

  1. Download the modify_subclient_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute –af modify_subclient_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] –subclientName $[xxxxx]

Example:

 
qoperation execute -af modify_subclient_template.xml -appName '$[MySQL]' -clientName '$[client1]' -instanceName '$[instance1]' -subclientName '$[default]' -dataBackupStoragePolicy/storagePolicyName '$[SP1]' -mySqlSubclientProp/numberOfBackupStreams $[2] -commonProperties/excludeFromSLA $[false]

Example to enable block-level backup at the subclient level:

 
qoperation execute -af modify_subclient_template.xml -appName '$[MySQL]' -clientName '$[client1]' -instanceName '$[instance1]' -subclientName '$[default]' -mySqlSubclientProp/isUseBlockLevelBackup $[1] -dataBackupStoragePolicy/storagePolicyName '$[SP1]' -isSnapBackupEnabled $[true]  -snapShotEngineName '$[native]'

Note: You can enable block-level backup using the above example only on a Linux computer.

Updating Subclient Content

  1. Download the update_content_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute –af update_content_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] –subclientName $[xxxxx]
Example:

Example:

 
qoperation execute –af update_content_template.xml -appName '$[MySQL]' -clientName '$[client1]' -instanceName '$[instance1]' –subclientName '$[sc1]' -mySQLContent/databaseName '$[db1]'

Note

You can add multiple databases to the subclient by modifying the XML file as shown in the example update_content_template.xml file.

Enabling Proxy Backup Operation

  1. Download the enable_proxy_subclient_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute -af enable_proxy_subclient_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] –subclientName $[xxxxx] -dataBackupStoragePolicy/storagePolicyName $[xxxxx] -mySqlSubclientProp/numberOfBackupStreams $[xxxxx] -commonProperties/excludeFromSLA $[false] –isProxyEnabled $[true] –isFailOverToPrduction $[true]

Example:

 
qoperation execute -af enable_proxy_subclient_template.xml -appName '$[MySQL]' -clientName '$[client1]' -instanceName '$[instance1]' –subclientName '$[sc1]' -dataBackupStoragePolicy/storagePolicyName '$[sp1]' -mySqlSubclientProp/numberOfBackupStreams $[2] -commonProperties/excludeFromSLA $[false] –isProxyEnabled $[true] –isFailOverToPrduction $[true]
Getting Subclient Properties

  1. Download the get_subclient_properties_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute –af get_subclient_properties_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] –subclientName $[xxxxx]
Deleting a Subclient

  1. Download the delete_subclient_template.xml file and save it on the computer from where the command will be executed.

  2. Execute the following command from the <Software_Installation_Directory>/Base folder after substituting the parameters values.

     
    qoperation execute –af delete_subclient_template.xml -appName '$[MySQL]' -clientName $[xxxxx] -instanceName $[xxxxx] -subclientName $[xxxxx]
Available Parameters for Subclient Configuration

The following table displays all the parameters you can use with the commands mentioned in the above sections. To add a parameter to your command, use the following syntax: (Some examples are provided at the end of the table.)

qoperation execute -af $[template XML file] -$[parameter name] $[value]

Parameter

Description of Parameter Values

appName

Name of the application. In this case it would be 'MySQL'.

clientName

Name of the client computer.

instanceName

Name of the MySQL instance.

subclientName

Name of the MySQL subclient.

enableBackup

Option to enable backup of subclient.

Valid values are True/False.

networkAgents

Number of Network Agents.

encryptionFlag

Option to set the encryption points during backups. Valid values are:

  • ENC_MEDIA_ONLY, to encrypt the backup data after transmission and prior to storage on the media.

  • ENC_NETWORK_AND_MEDIA, to encrypt the backup data before transmission. The data is stored encrypted on the media.

  • ENC_NETWORK_ONLY, to encrypt the backup data before transmission and then decrypt the data prior to storage on the media.

  • ENC_NONE, to disable data encryption.

softwareCompression

Option to enable compression on the Client or MediaAgent computer. Valid values are:

  • ON_CLIENT, to enable software compression on the client.

  • ON_MEDIAAGENT, to enable software compression on the MediaAgent.

  • OFF, to disable software compression.

dataBackupStoragePolicy/storagePolicyName

Name of Storage Policy to be associated for backup.

enableDeduplication

Option to enable deduplication on subclient.

Valid values are True/False.

generateSignature

A component of deduplication performed on the client or MediaAgent computer. Valid values are:

  • ON_CLIENT, to enable signature generation on the client.

  • ON_MEDIA_AGENT, to enable signature generation on the MediaAgent.

  • OFF, to disable signature generation.

mySqlSubclientProp/numberOfBackupStreams

Option to change the number of streams for data backup.

postBackupCommand

Path to the post-process script that will be run after the backup.

preBackupCommand

Path to the pre-process script that will be run before the backup.

runAs

Option to specify the user name who has permissions to run the pre-process and post-process scripts. Valid values are:

  • USE_IMPERSONATION, to specify a user with enough privileges to run the scripts. When using this value, you also need to provide the user credentials:

    -prepostUserName/userName <user name> -prepostUserName/password <password>

  • USE_LOCAL_SYS_ADMIN, to use the administrator account to run the scripts.

runPostBackup

Option to run a process after backup completes.

Valid values are Yes/No.

impersonateUser/userName

User name of the account that has the required privileges to access the data on a network share when specifying UNC paths for the subclient content.

impersonateUser/password

Password of the account that has the required privileges to access the network share. This parameter must be used along with the 'impersonateUser/userName' parameter.

mySQLContent/databaseName

Name of the database to be added as subclient content.

contentOperationType

Option to add, modify or delete the subclient content. Valid values are:

  • ADD, to add the subclient content.

  • OVERWRITE, to modify the subclient content.

  • DELETE, to delete the subclient content.

The following examples show how to add a parameter for a command:

Enable Backup

To enable backup for a subclient, add the 'enableBackup' parameter to the following command:

qoperation execute –af modify_subclient_template.xml -appName 'MySQL' -clientName client1 -instanceName instance1 –subclientName subclient1 -enableBackup true

Setting a Storage Policy

To assign a storage policy to a subclient, add the 'storagePolicyName' parameter to the following command:

qoperation execute –af modify_subclient_template.xml -appName 'MySQL' -clientName client1 -instanceName client1\instance1 –subclientName subclient1 -dataBackupStoragePolicy/storagePolicyName SPdata

Deleting the Client (qdelete client)

Description

This command can be used to deconfigure and/or delete a client, along with its agents.

By default, the qdelete client command asks for confirmation before deleting the client. You can skip the confirmation prompt with the -y option.

Upon successful completion, qdelete client displays the message "Deleted the client successfully" on the command prompt. In case of an error, an error code and description are displayed as: "client: Error errorcode: errordescription"

Usage
qdelete client [-cs $[commserve_host_name]] -c $[client] [-deconfigure] [-y] [-tf $[tokenfile]] [-tk $[token]] [-af $[clientfile]] [-h]
Options

-cs

CommServe host name

-c

Client computer name

-deconfigure

Deconfigures a client without deleting it

-y

Delete without confirmation

-tf

Reads token from a file

-tk

Token string

-af

Reads client name from a file

-h

Displays help
Diagnostics

Possible exit status values are:

0 - Successful completion.

1 - CLI usage failures, due to the use of an unsupported option or missing argument.

2 - Any other failure.

Examples

  • Delete a client with name client1. 

    qdelete client  -c $[client1]
 This command deconfigures and deletes a client, do you want to continue (y/n)? [n]

  • Deconfigure, but do not delete, a client with name client1

    qdelete client -c $[client1] -deconfigure -y

  • Delete a set of clients specified in an argument file. 

    qdelete client -af "$[E:\clients.txt]"

    In this example, clients.txt is a text file containing a list of client names. Ensure that the file is in the following format: 

    [client]
 $[Client01]
 $[Client02]
 $[ClientXX]

Note

You can mass-delete clients with or without their associated MediaAgents using the qdelete $[client]command. You can include this command (along with the qdelete mediaagent command, if desired) in a script. Mass deletion of these items is useful if you want to remove them after a split of a CommCell. To mass-delete items where the CommCell is not split, be sure to run the script from the install location of the CommServe.

Deleting the Agent (qdelete dataagent)

Description

This command deconfigures or deletes the specified agent.

By default, the qdelete dataagent command asks for confirmation before deletion. You can skip the confirmation prompt using the "-y" option.

Upon completion, qdelete dataagent displays a message that the agent was successfully deleted on the command prompt. In case of an error, an error code and description are displayed as: "dataagent: Error errorcode: errordescription"

Usage
qdelete dataagent -c $[client] -a $[agent] [-deconfigure] [-y] [-tf $[tokenfile]] [-tk $[token]] [-h]
Options

-c

Client computer name

-a

The agent to be deleted (see Argument Values - Agent Types)

-d

Deconfigures the agent without deleting it

-y

Delete without confirmation

-tf

Reads token from a file

-tk

Token string

-h

Displays help
Diagnostics

Possible exit status values are:

0 - Successful completion.

1 - CLI usage failures, due to the use of an unsupported option or missing argument.

2 - Any other failure.

Examples

  • Delete an agent named MyDataAgent under client client1. 

    qdelete dataagent -c $[client1] -a $[MyDataAgent]
This command deconfigures and deletes an agent, do you want to configure (y/n)

  • Deconfigure an agent named MyDataAgent under client client1 without any confirmation. 

    qdelete client -c $[client1] -a $[MyDataAgent] -deconfigure - y

Log Off from the CommServe

Once you have completed the command line operations, you can logout from the CommServe using the following command:

 
qlogout -cs commserve

For example, to log out from the CommServe 'Server1'. 

qlogout -cs $[Server1]
×

Loading...