Command Line Interface - Restore - Windows File System iDataAgent

Configuration Backup Restore
Table of Contents

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

Browse and Restore Data

You can now perform Browse operations using Command Line interface. It takes input from an XML file and enters the output in another XML file.

Browsing Data

Below is an example of Browsing data between a specific time range using a command line XML.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Browse">
    <session/>
    <entity commCellId="2" clientName="imindexing33" subclientName="SC2" backupsetName="commandline" appName="Windows File System" _type_="0"/>
    <paths path="E:\SuperBrowse\SC2\"/>
    <queries queryId="0" type="DATA">
    </queries>
    <timeRange fromTime="Dec 31, 1969" toTime="Nov 12, 2013"/>
    <options restoreIndex="true"/>
    <mode mode="2"/>
    <paging skipNode="0" pageSize="1000" firstNode="0"/>
    <ma clientName="indexingstorage"/>
    <user userName="admin"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

  2. Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your browse results.

    qlist backupfiles -af input_template.xml -dpath output_template.xml

  3. Verify the results in the output_template.xml.

Supported Parameters and Possible Values

The above input  XML file provide displays browsing data between a specified time.

The following table displays the various command line parameters, their values and options that are used in the above XML query:

Parameter Values Description

opType

The following values can be used to define the given parameter. For the above example Browse has been selected.
  • Browse
  • Find
  • Versions
  • IndexPrediction
This parameter is used to define the type of operation that you would perform during the XML request.

Entity

The following values need to be defined for this parameter:
  • appName="Windows File System"
  • backupsetName="backupset1"
  • clientName="client1"
  • subclientName="subclient1"
appName: This the type of Agent on which the Browse operation is performed and the value can be obtained form APP_iDAtype table.

backupsetName: Name of the backupset on which the browse operation will be performed. If no name is specified, defaultBackupSet s used.

clientName: Name of the client to which the backupset belongs.

subclientName: Subclient that was backed up. The browse operation will yield results on this subclient.

paths

  The path to the actual folder level on which the browse operation will be performed.

You must provide the exact path to the folder which contains the backed up files.

For example:

E:\superbrowse\SC2. All data under the SC2 folder will be displayed.

Similarly, for find operations, specify the path using wildcard.

For example:

“\**\*”

timeRange

The following values can be used to define the given parameter:
  • Latest
  • Point in time
  • TimeRange
The above example uses TimeRange. The Time range can be specified in the below formats:

<timeRange fromTime="2013-11-12 05:00:00" toTime="2013-11-12 11:40:29"/>

<timeRange fromTime="Dec 31, 1969" toTime="Nov 12, 2013"/>

Browsing Data Using Filters

Below is an example of browsing data using filters like file name and file type using a command line XML.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Browse">
    <entity type="0" subclientName="" commCellId="2" clientName="imindexing33" backupsetName="commandline" appName="Windows File System"/>
    <mode mode="2"/>
    <paths path="E:\superbrowse\SC2\Entitysearchfiles\Amex\"/>
    <options restoreIndex="true"/>
    <queries type="DATA" queryId="0">
    <whereClause connector="AND">
    <criteria field="FileName" dataOperator="LIKE"><values val="*.txt"/>
    </criteria>
    </whereClause>
    </queries>
    <user userName="admin"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

  2. Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your browse results.

    qlist backupfiles -af input_filter.xml -dpath output_template.xml

  3. Verify the results in the output_filter.xml.

Browsing Data Using Operators

Below is an example of browsing data using operators like file size greater than certain value, using a command line XML.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Browse">
    <entity type="0" subclientName="" commCellId="2" clientName="" backupsetName="" appName=""/>
    <mode mode="2"/>
    <paths path=""/>
    <options restoreIndex="true"/>
    <queries type="DATA" queryId="0">
    <whereClause connector="AND">
    <criteria field="FileSize" dataOperator="GT">
    <values val="5024"/>
    </criteria>
    </whereClause>
    </queries>
    <user userName="admin"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

  2. Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your browse results.

    qlist backupfiles -af input_operator.xml -dpath output_template.xml

  3. Verify the results in the output_operator.xml.

