Loading...

Command Line Interface - MediaAgent - XML Files

Table of Contents

Log On to the CommServe Computer

Disk Libraries

Tape Libraries and Stand-Alone Drives

Cloud Libraries

Adding a Cloud Device

Adding a New MediaAgent to a Cloud Storage Device

Adding a Mount Path to the Cloud Library

Key Management Server

Enable or Disable Client Side Deduplication

Delete a Library

Deconfigure MediaAgent from a Tape Library

Vendor Specific XML Parameters

Log On to the CommServe Computer

Before you run command line operations, use the qlogin command to log on to the CommServe computer.

  1. At the command prompt, go to <software installation directory>\Base.
  2. Use the appropriate method to log on to the CommServe computer.

    Method 1:  User Name/Password

    1. Log on to CommServe server1 with user name user1.

      qlogin -cs server1 -u user1
      Password:
      User logged in successfully.

    Method 2:  Token File

    When you use the token file method, you must append the token file to your qcommand.

    1. Create a token file (record the name and location of the file). 
    2. Run the following command:

      qlogin -f <tokenFile>

    3. Enter the user name and password.

      Enter User Name:
      Password:

Disk Libraries

Type the password on the command prompt. Do not edit the XML.

Create a Disk Device

You can use XML to create a disk device and specify a name for the device.

  1. Download the create_disk_device.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent where you want to create a disk device.

    deviceName

    If you do not want the default name for the disk device, specify a name.

    mountPath

    The mount path location for the disk device.

    loginName

    The login name to access the network location where you want to create the path for new disk device.

    Password

    The password to access the network location where you want to create a path for the new disk device.

    Type the password using the command prompt. Do not edit the XML.

    deviceAccessType

    The access type for the disk device. By default, the value is 14.

    To change the access type, refer to the following table.

    Access type

    Value

    Read

    4

    Read and Write

    6

    Read and Write, Preferred Access

    14

     

    Example: Use this example XML file to create a disk device with device name "Disk_Device_1", MediaAgent name "MA1", mount path "E:\Library1\Mountpath1", login username "user1" and device access type "read and write".

  4. From the <software installation directory>\Base folder, run the following command:

    qoperation execute -af <downloaded location>\create_disk_device.xml

          Click here to see sample output.

Create a Disk Library

  1. Download the create_disk_library_local_path.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the new disk library.

    mediaAgentName

    The name of a MediaAgent where you want to create a library.

    mountPath

    The mount path location for the disk library.

    Example: Use this example XML file to create a disk library with library name "Library1", MediaAgent name "MA1" and mount path "E:\Library1\Mountpath1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\create_disk_library_local_path.xml

    To create a disk library with library name "Library1", MediaAgent name "MA1" and mount path "E:\Library1\Mountpath1", run the following command:

    qoperation execute -af <downloaded location>\create_disk_library_local_path.xml -library/libraryName Library1 -library/mediaAgentName MA1 -library/mountPath E:\Library1\Mountpath1

    Click here to see sample output.

Create a Disk Library and a Storage Policy

You can create a disk library and a Storage Policy simultaneously with XML. The Storage Policy uses the disk library that you create as the default data path.

  1. Download the create_disk_library_storage_policy.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent where you want to create a library.

    libraryName

    The name of the new disk library.

    mountPath

    The mount path location for the disk library.

    createStoragePolicy

    When the value is set to 1, a Storage Policy is created.

    When the value is set to 0, a Storage Policy is not created.

    Example: Use this example XML file to create a disk library and storage policy simultaneously with library name "Library1", MediaAgent name "MA1" and mount path "E:\Library1\Mountpath1" .

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\create_disk_library_storage_policy.xml

    Click here to see sample output.

Configuring a Disk Library on a Network

  1. Download the Configure_DiskLibrary.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent where you want to create a library.

    libraryName

    The name of the new disk library.

    mountPath

    The mount path location for the disk library.

    loginName

    Login name to access the network location where you want to create the new disk library.

    password

    Password to access the network location where you want to create the new disk library.

    createStoragePolicy

    When the value is set to 1, a Storage Policy is created.

    When the value is set to 0, a Storage Policy is not created.

    Example: Use this example XML file to create a disk library and storage policy simultaneously with library name "Library1", MediaAgent name "MA1", mount path "\\demo-server\E$\Library1\mountpath1" and login username "user1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\Configure_DiskLibrary.xml

    Click here to see sample output.

Create a Disk Library using a Device

