CLI Reference

Overview

Every node provides CLI that can be used to manage configuration and invoke tasks on Storware Backup & Recovery Node. All of the commands are executed using vprotect command. The general syntax is as shown below:

[root@vProtect3 ~]# vprotect
usage: vprotect <COMMAND> -<ARG_1> ... -<ARG_N>
COMMAND is one of the following:
 node                   Node management
 config                     Node configuration management
 hv                         Hypervisor management
 hvm                        Hypervisor manager management
 hc                         Hypervisor cluster management
 hs                         Hypervisor storage management
 vm                         Virtual machine management
 vmpolicy                   VM backup policy management
 bd                         Backup destination management
 sched                      Schedule management
 brvm                       VM backup & restore
 st                         Storage management
 stpool                     Storage pool management
 stprovider                  Storage provider management
 brapp                      Application backup & restore
 mnt                        Mounted backup management
 task                       Task management
 login                      User login
 logout                     Node and user logout
 stop                       Safely stops node
 vm-snappolicy              Snapshot policy management for VMs
 storage-snappolicy          Snapshot policy management for storages
 app                        Application backup management
 appconf                    App command execution management
 apppolicy                  Application backup policy management
 restorejob                  Restore jobs
 recplan                    Recovery plan policies
 brst                       Storage backup & restore
 quota                      Quota management
 project                    Project management
 user                       User management
 rbac                       Rbac management
 role                       AppUser Role management
 group                      AppUser Group management
 status                     Shows node status
 start                      Starts node

Starting and stopping node

  • To check if Storware Backup & Recovery Node is running, run:

    or

  • To start Storware Backup & Recovery Node run:

    or

  • To safely stop Storware Backup & Recovery Node (this command waits for all tasks to be canceled, so that temporary objects are cleaned up) run:

    or

  • In emergency cases you may need to kill the engine without task clean up - get PID of the node by running:

    and kill process using:

User login

  • To log in to CLI use the following command:

where USER_NAME is your admin account in Storware Backup & Recovery. You will be prompted for a password. From this moment you are able to execute commands.

  • Once you completed working with CLI, you can log out by running:

Note about GUIDs

All of the commands require GUID of the object that you want to refer to in the command. GUID is found in the first column of typical list command, e.g.:

  1. Let's list VMs and get VM GUID:

  2. Now let's show details of the VM:

Note: that UUID is the ID used by the hypervisor or HV manager, while GUID is the ID used by Storware Backup & Recovery to uniquely identify objects.

Node GUID can be replaced by this keyword to state that action such as restore or mount is going to be run on the node where the command is executed from. For instance, to restore or backup with given GUID on current node to /vprotect_data:

Similarly, backup destinations can be referred to by names. So a backup of some VM with given GUID to backup destination with name ISP can be done like this:

Nodes

To list or register node use vprotect node sub-command:

Examples

  • To list all nodes registered

  • Example node registration

  • You may need to re-register a node if Storware Backup & RecoveryServer address changes

Node configurations

Use vprotect config sub-command add/remove backup destinations from node config, list, or show details of node configs.

Setting up parameters for node configuration

In general vprotect config -s <GUID> <PROPERTY_NO.> <VALUE> the command sets the value of a property with the given number of node configurations with GUID. Property numbers are returned in a detailed view of each node configuration. After you create node configuration, show default values with -g. Then use property numbers (the first number in the property/value line of the detailed view).

Examples

  • To list all node configurations

  • To show details of the given node config (by GUID)

  • To add backup destination (second GUID) to the given node configuration (first GUID):

    More backup destinations can be added by separating GUIDs with commas.

Backup destinations

The backup destination management module is used to add and remove a backup destination (a backup provider instance with retention settings). A backup destination must be assigned to a group for the scheduler to know where to put backups during automatic backup. For on-demand backup, you just need to specify which backup destination should be used.

Backup destinations are assigned to the node configuration. This means that nodes using such configuration are configured to store backups in the selected backup destinations.

