Command Line Interface - Configuration - Active Directory iDataAgent

You can use the command line interface to configure your subclient for backup.

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

Configuring a Subclient Using XML

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:

qoperation execute -af <template XML file> -<parameter name> <value>

Parameter	Description of Parameter Values
appName	Specifies the name of the application. In this case it would be 'Active Directory'.
clientName	Specifies the name of the client as displayed in the CommCell Browser (e.g., client1).
instanceName	Specifies the name of the Active Directory instance (e.g., DefaultInstanceName).
backupsetName	Name of the backup set. If the backup set name is not specified in the command query, the default backup set is used by default.
subclientName	Specifies the name of the Subclient (e.g. subclient1).
encryptionFlag	Specifies whether to enable encryption. Valid values are: ENC_NONE ENC_NETWORK_AND_MEDIA ENC_MEDIA_ONLY ENC_NETWORK_ONLY
contentOperationType	Modification type. Valid values are ADD, to add content to the subclient. OVERWRITE, to overwrite contents to the subclient. DELETE, to delete the contents from the subclient.
description	Specifies the Subclient description.
enableBackup	Option to allow backup. Set this to 'true'.
networkAgents	Number of Network Agents (e.g., 2). Valid vales are 1-4.
softwareCompression	Specifies whether 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 USE_STORAGE_POLICY_SETTINGS, to use the software compression options defined on the storage policy OFF, to disable software compression
throttleNetworkBandwidth	Enhancing backup performance by reducing network bandwidth overhead. Valid values are 2-2147483647.
dataBackupStoragePolicy/storagePolicyName	Specifies the data backup storage policy for the Oracle data backup.
enableDeduplication	Specifies whether to enable or disable deduplication. Valid values are true/false.
generateSignature	Specifies whether deduplication is performed on the client or MediaAgent computer. This can only be set when the "enableDeduplication" parameter is 'true'. 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.
preBackupCommand	Specifies the script to run before a backup starts.
postBackupCommand	Specifies the script to run after the backup completes.
runPostBackup	Specifies whether this process will execute for all attempts to run the phase. Valid values are YES/NO.
preSNAPCommand	Specifies the pre-process script to run before snapshot.
postSNAPCommand	Specifies the post-process script to run after snapshot.
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.
preSnapProcessOn	Where to run the preSNAPCommand Valid values are: SOURCE - run the command on the source PROXY - run the command on the proxy server
postSnapProcessOn	Where to run the preSNAPCommand Valid values are: SOURCE - run the command on the source PROXY - run the command on the proxy server
contentOperationType	Modification type. Valid values are ADD, to add content to the subclient OVERWRITE, to overwrite contents to the subclient. DELETE, to delete the contents from the subclient.
content/path	Location of the content to be backed up. This parameter must be used along with the 'contentOperationType' parameter, for example: -contentOperationType <value> -content/path '<path value>' Note the following: If you want to specify a wildcard to the content path, you must add '\/\/" (back and forward slash) at the end of the path to enable the detection of wildcard characters: `-content/path 'datapath*\/\/'` If you are using a UNC path to specify the subclient content, you must also use the 'impersonateUser/userName' and 'impersonateUser/password' parameters to provide the credentials of a user account that has the required privileges to access the network share (where the content resides).

Creating a Subclient

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

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

qoperation execute -af create_subclient_template.xml -appName 'Active Directory' -clientName 'client1' -backupsetName 'defaultBackupSet' -subclientName 'subclient1'

Updating a Subclient

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

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

qoperation execute -af update_subclient_template.xml -appName 'Active Directory' -clientName 'client1' -backupsetName 'defaultBackupSet' -subclientName 'subclient1'

Getting Subclient Properties

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

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

qoperation execute -af get_subclient_template.xml -appName 'Active Directory' -clientName 'client1' -backupsetName 'defaultBackupSet' -subclientName 'subclient1'

Deleting a Subclient

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

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

qoperation execute -af delete subclient_template.xml -appName 'Active Directory' -clientName 'client1' -backupsetName 'defaultBackupSet' -subclientName 'subclient1'

Available Commands

The following section provides a list of commands that can be used by the Active Directory iDataAgent.

Note

Before you run a command, make sure to log on to the CommServe computer using the qlogin command. Similarly, use the qlogout command to log off from the CommServe computer.

Qcreate Backupset

Description

This command creates a new backup set under the given client and agent.

The qcreate backupset command also allows the user to create default backup sets and on-demand backup sets. The default subclient created under the backup set can also be associated with a storage policy. If a storage policy name is not included, the subclient remains unassigned.

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

Usage

qcreate backupset -c client -a dataagenttype -i instance -n backupset [-sp storagepolicy] [-t NORMAL|DEFAULT|ONDEMAND] [-tf tokenfile] [-tk token] [-af Argument Filepath] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for certain agents
-n	Name of the backup set to be created
-t	Type of backup set (NORMAL, DEFAULT, or ONDEMAND)
-sp	Storage policy name with which default subclients are to be associated
-tf	Reads token from a file
-tk	Token string
-af	Reads arguments from a file
-h	Displays help