You can use an existing disk device to configure a disk library.

  1. Download the create_disk_library_using_disk_device.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    deviceName

    The name of the disk device that you want to use to configure the disk library.

    libraryName

    The name of the new disk library.

    mediaAgentName

    The name of the MediaAgent.

    baseFolder

    If you do not want the default name for the basefolder, specify a name.

    createStoragePolicy

    When the value is set to 1, a Storage Policy is created.

    When the value is set to 0, a Storage Policy is not created.

    By default, the value is 0

    Example: Use this example XML file to use an existing disk device with device name "Disk_Device_1" and MediaAgent name "MA1" to configure a new disk library with name "Library1" without creating a storage policy and using the default name for the basefolder.

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\create_disk_library_using_disk_device.xml

    Click here to see sample output.

Add a Device Controller on a Disk Device

You can add a controller to a disk device.

  1. Download the add_device_controller_on_disk_device.xml file and save it on the computer where the command is run.
  2. Open the XML file and before running the qoperation command, update the XML parameters listed in the table below.
  3. Change the XML parameters.
    Note: For Fibre Channel and iSCSI transport modes, mount path details and login credentials are not required as inputs in the xml.
     

    Attribute

    Description

    mediaAgentName

    The name of the new MediaAgent that you want to add on the device.

    deviceName

    The name of the disk device.

    mountPath

    The mount path location of the new device controller.

    loginName

    Login name to access the mount path for the new device controller (if the path is a network path).

    Password

    Password to access the mount path for the new device controller (if the path is a network path).

    deviceAccessType

    To specify the access type for the new MediaAgent, refer to the following table.

    Regular


    Access type

    Value

    Read

    4

    Read and Write

    6

    Read and Write, Preferred Access

    14

    Fibre Channel (FC)

    Access type

    Value

    Read

    36

    Read and Write

    38

    iSCSi

    Access type

    Value

    Read

    132

    Read and Write

    134


     

    Example: Use this example XML file to add an additional MediaAgent with name "MA2" on a disk device with device name "Disk_Device_1", mount path "\\demo-server\E$\Library1\mountpath1", login username "user1" and device access type "regular read and write".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\add_device_controller_on_disk_device.xml

    Click here to see sample output.

Adding a Mount Path to a Disk Library on a Network

  1. Download the add_MountPath.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent where you want to add a mount path.

    libraryName

    The name of the disk library on the network where you want to add the mount path.

    mountPath

    The mount path location for the disk library.

    loginName

    Login name to access the network location where the disk library exists.

    password

    Password to access the network location where the disk library exists.

    Example: Use this example XML file to add a mount path "\\demo-server\E$\Library1\mountpath1" to a disk library on network with library name "Library1", MediaAgent name "MA1" and login username "user1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\add_MountPath.xml

    Click here to see sample output.

Create a PnP Library

  1. Download the create_pnp_library.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    libraryName

    The value must be the name or serial number of a configured tape library.

    libSerialNumber

    The value must be PnP in order to create a PnP library.

    Example: Use this example XML file to create a PnP library with PnP serial number "00000001" in a library with name "Library1" and MediaAgent name "MA1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\create_pnp_library.xml

    Click here to see sample output.

Editing PnP Library Properties

  1. Download the edit_pnp_library_prop.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The value must be the name or serial number of a configured tape library.

    usePnpWhenBlank

    Specify that blank disks with no other data is used for data protection operations and allows you to use disks exclusively for data protection purposes.

    Valid values are
    0 (disable)
    1 (enable)
    2 (do not change)

    Example: Use this example XML file to set the low watermark to "500MB" for a PnP library with name "Library1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\edit_pnp_library_prop.xml

Add an Additional Mount Path

You can add additional mount paths to local drives only.

  1. Download the add_mount_path.xml file and save it on the computer from where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of a MediaAgent.

    libraryName

    The name of the disk library where you want to add additional mount path.

    mountPath

    The mount path location that you want to add.

    Example: Use this example XML file to add a mount path "E:\Library1\Mountpath1" to a local disk library with name "Library1" and MediaAgent name "MA1"

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\add_mount_path.xml

    Click here to see sample output.

Add a Mount Path using a Disk Device

You can add a mount path using a disk device.

  1. Download the add_mount_path_using_disk_device.xml file and save it on the computer from where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the disk library where you want to add a mount path.

    deviceName

    The name of the disk device

    mediaAgentName

    The name of the MediaAgent.

    baseFolder

    If you do not want the default name for the basefolder, specify a name.

    Example: Use this example XML file to add a mount path using a disk device with name "Disk_Device_1", MediaAgent name "MA1" and library name "Library1" using the default name for the basefolder.

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\add_mount_path_using_disk_device.xml

    Click here to see sample output.