Note: that the backup task will fail if it is not able to assign a node because the given BD is not assigned to the node config of the node that is required to be used for the given hypervisor.

To manage backup destinations in the system used vprotect bd sub-command.

Setting up parameters for backup destinations

In general vprotect bd -s <GUID> <PROPERTY_NO.> <VALUE> command sets value of property with the given number of BD with GUID. Property numbers are returned in detailed view of each BD (fields obviously are different for each backup provider). After you create backup destination, show default values with -g. Then use property numbers (first number in the property/value line of the detailed view).

Retention time settings are interpreted in days (just give a number without any additional suffixes).

There are however some mode/type fields that require a string to be typed in the correct format:

  1. Amazon S3 - Backup mode - must be either:

    • SINGLE_BUCKET - single bucket for all VMs

    • ONE_BUCKET_PER_VM - separate bucket for each VM (note that default limit is 100 buckets in Amazon S3)

  2. Swift - Auth method - authentication method used to authenticate Swift BD:

    • BASIC

    • TEMPAUTH

    • KEYSTONE

  3. Time zones must be specified in the format shown in this table: List of tz database time zones​

Examples

  • To list all backup destinations

  • To show details of the given HV manager (by GUID) - note that each BD has a different set of fields - numbers at the beginning of a line indicate an identifier of a field you want to set from CLI:

  • Remember that to use a BD you need to create a new entry of a given type and then configure its properties (example for IBM Spectrum Protect [ISP], assume that GUID returned by the first command was bb74ef6c-f6de-4783-bfa7-70fc2376fb08 ):

    Now set the properties:

    • retention - full - 4 versions / 30 days

    • retention - incremental - 28 versions / 30 days

    • ISP node name

    • ISP node password

    • ISP server time zone

HV managers (oVirt/RHV/Oracle VM/Nutanix/Kubernetes)

Hypervisor manager management module is used to add, remove hypervisor managers (currently only oVirt and RHV managers) and invoke indexing task. Indexing tasks gathers information about hypervisors and VMs running in the managed environment and updates their location if the VM has been moved to the different hypervisor.

To manage HV managers in the system usedvprotect hvm sub-command.

Note: that if you're using RHV/oVirt/Oracle VM/Nutanix/Kubernetes then hypervisors will be detected automatically as a part of the index task. So there is no need to define every hypervisor manually as they will be detected automatically.

Examples

  • To list all hypervisor managers

  • To show details of the given HV manager (by GUID)

  • To index VMs and hypervisors on the given HV manager:

  • To create a HV manager you need to execute the following commands:

    • Create HV manger entry with given type:

    • Use GUID returned to set credentials:

    • By default current node configuration is used for created HV manager - you may change it with this command (first HV GUID, then node configuration GUID):

      Hypervisors connected to the HV manager will have node configuration of the HV manager assigned by default. For backup export always node configuration assigned to the HV is used.

Hypervisors

The Hypervisor management module is used to add, remove hypervisors and invoke indexing tasks. Indexing tasks gather information about VMs running on the hypervisor and update their location if the VM has been moved within the pool.

To manage hypervisors in the system used vprotect hv sub-command.

Note: that if you're using RHV/oVirt/Oracle VM then hypervisors will be detected automatically as a part of the index task. So there is no need to define OVM hypervisors and for RHV/oVirt KVM hosts will be detected automatically.

Examples

  • To list all hypervisors

  • To show details of the given hypervisor (by GUID)

  • To index VMs on the given HV:

  • To create a hypervisor you need to execute the following commands:

    • Create HV entry with given type:

    • Use GUID returned to set credentials:

    • By default current node configuration is used for created hypervisor - you may change it with this command (first HV GUID, then node configuration GUID):

Hypervisor clusters

Hypervisor clusters management module enables you to view and remove clusters detected on RHV/oVirt/Nutanix/OVM/XenServer environments.

To view or delete them use vprotect hc sub-command.

Examples

  • To list all detected clusters:

  • To delete a cluster with GUID 107bc87a-9adf-4d6c-b732-345dd06c59e9:

Hypervisor storage