Argument File

client	Client computer name
dataagent	Agent type installed on client computer (see Argument Values - Agent Types)
backupset	Backup set name to be created
sp	Storage policy name to be associated with all subclients in the backup set
backupsettype	Backup set type (NORMAL, DEFAULT, or ONDEMAND)
compressionat	Compression at client or MediaAgent (CLIENT\|MA)
networkagents	Number of network agents
prebackup	Prebackup command name
postbackup	Postbackup command name
prescan	Prescan command name
postscan	Postscan command name

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

Create a backup set with name backupset1 under client client1 and Agent Q_ACTIVEDIR.

qcreate backupset -c client1 -a Q_ACTIVEDIR -n backupset1

Qcreate Subclient

Description

This command creates a new subclient under a specified client and agent. The instance name and backup set name are required for certain agents, and should be specified when applicable.

The new subclient will be associated with the specified storage policy and content. If you want to enable deduplication, create the [singleinst] section in the Argument file and specify whether deduplication should be performed in the MediaAgent or the Client.

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

Usage

qcreate subclient -c client -a dataagenttype -b backupset -i instance -n subclient -sp storagepolicy -f content1 [-f content2 -f content3 ..] [-wc y|n] [-tf tokenfile] [-tk token] [-af argsfilepath] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-b	Backup set name, required for certain agents
-i	Instance name, required for certain agents
-n	Name of the subclient to be created
-sp	Name of the storage policy to be associated with the subclient
-f	File/Directory Path to be included as content in the new subclient. See syntax to specify multiple content.
-wc	Does File/Directory Paths have wildcards (y\|n)
-tf	Reads token from a file
-tk	Token string
-af	Reads arguments from a file
-h	Displays help

Argument File

client	Client computer name
dataagent	Agent type installed on client computer (see Argument Values - Agent Types)
backupset	Backup set name
subclient	Subclient name to be created
datareaders	Number of data readers
sp	Storage policy name to be associated with the subclient.
content	Subclient content (list of files/directories).
compressionat	Compression at client or MediaAgent (CLIENT\|MA)
networkagents	Number of Network Agents
prebackup	PreBackup command name
postbackup	PostBackup command name
prescan	Prescan command name
postscan	PostScan command name
wildcard	Wildcard characters
singleinst	MediaAgent or Client
description	User-defined description

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

Create a subclient with name subclient1 under client client1, iDataAgent Q_ACTIVEDIR and backup set backupset1 with content c:\ and storage policy sp1.

qcreate subclient -c client1 -a Q_ACTIVEDIR -b backupset1 -n subclient1 -f "c:\" -sp sp1

Qinfo Backupset

Description

This command displays information about a given backup set. If the agent supports instances above backup sets, only the backup sets under the specified instance are listed.

In case of an error, an error code and description are displayed as: "backupset: Error errorcode: errordescription"

Usage

qinfo backupset -c client -a dataagenttype -i instance -b backupset [-desc] [-tf tokenfile] [-tk token] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for a few agents
-b	Backup set name
-desc	Displays description provided by the user To display the entire user description for the backup set without any other information, be sure to include the -desc option when you run the command. Otherwise, all the requested information along with only a partial description will be displayed.
-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

Display information about a backup set backupset1 in client client1 and Agent Q_ACTIVEDIR.

qinfo backupset -c client1 -a Q_ACTIVEDIR -b backupset1

Sample Output:

Name         : backupset1
 Default      : Yes
 OnDemand     : No
 Description  : Backup Set description

Qinfo Subclient

Description

This command displays information about a subclient under a specified client, agent, and instance/backup set. The backup set name and instance name should be specified based on the agent, as certain agents place subclients under backup sets, and others place them under the instance.

In case of an error, an error code and description are displayed as: "subclient: Error errorcode: errordescription"

Usage

qinfo subclient -c client -a dataagenttype -i instance -b backupset -s subclient [-desc] [-tf tokenfile] [-tk token] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for a few agents
-b	Backup set name, required for a few agents
-s	Subclient name
-desc	Displays description provided by the user To display the entire user description for the backup set without any other information, be sure to include the -desc option when you run the command. Otherwise, all the requested information along with only a partial description will be displayed.
-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

Display information about a subclient subclient1 in the client client1, Agent Q_ACTIVEDIR and backup set backupset1.

qinfo subclient -c client1 -a Q_ACTIVEDIR -b backupset1 -s subclient1

Sample Output:

Name            : subclient1
 Default         : Yes
 Storage Policy  : my_sp
 Description     : Subclient description

Qlist Backupset

Description

This command lists the names of all the backup sets in the specified client and agent. If the agent supports instances above the backup set level, then only the backup sets under the specified instance are listed. Whenever more than one backup set is found, each backup set is listed in its own line on the command prompt. No message is displayed whenever backup sets are not found.