Sharing a Mount Path

You can share the existing mount path with other MediaAgent.

  1. Download the share_mount_path.xml file and save it on the computer from where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the disk library where the mount path exists.

    library/mediaAgentName

    The name of any MediaAgent associated to the specific mount path.

    library/mountPath

    The mount path that will be shared between the MediaAgents.

    libNewProp/mountPath

    The path of the new MediaAgent

    libNewProp/mediaAgentName

    The name of the new MediaAgent that will share the mount path.

    loginName

    Login name used by the new MediaAgent to access the mount path.

    Password

    Password used by the new MediaAgent to access the mount path.

    deviceAccessType

    Read Device Access = 4

    Read/ Write Device Access = 6

    Read Device Access with Preferred = 12

    Read/Write Device Access with Preferred = 14

    Data Server - IP Read = 20

    Data Server - IP Read/ Write = 22

    Data Server - FC Read = 36

    Data Server - FC Read/ Write = 38

    Data Server - iSCSI Read = 132

    Data Server - iSCSI Read/ Write = 134

    Note: For the Data Server device access type, enter the local path provided in the library/mountPath parameter in the libNewProp/mountPath parameter also.

    proxyPassword

    Password to access the proxy server if a proxy server is present

    Example:

    • Use this example XML file to share a mount path "E:\Library1\Mountpath1" on MediaAgent "MA1" and library "Library1" with another MediaAgent "MA2", new mount path location "\\demoserver\E$\Library1\Mountpath1", device access type "read and write" and login username "user1".
    • Use this example XML file to share a mount path "E:\Library1\Mountpath1" on MediaAgent "MA1" and library "Library1" with another MediaAgent "MA2", new mount path location "E:\Library1\Mountpath1", device access type "Data Server - IP Read/ Write" and login username "user1".
  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\add_mount_path_using_disk_device.xml

    Click here to see sample output.

Editing a Mount Path

You can modify the mount path of the MediaAgent.

  1. Download the Edit_MP_Prop.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the library on which mount path will be updated.

    mediaAgentName

    The name of the MediaAgent.

    mountPath

    The old mount path, that will be edited.

    numOfWritersForMountpath

    The number of writers for the mount path. You can specify a value in the range of 1 to 999.

    When the value is set to 0, disables the mount path for write.

    When the value is set to -1, allows the maximum number of writers for the mount path.

    When the value is set to -2, the existing settings are not altered.

    reserveSpaceInMB

    The total amount of free space that must be available at all times when the system writes data to the mount path.

    libNewProp/mountPath

    The new mount path of the MediaAgent.

    resrvSpaceForSiloRestores

    When the value is set to 0, disables space reservation for SILO restores.

    When the value is set to 1, enables space reservation for SILO restores.

    When the value is set to 2, the existing settings are not altered.

    enablePruningOfAgedData

    When the value is set to 0, disables pruning of aged data.

    When the value is set to 1, enables pruning of aged data.

    When the value is set to 2, the existing settings are not altered.

    useDPSettingsForPruning

    Update this parameter only when the value for enablePruningOfAgedData parameter is set to 1.

    When the value is set to 0, pruning request is sent to any MediaAgent that has access to the library, irrespective of whether the MediaAgent is part of the data path or not.

    When the value is set to 1, the pruning request is sent to only the MediaAgents associated with the data paths in the storage policy copy.

    When the value is set to 2, the existing settings are not altered.

    Example: Use this example XML file to modify the mount path in a library with name "Library1" and MediaAgent name "MA1" from the current path "E:\Library1\Mountpath1" to a new path "\\demo-server\E$\Library1\mountpath1" that can be accessed with the login username "user1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\Edit_MP_Prop.xml

    Click here to see sample output.

What to do next

On successfully editing the mount path, copy content from the older location to the new location.

Editing Disk Library Properties