Hypervisor storage management module enables you to view and remove storage detected on RHV/oVirt/Nutanix/OVM/XenServer environments. You can select storage in the restore dialog box for XenServer/Nutanix and RHV/oVirt (v4) platforms.

To view or delete them used vprotect hs sub-command.

Examples

  • To list all detected storage volumes:

  • To delete a storage volume with GUID 6b5aa45a-5436-47cd-82ce-1c4250742323:

Virtual machines

The Virtual machine management module is used to provide information about VMs that has been detected on hypervisors, report the status of the last backup of your VMs (and all backups for a particular VM) and set priority for operations invoked on VM.

To manage VMs in the system used vprotect vm sub-command.

VMs are detected automatically during Index tasks executed on the HV or HV manager.

Examples

  • To list all VMs

  • To show details of the given VM (by GUID)

  • To add VM (first GUID) to the given policy (second GUID):

  • To show backup history of a VM with given GUID:

  • To create snapshot of a VM with given GUID (VM must have snapshot policy already assigned):

Storage backup management

This module is responsible for managing storage instances and actions related to backups/schedules/policies etc.

Examples

Storage pool management

This small module allows us to list and deleting inventoried storage pools.

Examples

To list storage pools

Storage providers management

This module is responsible for managing the storage provider's infrastructure. So performing tasks such as adding/removing / inventorying, etc.

Examples

VM backup policies

Virtual machine backup policies management module is used to define backup policies of VMs. You can assign different backup priorities for a policy when the scheduler invokes a backup task. You need first to define a VM policy and then add VMs to it. VM can belong only to a single backup policy.

To manage VM policies in the system use vprotect vmpolicy sub-command.

VMs are assigned automatically to the policy only if VM has no policy assigned already. If an automatic assignment has been turned on for a policy and either name of the VM matches the regular expression, or tag-detected (Citrix/oVirt/RHV/Oracle VM) matches tag defined for the policy, VM is assigned to the policy, and all schedules for a policy will also be automatically invoked for this VM.

Note: it is important to assign a backup destination for a policy (required for a node to know where to store backups)

Examples

  • To list all VM policies

  • To show details of the given VM (by GUID)

  • To create a new policy

  • To add policy1 tag (include) for a policy:

  • To remove policy1 tag (include) for a policy:

  • To set 2 schedules (GUIDs are comma-separated) for a policy (first GUID):

  • To set backup destination (you can use name or GUID) for a policy (first GUID):

Snapshot management policies for VMs

The snapshot management policies module enables CDM for your VMs and manages their retention. Currently, it is supported for KVM, Citrix, RHV/oVirt/OLVM platforms.

To manage snapshot policies for VMs in the system use vprotect vm-snappolicy sub-command.

VMs are assigned automatically to the policy only if VM has no policy assigned already. If an automatic assignment has been turned on for a policy and either name of the VM matches a regular expression, or tag-detected (Citrix/RHV/oVirt/OLVM) matches tag defined for the policy, VM is assigned to the policy, and all schedules for a policy will also be automatically invoked for this VM.

Note: only VMs with assigned snapshot management policy can be a snapshot from the CLI or UI

Examples

  • To list all snapshot policies

  • To show details of the given VM (by GUID)

  • To create a new policy

  • To add policy1 tag (include) for a policy:

  • To remove policy1 tag (include) for a policy:

  • To set 2 schedules (GUIDs are comma-separated) for a policy (first GUID):

Snapshot management policies for storage

To manage snapshot policies for storage in the system used vprotect storage-snappolicy sub-command.

Storages are assigned automatically to the policy only if storage has no policy assigned already. If an automatic assignment has been turned on for a policy and the name of the storage matches the regular expression, storage is assigned to the policy, and all schedules for a policy will also be automatically invoked for this storage.

Note: only storage with an assigned snapshot management policy can be a snapshot from the CLI or UI

Examples

To list all snapshot policies

  • To show details of the given snapshot policy (by GUID)

  • To create a new policy

  • To set 2 schedules (GUIDs are comma-separated) for a policy (first GUID):