In case of an error, an error code and description are displayed as: "backupset: Error errorcode: errordescription"

Usage

qlist backupset -c client -a dataagenttype -i instance [-tf tokenfile][-tk token] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for certain agents
-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.

Example

List all the Backup sets in the client client1, agent MyDataAgent.

qlist backupset -c client1 -a MyDataAgent

The output for the qlist backupset command is:

defaultBackupSet
 bs1

Qlist Subclient

Description

This command lists the names of all the subclients in a specified client, agent, and instance/backup set. Whenever more than one subclient is found, each subclient is listed in its own line on the command prompt. No message is displayed whenever subclients are not found.

In case of an error, an error code and description are displayed as: "subclient: Error errorcode: errordescription"

Usage

qlist subclient -c client -a dataagenttype -i instance -b backupset [-tf tokenfile] [-tk token] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for certain agents
-b	Backup set name, required for certain agents
-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

List all the Subclients in the client client1, Agent Q_ACTIVEDIR and backup set backupset1.

qlist subclient -c client1 -a Q_WIN_2KFS -b backupset1

Sample Output:

default
 subclient1

Qmodify Subclient

Description

This command modifies the storage policy, content, or user-defined description of a given subclient.

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

Note

To use this command, you must ensure that the QCMD_SUPPORT_MODIFY_SUBCLIENT additional setting is set to 1.

Usage

qmodify subclient -c client -a dataagenttype -i instance -b backupset -s subclient -sp storagepolicy -f content [-ow overwrite] [-drs datareaders] [-wc y|n] [-af ArgumentFilepath] [-tf tokenfile] [-tk token] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-i	Instance name, required for a few agents
-b	Backup set name, required for a few agents
-s	Name of the subclient to be modified
-sp	Name of the storage policy to be associated with the subclient
-f	File/Directory Path to be added to the existing content When using the -f content option, you must verify that the subclient content is in the correct format path. This command does not enforce the content format, and any path (including an incorrect path) can be specified. This may result in incorrect content being assigned to a file system subclient and a "pending" subclient scan.
-wc	Do file/directory paths have wildcards (y\|n)
-ow	If the contents needs to be overwritten (0:1)
-drs	Number of data readers
-af	Input file containing arguments
-tf	Reads token from a file
-tk	Token string
-h	Displays help

Argument File

client	Client computer name
dataagent	Agent type installed on source client computer (see Argument Values - Agent Types)
instance	Instance name to which the subclient belongs, required for certain agents
backupset	Backup set name to which the subclient belongs, required for certain agents
subclient	Name of the subclient to be modified
sp	New storage policy for the subclient
content	List of files/directories to be added to the existing content The content option is supported for file system Agents. Although, changing the storage policy association of a subclient is supported for all agents.
datareaders	Number of data readers
wildcard	Do file/directory paths have wildcards (y\|n)
description	User-defined description

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

Modify a subclient with name subclient1 under client client1 and Agent Q_ACTIVEDIR and backup set backupset1 by changing its storage policy to sp1.

qmodify subclient -c client1 -a Q_ACTIVEDIR -b backupset1 -s subclient1 -sp sp1

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.

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
```

Qdelete Backupset

Description

This command deletes a given backup set.

When the backup set to be deleted contains archived data, the command asks the user to confirm the deletion. This prevents the user from accidentally removing backup sets that may have archive jobs. If you want to skip the confirmation prompt, you can use the "-skc" option.

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

Usage

qdelete backupset -c client -a dataagenttype -b backupset [-skc] [-tf tokenfile] [-tk token] [-af ArgumentFilepath] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-b	Name of the backup set to be deleted
-skc	Skips the confirmation prompt to delete the backup set if archived data is found on the backup set.
-tf	Reads token from a file
-tk	Token string
-af	Reads arguments from a file
-h	Displays help

Argument File

client	Client computer name
dataagent	Agent type installed on client computer (see Argument Values - Agent Types)
backupset	Backup set name to be deleted

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.

Example

Delete a backupset with name bs1 under client client1 and Agent MyDataAgent.

qdelete backupset -c client1 -a MyDataAgent -b bs1

Qdelete Subclient

Description

This command deletes a given subclient.

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

Usage

qdelete subclient -c client -a dataagenttype -b backupset -s subclient [-tf tokenfile] [-tk token] [-af ArgumentFilepath] [-h]

Options

-c	Client computer name
-a	Agent type installed on client computer (see Argument Values - Agent Types)
-b	Name of the backup set
-s	Name of the subclient to be deleted
-af	Reads arguments from a file
-tf	Reads token from a file
-tk	Token string
-h	Displays help

Argument File

client	Client computer name
dataagent	Agent type installed on client computer (see Argument Values - Agent Types)
backupset	Backup set name
subclient	Subclient name to be deleted

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.

Example

Delete a subclient with name subclient1 under client client1, Agent Q_ACTIVEDIR and backupset backupset1.

qdelete subclient -c client1 -a Q_ACTIVEDIR -b backupset1 -s subclient1