You can modify the properties of a disk library using XML. 

  1. Download the edit_disk_library_properties.xml file save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the disk library whose property needs to be updated.

    mountPathUsage

    When the value is set to 1, Spill and fill mount paths usage is selected.
    When the value is set to 2, Fill and Spill mount paths usage is selected.

    numOfWritersForLibrary

    When the value is set to -1, the number of writers allocated in the disk library is maximum.

    usePnpWhenBlank

    Specify that blank disks with no other data is used for data protection operations and allows you to use disks exclusively for data protection purposes.

    Valid values are
    0 (disable)
    1 (enable)
    2 (do not change)

    lowWaterMark

    Value in (%) for low watermark warning

    Note: This value should be less than or equal to the warning watermark value (%).

    warningWaterMark

    Value in (%) for warning watermark

    Note: This value should be greater than or equal to the low watermark value (%).

    startDataAgingWhenDataOccupiedOnDiskIs

    Specify the disk capacity in percentage. The data ageing will start when the disk consumption reached the defined percentage.

    preventDataDelFromMntPth

    When the value is set to 0, disables prevention of accidental deletion of the mount path contents.
    When the value is set to 1, enables prevention of accidental deletion of the mount path contents.
    When the value is set to 2, the existing settings are not altered.

    stopDataAgingWhenDataOccupiedOnDiskIs

    Specify the disk capacity in percentage, when reached, data is not aged

    preferMountPathWithFreeSpace

    When the value is set to 1, the system uses the mount path with the most free space available while using the round-robin method to write the data.

    preferMountPathAccordingToMA

    When the value is set to 1, the mount path set as the 'preferred' mount path for the MediaAgent (selected in the Data Path tab of Copy Properties dialog box) is picked for write operations.

    hideLibrary

    When the value is set to 1, the library is hidden and is prevented from being displayed in the CommCell Console.

    Example:

    • Use this example XML file to set the mount path usage as "Spill and fill mount paths" for a library with name "Library1".
    • Use this example XML file to set the number of writers as "5" for a library with name "Library1".
    • Use this example XML file to set the low watermark as "20" and warning watermark as "40" for a library with name "Library1".
  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\edit_disk_library_properties.xml

    Click here to see sample output.

Delete a Mount Path

You can delete mount paths from local drives only.

The mount path is not deleted and you receive an error message if the mount path:

  • contains valid data
  • is used by a deduplication database (DDB)
  • is associated with a Storage Policy that is used as an Incremental Storage Policy for another Storage Policy
  1. Download the delete_mount_path.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    libraryName

    The name of the disk library from which you want to delete the mount path.

    mountPath

    The mount path location that you want to delete.

    opType

    The default value is 16. If you are trying to delete an offline mount path, set the value as 1024.

    Example: Use this example XML file to delete a mount path "E:\Library1\Mountpath1" from a local disk library with name "Library1" and MediaAgent name "MA1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\delete_mount_path.xml

    Click here to see sample output.

Delete a Device Controller on a Disk Device

You can delete a device controller present on a disk device.

  1. Download the delete_device_controller.xml file and save it on the computer where the command is run.
  2. Open the XML file and update the XML parameters listed in the table below:

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent that contains the device controller.

    libraryName

    The name of the library that contains the device controller.

    mountPath

    The mount path location of the device controller.

    Example: Use this example XML file to delete a device controller from the MediaAgent with name "MA1", library with name "Library1" and the mount path location "E:\Library1\Mountpath1" .

  3. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\delete_device_controller.xml

    Click here to see sample output.

Tape Libraries and Stand-Alone Drives

Create a Tape or Stand-Alone Library

The following procedure can be used to detect and configures a tape library or a stand-alone drive.

  1. Download the create_tape_library.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    libraryName

    The name of the new tape library.

    libSerialNumber

    The serial number of the tape library. This value is case-sensitive and must match the actual serial number.

    Example: Use this example XML file to create a tape library with serial number "00000001", library name "Library1" and MediaAgent name "MA1".

    Note: For stand-alone library, libSerialNumber is the tape drive serial number. In that case, the libraryName will be used to set as the new library name.

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\create_tape_library.xml

    Click here to see sample output.

Performing Drive Operations

This procedure handles drive operations such as:

  • Marking  a drive as replaced
  • Marking a drive as cleaned
  • Marking a drive as fixed
  1. Download the mark_drive.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    libraryName

    The name of the tape library.

    driveName

    The name of the drive on which you want to run the operation

    markDrive

    The drive operation that you want to perform. Refer to the table for the values.

    Drive Operation

    Value

    To mark a drive as replaced

    1

    To mark a drive as cleaned

    2

    To mark a drive as fixed

    3

     

    Example: Use this example XML file to mark a drive with name "Drive1" and library name "Library1" as fixed.

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\mark_drive.xml

    Click here to see sample output.

Cloud Libraries

Create a Cloud Library

This procedure creates a cloud library with the specified vendor.

  1. Download the Config-CloudLib.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    libraryName

    The name of the new cloud library.

    baseFolder

    This is an optional attribute. You can specify the name of the base folder or else standard naming convention will be used to name the base folder.

    For more information on the specific parameters required by each vendor, see Vendor Specific XML Parameters.

    Example: Use this example XML file to create an Amazon S3 cloud library with name "Library1", MediaAgent name "MA1", bucket "examplebucket", server type "2", Access Key ID "AKIAIOSFODNN7EXAMPLE" and Secret Access Key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY".

  4. Run the following command from the <software installation directory>\Base folder to execute the xml.

    qoperation execute -af <downloaded location>\Config-CloudLib.xml