Browsing Data Using Functions

Below is an example of browsing data using functions like aggregate using a command line XML.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Find">
    <entity commCellId="2" clientName="imindexing33" subclientName="SC2"
    backupsetName="commandline" appName="Windows File System" _type_="0"/>
    <paths path="\**\*"/>
    <mode mode="2"/>
    <queries type="AGGREGATE" queryId="1">
    <aggrParam field="FileName" aggrType="COUNT"/>
    <whereClause connector="AND">
    <criteria field="FileName" dataOperator="LIKE">
    <values val="*.docx"/>
    </criteria>
    </whereClause>
    </queries>
    <ma clientName="indexingstorage"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

  2. Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your browse results.

    qlist backupfiles -af input_function.xml -dpath output_template.xml

  3. Verify the results in the output_operator.xml.

Browsing Multiple Versions of a File

You can use command line to view a particular backed up file version for restores. If a time range browse is performed, versions are shown across cycles.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Versions">
    <session/> <entity commCellId="2" clientName="imindexing33" subclientName="SC2"
    backupsetName="commandline" appName="Windows File System" _type_="0"/>
    <paths path="E:\SuperBRowse\SC2\Lemmatize\Intelligence.txt"/>
    <queries queryId="0" type="DATA"> </queries>
    <timeRange fromTime="2013-06-28 19:30:39" toTime="2013-08-27 19:30:39"/>
    <options restoreIndex="true"/>
    <paging skipNode="0" pageSize="1000" firstNode="0"/>
    <ma clientName="indexingstorage"/>
    <user userName="admin"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

     Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your browse results.

    qlist backupfiles -af input_version.xml -dpath output_template.xml

  2. Verify the results in the output_operator.xml.

Supported Parameters and Possible Values for Filters, Operators and Functions

The above  XML files helps in browsing data using specific filters, functions and operators.

The following table displays the various command line parameters, their values and options that are used in the above XML queries:

Parameter Values Description

queryId

The following values can be used to define the given parameter:

QueryType

This has a string value that is used to identify each query. The response for each query also has the same id.

Each query type can have one of the following values:

  • Data

    Response is returned as a list of browseData structures. A string value as dataParam can be passed.

  • Aggregate

    This is used to compute aggregate data on a desired result set . aggrType can be set to one of the following values

    • MAX
    • MIN
    • AVG
    • SUM
    • COUNT
  • TopBottom

    For TopBottomParam, the count is number of items.

 

topBottomParam topBottomParam can have one of the following values:
  • FilteretedBrowseField
  • count
  • Ascending

 

aggregateParam aggregateParam can have one of the following values:
  • aggregateParam

    This is used to compute aggregate data on a desired result set . aggrType can be set to one of the following values

    • MAX
    • MIN
    • AVG
    • SUM
    • COUNT
  • FilteretedBrowseField
  • FilteretedBrowseField Group By

 

dataParam dataParam can have one of the following values:
  • fileFilteretedBrowseField
  • browsePpging can further have the following values:
    • firstnode
    • SkipNode
    • Pagesize

Options

All options mentioned below are set to “false” by default. The behavior changes when they are set to “true”.

The description column describes the behavior when the value is set to "true".

showDeletedFiles This parameter displays the deleted files along with existing files in the browse results.
restoreIndex This parameter restores the index automatically, if it is not available in cache.
caseInsensitive This parameter enforces a case insensitive search for case-sensitive platforms.
skipIndexRestore This parameter ensures not to restore the index and displays partial or no results
includeMetadata This parameter enables inclusion of troubleshooting folders in the browse results.

Troubleshooting folders include collect files or job specific metadata files of a file system.

whereClause A query can have multiple where clauses . For example:

<whereClause> <criteria dataOperator="IN" field="ModifiedDate"> <values val="thisMonth"/> </criteria> </whereClause>

Perform the Restore

In order to run the restores from command line, you need an input xml file which contains the parameter values for configuring the restore options. This input xml file can be obtained using one of the following ways:

  • Download the input xml file template and save it on the computer from where the restore will be performed.
  • Generate the input xml file from the CommCell Console and save it on the computer from where the restore will be performed.