Schedules

The schedule management module is used to create schedules associated with VMs or groups of VMs. Each schedule defines the days of a week and the hour when the backup tasks should be invoked. Each schedule also defines a time window in which the backup process must start. If the task queue is full and the tasks start after the specified amount of time from the schedule – it will be canceled and marked as failed.

Note:

  • tasks in the queue are run in order from the highest to the lowest priority.

  • you can assign multiple schedules if you need backup to be executed at different hours on different days

  • remember always to assign schedules to VM or VM group – schedule can be assigned only to a single VM or VM group

To manage schedules in the system used vprotect sched sub-command.

Examples

  • To list all schedules

  • To create a full virtual machine backup schedule with a name Schedule1 executed every day at 05:00 with 60 minutes of time window:

  • To create an incremental virtual machine backup schedule with a name Schedule2 executed every Monday, Wednesday and Friday at 17:00 with 90 minutes of time window:

Note: that days of the week are given as a single comma-separated string of short (3-letter) weekday names

  • To disable a schedule with GUID 6651787d-9a55-421d-8158-ead80a70a9cb:

VM backup/restore

This module is used to manage the backup and restore processes. It is also used to list backups of a particular VM.

To invoke backup and restore tasks use vprotect brvm sub-command.

Examples

  • To list all backups and their status:

  • To show backups of a particular VM:

  • To show files that a specific backup consists of:

  • To show detected file systems in specific backup:

  • To create a full backup of a VM and store it in backup destination set to rule called MyTSM

  • To restore a full backup with given GUID on the current node (this) to the /vprotect_data

  • To create an incremental backup (Citrix only) of a VM and store it in backup destination called MyTSM

  • To restore VM backup (first GUID) to the hypervisor (second GUID - Citrix XenServer only) and specific storage

Storage backup/restore

This module is used to manage the backup and restore process of storage providers.

To invoke backup and restore tasks use vprotect brst sub-command.

Examples

  • To list all backups and their status:

  • To show backups of a particular storage:

  • To show files that a specific backup consists of:

  • To create a full backup of a storage and store it in backup destination called MyTSM

  • To restore a full backup with given GUID on the current node (this) to the /vprotect_data

  • To create an incremental backup of a storage and store it in backup destination called MyTSM

Mounted backups