Adding a Cloud Device

  1. Download the add_cloud_device.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    deviceName

    The name of the cloud device that you want to use to configure.

    baseFolder

    This is an optional attribute. You can specify the name of the base folder or else standard naming convention will be used to name the base folder.

    deviceAccessType

    Access type Value

    Read 4

    Read and Write 6

    Read and Write, Preferred Access 14

    For more information on the specific parameters required by each vendor, see Vendor Specific XML Parameters.

    Example: Use this example XML file to add a new device "Device1" on an Amazon S3 cloud library with name "Library1", MediaAgent name "MA1", bucket "examplebucket", device type "2", device access type "Read and Write, Preferred Access", Access Key ID "AKIAIOSFODNN7EXAMPLE" and Secret Access Key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY".

  4. Run the following command from the <software installation directory>\Base folder to execute the xml.

    qoperation execute –af add_cloud_device.xml

Adding a New MediaAgent to a Cloud Storage Device

You can use the XML to add a new MediaAgent to a cloud storage device.

  1. Download the add_cloud_device_controller.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the new MediaAgent.

    deviceName

    The name of the cloud storage device.

    baseFolder

    This is an optional attribute. You can specify the name of the base folder or else standard naming convention will be used to name the base folder.

    deviceAccessType

    Access type Value

    Read 4

    Read and Write 6

    Read and Write, Preferred Access 14

    For more information on the specific parameters required by each vendor, see Vendor Specific XML Parameters.

    Example: Use this example XML file to add a new MediaAgent with name "MA1" to a Google device with name "Device1", bucket "examplebucket", device type "19", device access type "Read and Write, Preferred Access", Access Key ID "AKIAIOSFODNN7EXAMPLE" and Secret Access Key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY".

  4. Run the following command from the <software installation directory>\Base folder to execute the xml.

    qoperation execute –af add_cloud_device_controller.xml

Adding a Mount Path to the Cloud Library

You can use two methods to add a mount path to the cloud device.

By Using Cloud Storage Account Credentials

  1. Download the add_cloud_mp_account.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    mediaAgentName

    The name of the MediaAgent.

    libraryName

    The name of the new cloud library.

    For more information on the specific parameters required by each vendor, see Vendor Specific XML Parameters.

    Example: Use this example XML file to add a mount path to an Amazon S3 cloud library with name "Library1", MediaAgent name "MA1", bucket "examplebucket", server type "2", Access Key ID "AKIAIOSFODNN7EXAMPLE" and Secret Access Key "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY".

  4. Run the following command from the <software installation directory>\Base folder to execute the xml.

    qoperation execute –af add_cloud_mp_account.xml

By Using Device Name

  1. Download the add_cloud_mp_device_name.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    deviceName

    The name of the cloud device that you want to use to configure.

    libraryName

    The name of the new cloud library.

    mediaAgentName

    The name of the MediaAgent.

    Example: Use this example XML file to add a mount path to a cloud library with name "Library1", device name "Device1" and MediaAgent name "MA1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute –af add_cloud_mp_device_name.xml

Key Management Server

Adding a Key Management Server