Use the following steps to perform the restore:

  1. Download the restore_template.xml file and save it on the computer from where the command will be executed.
  2. From Command prompt, navigate to <Software_Installation_Directory>/Base and run the following command:

    qlogin -cs <commserve name> -u <user name>

  3. Execute the saved xml script using qoperation execute command.

    qoperation execute -af restore_template.xml -appName 'File System' -clientName xxxxx -backupsetName xxxxx -destPath 'xxxxx' -sourceItem 'xxxxx'

    Note: If the sourceItem parameter contains a directory path, verify the path is valid before you run the command.

  1. Verify the status of the job using the following command:

    qlist job –j JOBID

  2. Once the job completes, logout from the CommServe using the qlogout command.

    qlogout [-cs <commserve_host_name>] [-all] [-tf <tokenfile>] [-tk <token>] [-h]

Examples

Restoring from a Current Backup

qoperation execute -af restore_template.xml -appName 'File System' -clientName client1 -backupsetName backupset1 -destPath 'C:\temp' -sourceItem 'C:\test'

Restoring Files to a Point-in-Time (Date)

qoperation execute -af restore_template.xml -appName 'File System' -clientName client1 -backupsetName backupset1 -destPath 'C:\temp' -sourceItem 'C:\test' -toTimeValue 2011-11-28

Restoring Files to a Point-in-Time (Date and Time)

qoperation execute -af restore_template.xml -appName 'File System' -clientName client1 -backupsetName backupset1 -destPath 'C:\temp' -sourceItem 'C:\test' -toTimeValue 2011-11-28 15:40:00

Restoring by Jobs

qoperation execute -af restore_by_job_template.xml -jobids 52 -sourceItem 2:52 -striplevel 1

where:
  • jobids is the backup job ID
  • sourceItem is the CommCell D and the backup job ID separated by a colon (':'). By default, the CommCell ID is 2.
  • striplevel is the number of folder levels to exclude from the source path. This parameter is optional.

    For example, if you have a directory structure (source path) as /a/b/c and you select strip level 2, the data will be restored from folder c, while folders a and b are excluded. Ensure that the strip level is always less than the source path level.

Step-by-step restores should be performed from the CommCell Console.

Generate the Command Line Script from the CommCell Console

In addition to the parameter values provided in the template xml file, if you want to include additional options for the restore, you can do so by selecting the required options from the CommCell Console and generate the command line xml script for the restore operation.

Follow the steps given below to generate a script which you can use to perform a restore from the command line interface:

  1. From the CommCell Browser, navigate to Client Computers | <Client> | File System.
  2. Right-click the <Backup Set> and click All Tasks | Browse and Restore.
  3. Click View Content.
  1. In the right pane of the Browse window, select the data that you want to restore and click Recover All Selected.
  2. Select the required restore options which you want to execute using the script.
  3. Click Save as Script.

  1. Enter the location to save the script along with the file name and extension. For example, "C:\scripts\myscript.bat" on Windows and "/usr/scripts/myscript.sh" on Unix. Alternatively, you can also click Browse and navigate to the location.

    The script will be saved as a .xml file and .bat/.sh file.

    If a file with the same name already exists in the specified location, both the .xml and .bat/.sh files will be overwritten.

  2. Enter the username and password for the user account which you want to use to perform the restore.

    By default, the user account which you have used to login to CommCell console is used for performing the restore. However, if the user account does not have access to application and database, click Use a different account.

  3. Click OK.

Find Data

Using Command Line XML