The Mounted backup management module is used to mount and unmounts backups on the given node. This feature is currently supported for RHV/oVirt/OVM VMs. Each mounted backup can be mounted automatically (auto-detection of mount points within a single root or manually with separate mount points for each volume.

To invoke mount/unmount tasks use vprotect mnt sub-command.

Examples

  • To list all mounted backups:

  • To list all mounted files used by mounted backup with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95 (note that this is mounted backup GUID not a backup GUID):

  • To show detected file systems in specific backup:

  • To mount all file systems in backup with GUID 2132182d-e9ab-4478-a1db-48222b0e515b and node config with GUID 3a9d48dc-e48f-11eb-a1ce-005056a6b7e5 to /mnt/myVM/2017-01-01:

  • To mount manually file systems in backup with GUID 2132182d-e9ab-4478-a1db-48222b0e515b with specifying mount points you need to provide semicolon-separated list where you provide name of the volume=mount point (white space before or after semicolon or equal sign is not allowed)

  • To unmount mounted backup with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95:

Tasks

The Task Management module is used to show and cancel tasks being executed. You can also monitor the progress of the tasks.

Note:

  • tasks in the queue are run in order from the highest to the lowest priority.

  • the queue is being periodically cleaned, so only the last tasks are being shown

To manage tasks use vprotect task sub-command.

Examples

  • To list tasks assigned to the current node:

  • To list all tasks in the system:

  • To show task details:

  • To cancel the task with ID 091d623d-edea-490f-8b3b-da30c09a3f93:

Note: some tasks may need to be finished before they are cancelled, for example export VM from the hypervisor – after cancellation it may take some time for the task to process the cancel request and clean up the snapshots etc. If necessary, the backup will be marked as failed.

Project

The Project module is used to view details and set a quota for available projects.

Examples

  • To list all projects:

  • To set quota with GUID 6f0bfb3c-24dd-4d12-8a72-997ded2ecc98 to project with GUID ca707d31-f403-40d5-b160-6ac512457b87

User Management

The User module is used to manage users and their settings. You can add or remove users, change their password or timezone.

Examples

  • To create a new user

  • To list all users

  • To set password for the user

Quota

Quota management module is used to manage backup/restore limits for virtual machines in projects.

To manage Quotas in the system use vprotect quota sub-command.

Examples

  • To list all quotas:

  • To list all projects for Quota with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95:

  • To list all possible rule names:

  • To add rule to Quota with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95:

RBAC

This module allows listing possible context types and privilege types used in RBAC management.

This module uses vprotect rbac sub-command.

Examples

  • To list all possible privilege types

User Role Management

The User Role management module is used to manage Roles and their privileges.

Note: only rules that are created by the user can be deleted.

To manage User Roles in the system use vprotect role sub-command.

Examples

  • To create a new Role

  • To add VE_INSTANCE_READ privilege to a Role with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95

User Group Management

+User Group management module is used to bind Users with a set of Roles.

Note: only groups that are created by the user can be deleted.

To manage User Roles in the system use vprotect group sub-command.

Examples

  • To add Role with GUID 1ac068d3-4848-4c98-b30b-54ce050b6a95 to Group with GUID 54c57989-9d99-480f-a6da-b4f34b7bd812

  • To remove User with GUID 91e6bf9c-59c6-4653-9854-e9c920198343 from Group with GUID 54c57989-9d99-480f-a6da-b4f34b7bd812

Application backup/restore

This module is used to manage tge backup and restore process. It is also used to list backups of a particular application.

To invoke backup and restore tasks use vprotect brapp sub-command.

Examples

  • To list all backups and their status:

  • To show backups of a particular VM:

  • To show files that a specific backup consists of:

  • To create a full backup of a app and store it in backup destination called MyTSM

  • To restore a full backup with given GUID on the current node (this) to the /vprotect_data

  • To restore application backup (first GUID) to the other application (assuming it has REMOTE_SSH in Command Execution Configuration - second GUID)

Applications

The Application management module is used to provide information about apps that have been defined report the status of the last backup of your apps (and all backups for a particular app).

To manage Applications in the system used vprotect app sub-command.

Examples

  • To list all Applications

  • To show details of the given Application (by GUID)

  • To add Application (first GUID) to the given policy (second GUID):

  • To show backup history of a VM with given GUID:

Application backup policies

Application backup policies management module is used to define backup policies for Applications. You can assign different backup priorities for a policy when the scheduler invokes a backup task. You need first to define the application backup policy and then add Applications to it. The Application can belong only to a single backup policy.

To manage Application policies in the system used vprotect apppolicy sub-command.

Note: it is important to assign a backup destination for a policy (required for a node to know where to store backups)

Application backup policies are supposed to have multiple rules (but currently vProtect supports exactly 1 rule). Rule specifies schedules and backup destinations for the policies.

Examples

  • To list all application backup policies

  • To show details of the given application (by GUID)

  • To create a new policy

  • To set backup destination for a policy:

Application command execution management

Application command execution management module is used to define command execution for application. You can assign application to command definition or show details of command config. As you can see in the module syntax, you can do much more and we will show such operations in examples.

Examples

  • To list all command configs:

  • To see command config details:

Restore Jobs

You can use this small module to list restore job operations and see the details of every task.

Examples

  • To list restore jobs:

  • To see restore job details:

Recovery plans policies

The Recovery plans policies module is used to define recovery plans policies and rules for VMs. You can assign different restore priorities for a policy when the scheduler invokes the restore task. You need first to create a new policy and then add new rules to it.

Examples

  • To create new policy:

  • To add new rule to selected policy:

  • To list policies:

  • To list rules assigned to policy:

  • To select the virtual machine you want to restore using a rule :

PreviousUpgradeNextCLI v2 Reference