You can use XML to add a key management server.

  1. Download the Add_KMS.xml file and save it on the computer where the command is run.
  2. The following table displays the parameters you can use with the command..

    Attribute

    Description

    Parent Element

    keyProviderName

    The name of the key provider.

    provider

    keyProviderType

    The type of the key provider.

    To add a Safenet or Vormetric key management server, set the value to KMIP.

    To add an AWS key management server, set the value to AWS_KMS.

    To add a passphrase key management server, set the value to PASSPHRASE.

    keyProvider

    encryptionKeyLength

    The key length to use with the AES cipher.

    The following are the supported key lengths for AES cipher:

    • 128
    • 256

    keyProvider

    host

    The IP address or hostname of the third-party key management server. In case of a cluster server, specify the host values of all servers separated with a comma during command execution.

    Note: For CommCell migration, make sure that both the source and the destination CommCells are pointing to the same third-party key management server.

    properties

    port

    The port used by the key management server.

    In case of a cluster server, all servers should use the same port.

    properties

    certFilePath

    The location of the client certificate.

    Example: C:\Certificates\client.crt (for Salefent) and C:\Certificates\client.pem (for Vormetric)

    properties

    sslPassPhrase

    The passphrase of the certificate if set.

    properties

    keyFilePath

    The location of the client certificate key.

    Example: C:\Certificates\clientkey (for Safenet) and C:\Certificates\client_private.pem (for Vormetric)

    properties

    caCertFilePath

    The location of the key management server CA certificate.

    Example: C:\Certificates\Local_CA.crt (for Safenet) and C:\Certificates\1.2.3.4_CA.pem (for Vormetric)

    properties

    regionName

    The region where AWS hosts the Key Management Service.

    properties

    userName

    The AWS Access Key.

    userAccount

    password

    The AWS Secret Access Key.

    userAccount

    passphrase

    The passphrase for the passphrase key management server.

    properties

    clientName

    The name of the client to store the passphrase file for a passphrase key management server.

    client

    path

    The location to export the passphrase file for a passphrase key management server.

    filePath

  3. To add a Safenet or Vormetric key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName xxxxx -keyProviderType KMIP -encryptionKeyLength xxx -sslPassPhrase xxx -host xxx -port xxxx -certFilePath xxx -keyFilePath xxx -caCertFilePath xxx

    Example:

    Execute the following command to add a Safenet key management server with key provider name "Safenet", provider type "KMIP", encryption key length "128", passphrase "sslphrase!12", host "172.19.119.222", port "9002", client certificate location "C:\Certificates\client.crt". client certificate key location "C:\Certificates\clientkey", and key management server CA certificate location "C:\Certificates\Local_CA.crt".

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName Safenet -keyProviderType KMIP -encryptionKeyLength 128 -sslPassPhrase sslphrase!12 -host 172.19.119.222 -port 9002 -certFilePath C:\Certificates\client.crt -keyFilePath C:\Certificates\clientkey -caCertFilePath C:\Certificates\Local_CA.crt

  4. To add an AWS key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName xxxxx -keyProviderType AWS_KMS -regionName xxxx -userName xxxx -password xxxx

    Example:

    Execute the following command to add an AWS key management server with key provider name "AWS", provider type "AWS_KMS", region name "Asia Pacific (Mumbai)", Access Key "accesskey", and Secret Access Key "secretkey":

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName AWS -keyProviderType AWS_KMS -regionName 'Asia Pacific (Mumbai)' -userName accesskey -password secretkey

  5. To add a passphrase key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName xxxxx -keyProviderType PASSPHRASE -encryptionKeyLength xxx –passphrase xxx –passphraseClient/client/clientName xxx -passphraseClient/filePath/path xxxx

    Example:

    Execute the following command to add a passphrase key management server with key provider name "PassphraseKMS", provider type "PASSPHRASE", encryption key length "128", passphrase "demo passphrase", client name "client1", and passphrase file location "C:\Passphrase".

    qoperation execute -af c:\Xmls\Add_KMS.xml -keyProviderName PassphraseKMS -keyProviderType PASSPHRASE -encryptionKeyLength 128 –passphrase “demo passphrase” –passphraseClient/client/clientName client1 -passphraseClient/filePath/path c:\Passphrase

          Click here to see sample output.

Associating Storage Policy Copies to a Key Management Server

You can use XML to associate one or more storage policy copies to a key management server.

  1. Download the Associate_Copies_to_KMS.xml file and save it on the computer where the command is run.
  2. The following table displays the parameters you can use with the command.

    Attribute

    Description

    Parent element

    copyName

    The name of the storage policy copy.

    StoragePolicyCopy

    storagePolicyName

    The name of the storage policy.

    StoragePolicyCopy

    keyProviderName

    The name of the key provider.

    A copy is associated with Commvault key management server by default. You can associate the copy to a third-party key management server. You can also change the association from one third-party to another third-party key management server. However, to change the association from a third-party key management server to the default Commvault server, you require an authorization code to perform the operation.

    dataEncryption

    rotateMasterKey

    Used to rotate the master key.

    The value is set to 1 by default. Do not change the value.

    dataEncryption

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

    qoperation execute -af <downloaded location>\Associate_Copies_to_KMS.xml -copyName xxxxx -storagePolicyName xxxx -keyProviderName xxx

    Example:

    Execute the following command to associate a storage policy copy with name "Copy1" and storage policy "SP1" with the key provider "Safenet":

    qoperation execute -af <downloaded location>\Associate_Copies_to_KMS.xml -copyName Copy1 -storagePolicyName SP1 -keyProviderName Safenet

         Click here to see sample output.

Rotating Master Key for a Storage Policy Copy