You can use command line XML files to perform find operations.

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

    Modify the xml template as per your setup.

    The following example lists the mandatory parameters and sample values.

    <databrowse_BrowseRequest opType="Find">
    <session/> <entity commCellId="2" clientName="imindexing33" subclientName="SC2"
    backupsetName="commandline" appName="Windows File System" _type_="0"/>
    <paths path="\**\*"/> <queries queryId="0" type="DATA">
    </queries>
    <timeRange fromTime="Dec 31, 1969" toTime="Nov 12, 2013"/>
    <options restoreIndex="true"/> <mode mode="2"/>
    <paging skipNode="0" pageSize="1000" firstNode="0"/>
    <ma clientName="indexingstorage"/>
    <user userName="admin"/>
    <advOptions copyPrecedence="0"/>
    </databrowse_BrowseRequest>

  2. Execute the following command from the /Base folder after substituting the parameters values in the input file.

    Make sure to provide the name and path of the output xml file in which you want to retrieve your find results.

    qlist backupfiles -af input_find.xml -dpath output_template.xml

  3. Verify the results in the output_template.xml.

Using qoperation find

Description

This command performs a search operation on backed up files and saves the results to a file. The type of operation is defined in the opType attribute in the XML request file:

  • Find: Performs a recursive search and returns a list of files and folders. Specify recursion by using asterisks in the path attribute as shown: <paths path="C:\data\**\*" />.
  • Browse: Performs a search on one directory and returns a list of files and folders in that directory. (The Browse operation is not recursive.)
  • Versions: Lists all of the versions of a single file.

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

Usage

qlist backupfiles -af <path_to_input_XML_file> -dpath <path_to_output_XML_file> [-tf <tokenfile>] [-tk <token>] [-example] [-h]

Options

-af XML file that contains the request
-dpath Destination path and file name for the XML output file
-tf Reads token from a file
-tk Token string
-example Sample "find" and "browse" XML requests
-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

  • For the default subclient, finds all of the files and folders in the C:\data directory and its subdirectories.

    qlist backupfiles -af c:\searches\find.xml -dpath c:\results\find_results.xml

    XML example for the Find operation:

    <databrowse_BrowseRequest opType="Find">
      <entity _type_="0" appName="Windows File System" backupsetName="defaultBackupSet" clientName="vmcs100_cn" subclientName="default"/>
      <paging pageSize="4294967295" skipNode="0"/>
      <mode mode="2"/>
      <paths path="C:\data\**\*" />
    </databrowse_BrowseRequest>

  • For the default subclient, browses the files and folders in the C:\ directory.

    qlist backupfiles -af c:\searches\browse.xml -dpath c:\results\browse_results.xml

    XML example for the Browse operation:

    <databrowse_BrowseRequest opType="Browse">
      <entity _type_="0"appName="Windows File System" backupsetName="defaultBackupSet" clientName="vmcs100_cn" subclientName="default"/>
      <mode mode="2"/>
      <paging pageSize="4294967295" skipNode="0"/>
      <paths path="C:\"/>
      <timeRange fromTime="0" toTime="1331280338"/>
    </databrowse_BrowseRequest>

  • For the default subclient, lists the versions available for the mydata.txt file.

    qlist backupfiles -af c:\searches\versions.xml -dpath c:\results\versions_results.xml

    XML example for the Versions operation:

    <databrowse_BrowseRequest opType="Versions">
      <entity _type_="0"appName="Windows File System" backupsetName="defaultBackupSet" clientName="vmcs100_cn" subclientName="default"/>
      <mode mode="2"/>
      <paths path="C:\Users\Administrator\Documents\test\mydata.txt"/>
    </databrowse_BrowseRequest>

Example

Use the following steps to perform a wild card search operation on backed up content using find command:

  1. Create an input parameter file with the required arguments and values.

    For example, see the sample input parameter sample.ini on the right.

    [sourceclient]
    silver

    [dataagent]
    Q_FILESYSTEM

    [backupset]
    defaultBackupSet

    [sourcepaths]
    C:\*.xml

    [browsefrom]
    2011/8/22 00:25:00

    [browseto]
    2011/8/22 06:28:00

    [options]
    QR_BROWSE
    QR_NORECURSE
    QR_NOIMAGE
    QR_WILDCARD

  2. Run the qoperation from the command prompt.

    C:\SnapProtect\Base>qoperation find -af "SAMPLEFILE.INI" -rf C:\out_find03.txt
    1: Wed Aug 10 10:44:47 2011 1312987487 Unknown 237 \C:\1.xml