You can use XML to rotate the master key of a storage policy copy. This operation revokes current master key and generates a new master key with the key management server. The RSA public key and the RSA private key remain the same after key rotation. So, the old jobs that are encrypted with the previous master key can be decrypted.

The new master key is used only to decrypt the RSA private key during when restore and auxiliary copy operations.

  1. Download the Rotate_MasterKey.xml file and save it on the computer where the command is run.
  2. The following table displays the parameters you can use with the command.

    Attribute

    Description

    Parent element

    copyName

    The name of the storage policy copy.

    StoragePolicyCopy

    storagePolicyName

    The name of the storage policy.

    StoragePolicyCopy

    rotateMasterKey

    Used to rotate the master key.

    The value is set to 1 by default. Do not change the value.

    dataEncryption

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

    qoperation execute -af <downloaded location>\Rotate_MasterKey.xml -copyName xxxxx -storagePolicyName xxxx

    Example:

    Execute the following command to rotate master key for a storage policy copy with name "Copy1" and storage policy "SP1":

    qoperation execute -af <downloaded location>\Rotate_MasterKey.xml -copyName Copy1 -storagePolicyName SP1

          Click here to see sample output.

Deleting a Key Management Server

You can use XML to delete a key management server. You cannot delete a key management server to which a storage policy copy is associated.

  1. Download the Delete_KMS.xml file and save it on the computer where the command is run.
  2. The following table displays the parameters you can use with the command.

    Attribute

    Description

    keyProviderName

    The name of the key provider for the key management server.

  3. Execute the following command from the <software_installation_directory>/Base folder after substituting the parameter value.

    qoperation execute -af <downloaded location>\Delete_KMS.xml -keyProviderName xxx

    Example:

    Execute the following command to delete a key management server with key provider "Safenet":

    qoperation execute -af <downloaded location>\Delete_KMS.xml -keyProviderName Safenet

          Click here to see sample output.

Listing the Key Management Servers

You can use XML to list the key management servers configured on the CommServe.

  1. Download the List_KMS.xml file and save it on the computer where the command is run.
  2. From the <software installation directory>\Base folder, run the following command:

    qoperation execute -af <downloaded location>\List_KMS.xml

          Click here to see sample output.

Modifying the Properties of a Key Management Server

You can use XML to modify the properties of a key management server.

  1. Download the Modify_KMS.xml file and save it on the computer where the command is run.
  2. The following table displays the parameters you can use with the command.

    Attribute

    Description

    Parent Element

    keyProviderName

    The name of the key provider.

    provider

    encryptionKeyLength

    The key length to use with the AES cipher. The following are the supported key lengths for AES cipher:

    • 128
    • 256

    keyProvider

    configurationFilePath

    The location of the KMIPServers_Template.ini file.

    We recommend to not use this configuration file. You can apply the values that are present in the KMIPServers_Template.ini file in the below parameters under the properties parent of this XML file.

    properties

    host

    The IP address or hostname of the third-party key management server. In case of a cluster server, add the host values of all servers separated with a comma.

    Note: For CommCell migration, make sure that both the source and the destination CommCells are pointing to the same third-party key management server.

    properties

    port

    The port used by the key management server.

    In case of a cluster server, all servers should use the same port.

    properties

    certFilePath

    The location of the client certificate.

    Example: C:\Certificates\client.crt (for Salefent) and C:\Certificates\client.pem (for Vormetric)

    properties

    sslPassPhrase

    The passphrase of the certificate if set.

    properties

    keyFilePath

    The location of the client certificate key.

    Example: C:\Certificates\clientkey (for Safenet) and C:\Certificates\client_private.pem (for Vormetric)

    properties

    caCertFilePath

    The location of the key management server CA certificate.

    Example: C:\Certificates\Local_CA.crt (for Safenet) and C:\Certificates\1.2.3.4_CA.pem (for Vormetric)

    properties

    userName

    The AWS Access Key.

    userAccount

    password

    The AWS Secret Access Key.

    userAccount

    passphrase

    The passphrase for the passphrase key management server.

    properties

    clientName

    The name of the client to store the passphrase file for a passphrase key management server.

    client

    path

    The location to export the passphrase file for a passphrase key management server.

    filePath

    newKeyProviderName

    The new name for the key provider.

    App_ModifyEncKeyProviderReq

  3. To modify a Safenet or Vormetric key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName xxxxx -encryptionKeyLength xxx -sslPassPhrase xxx -host xxx -port xxxx -certFilePath xxx -keyFilePath xxx -caCertFilePath xxx

    Example:

    Execute the following command to modify the properties of a key management server with key provider name "Safenet" as encryption key length "128", passphrase "sslphrase!12", host "172.19.119.222", port "9002", client certificate location "C:\Certificates\client.pem". client certificate key location "C:\Certificates\client_private.pem", key management server CA certificate location "C:\Certificates\1.2.3.4_CA.pem", and new key provider name "Vormetric":

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName Safenet -encryptionKeyLength 128 -sslPassPhrase sslphrase!12 -host 172.19.119.222 -port 9002 -certFilePath C:\Certificates\client.pem -keyFilePath C:\Certificates\client_private.pem -caCertFilePath C:\Certificates\1.2.3.4_CA.pem -newKeyProviderName Vormetric

  4. To modify an AWS key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName xxxxx -regionName xxxx -userName xxxx -password xxxx -newKeyProviderName xxxx

    Example:

    Execute the following command to modify the properties of a key management server with key provider name "AWS" as region name "Asia Pacific (Mumbai)", Access Key "accesskey", Secret Access Key "secretkey", and new key provider name "AWS_Modified":

    qoperation execute -af <downloaded location>\Add_KMS.xml -keyProviderName AWS -keyProviderType AWS_KMS -regionName 'Asia Pacific (Mumbai)' -userName accesskey -password secretkey -newKeyProviderName AWS_Modified

  5. To modify the passphrase for a passphrase key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName xxx -–oldPassphrase xxx –passphrase xxx –rotatePassphrase true

    Example:

    Execute the following command to modify the passphrase of a passphrase key management server with key provider name "PassphraseKMS", old passphrase "demo passphrase", and new passphrase "new demo passphrase".

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName PassphraseKMS -–oldPassphrase "demo passphrase" –passphrase "new demo passphrase" –rotatePassphrase true

  6. To modify the export location of the passphrase file for a passphrase key management server, execute the following command from the <software_installation_directory>/Base folder after substituting the parameter values:

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName xxx –passphraseClient/client/clientName xxx -passphraseClient/filePath/path xxx

    Example:

    Execute the following command to modify the export location of the passphrase file for a passphrase key management server with key provider name "PassphraseKMS", new client name "client2", and export location on new client “d:\Passphrase”.

    qoperation execute -af <downloaded location>\Modify_KMS.xml -keyProviderName PassphraseKMS –passphraseClient/client/clientName client2 -passphraseClient/filePath/path d:\Passphrase

Click here to see sample output.

Enable or Disable Client Side Deduplication

  1. Download the client_deduplication.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameters.

    Attribute

    Description

    clientName

    The name of the client computer as it appears in the CommCell Browser.

    For example: If you want to enable source-side deduplication to client1 and client2, then you must add the following:

    <entity>
    <clientName>client1</clientName>
    </entity>
    <entity>
    <clientName>client2</clientName>
    </entity>

    enableClientSideDiskCache

    Option to enable or disable source-side disk cache.

    Valid values are true or false.

    maxCacheDb

    Specifies the maximum size in MB for source-side disk cache.

    Valid values are 1024 - 131072 MB.

    enableVariableContentAlignment

    Option to enable or disable the variable content alignment.

    Valid values are true or false.

    clientSideDeduplication

    Option to enable or disable client side deduplication.

    Valid values are:

    OFF: Disable client side deduplication

    ON_CLIENT: Enable client side deduplication

    USE_SPSETTINGS: Use storage policy settings

    Example: Use this example XML file to enable client side deduplication, disable source-side disk cache, disable variable content alignment and set the maximum size of source-side disk cache to "2048MB" for a client with name "Client1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute –af client_deduplication.xml

    Click here to see sample output.

Delete a Library

  1. Download the delete_library.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameter.

    Attribute

    Description

    libraryName

    The name of the library that you want to delete.

    Example: Use this example XML file to delete a tape library with name "Library1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\delete_library.xml

    Click here to see sample output.

Deconfigure MediaAgent from a Tape Library

  1. Download the deconfigure_MA_tape_library.xml file and save it on the computer where the command is run.
  2. Open the XML file.
  3. Change the XML parameter.

    Attribute

    Description

    libraryName

    The name of the tape library

    mediaAgentName

    The name of the MediaAgent which you want to deconfigure from the tape library

    Example: Use this example XML file to deconfigure a MediaAgent with name "MA1" from a tape library with name "Library1".

  4. Run the following command from the <software installation directory>\Base folder.

    qoperation execute -af <downloaded location>\deconfigure_MA_tape_library.xml

    Click here to see sample output.

Last modified: 1/3/2018 8:47:48 PM