Skip to main content
Pure1 Support Portal

purepgroup

Name

purepgroup, purepgroup-create, purepgroup-copy, purepgroup-destroy, purepgroup-eradicate, purepgroup-recover, purepgroup-rename, purepgroup-snap — manage the creation and deletion of the Purity protection group (pgroup) objects.

Synopsis

purepgroup copy [ --overwrite ] SOURCE DEST

purepgroup create [ --hgrouplist HGROUPS | --hostlist HOSTS | --vollist VOLS ] [--targetlist TARGETS] PGROUP...

purepgroup destroy PGROUP...

purepgroup eradicate PGROUP...

purepgroup recover PGROUP...

purepgroup rename OLD-NAME NEW-NAME

purepgroup snap [--apply-retention] [ --replicate-now | --replicate ] [--suffix SUFFIX] PGROUP...

Arguments

PGROUP

Protection group or protection group snapshot to be created, destroyed, eradicated, or recovered. For purepgroup snap, protection group to be snapped.

SOURCE

Protection group or protection group snapshot from where data is copied. The data is copied to the DEST protection group.

DEST

Protection group to where data is copied. The data is copied from the SOURCE protection group or protection group snapshot.

OLD-NAME

Name of the protection group to be renamed.

NEW-NAME

Name by which the protection group is to be known after the command executes.

Options

-h | --help

Can be used with any command or subcommand to display a brief syntax description.

--apply-retention

Applies the retention schedule settings to the snapshot.

--hgrouplist

Comma-separated list of one or more host groups to be included in the specified protection groups.

--hostlist

Comma-separated list of one or more hosts to be included in the specified protection groups.

--overwrite

Allows purepgroup copy to overwrite existing volumes. Without this option, if the DEST protection group already contains volumes with matching names, then the command fails. With this option, if the DEST protection group exists, then the SOURCE and DEST protection groups must contain the same volumes (volume names).

--replicate, --replicate-now

Replicates the snapshot to all target arrays that have allowed replication.

--suffix

Specifies a name suffix for the snapshots created. Specifying this option causes snapshots to have names of the form PGROUP.SUFFIX rather than the default PGROUP.NNN form. The names of all snapshots created by a single command that specifies this option have the same suffix.

--targetlist

Comma-separated list of one or more target arrays to be included in the specified protection groups. The target arrays receive the replicated snapshots.

--vollist

Comma-separated list of one or more volumes to be included in the specified protection groups.

Conventions

Object Names

Valid characters are letters (A-Z and a-z), digits (0-9), and the hyphen (-) character. Volume names may also include the underscore (_) character. The first and last characters of a name must be alphanumeric, and a name must contain at least one letter.

Most objects in Purity that can be named, including host groups, hosts, volumes, protection groups, volume and protection group suffixes, SNMP managers, and subnets may be 1-63 characters in length.

Array names may be 1-56 characters in length. The array name length is limited to 56 characters so that the names of the individual controllers, which are assigned by Purity based on the array name, do not exceed the maximum allowed by DNS.

Names are case-insensitive on input. For example, vol1, Vol1, and VOL1 all represent the same volume. Purity displays names in the case in which they were specified when created or renamed.

Protection Group Snapshot Names

The protection group snapshot naming convention is PGROUP.NNN, where:

  • PGROUP is the name of the protection group.

  • NNN is a unique monotonically increasing number or a manually-assigned protection group snapshot suffix name.

The protection group volume snapshot naming convention is PGROUP.NNN.VOL, where:

  • PGROUP is the name of the protection group.

  • NNN is a unique monotonically increasing number or a manually-assigned protection group snapshot suffix name.

  • VOL is name of the volume member.

If you are viewing replicated snapshots on a target array, the snapshot name begins with the name of the source array from where the snapshot was taken.

Description

A protection group defines a set of volumes, hosts, or host groups (called members) that are protected together through snapshots with point-in-time consistency across the member volumes. The members within the protection group have common data protection requirements and share the same snapshot, replication, and retention schedules.

A single protection group can consist of multiple hosts, host groups, and volumes. Likewise, hosts, host groups, and volumes can be associated with multiple protection groups.

Protection group snapshots capture the content of all volumes on the source array for the specified protection group at a single point in time. The snapshot is an immutable image of the volume data at that instance in time. The volumes are either direct members of the protection group or connected to any of its hosts or host groups within a protection group.

Protection group snapshots cannot be connected to host groups or hosts for writing and reading. However, the volumes within a protection group snapshot, which are visible in both the Storage and Protection tabs, can be copied to new or existing live, host-accessible volumes.

Protection group snapshots can be saved locally or replicated from the source array to a target array.

Creating Protection Groups

Run purepgroup create on the source array (source) to create a new protection group.

Include the --hostlist, --hgrouplist, or --vollist option to add hosts, host groups, or volumes, respectively, as members to the protection group. Only members of the same object type can belong to a protection group. For example, hosts or host groups cannot be added to a protection group that contains volumes.

To replicate snapshots, the protection group must include at least one target array (target) to where the replicated data is written. Include the --targetlist option to add the target arrays to the protection group. Once the target arrays have been added to the protection group, the source array must connect to each of the target arrays (purearray connect), and then each target array must allow data to be replicated from the source array (purepgroup allow). For more information about connecting arrays and allowing data replication on target arrays, refer to purepgroup-setattr(1).

Once a protection group has been created with members and target arrays (for replication only), it is ready to generate and replicate snapshots.

Renaming Protection Groups

Run purepgroup rename to change the current name (OLD-NAME) of the protection group to the new name (NEW-NAME). The name change is effective immediately and the old name is no longer recognized in CLI or GUI interactions. In the Purity GUI, the new name appears upon page refresh.

Protection group snapshots cannot be renamed.

Destroying Protection Groups

Protection groups can be destroyed, eradicated, and recovered by the respective purepgroup command.

The purepgroup destroy command destroys the specified protection group and, implicitly, all of its snapshots. Once a protection group has been destroyed, the replication process for the protection group stops. Destroyed protection groups and their snapshots undergo a 24-hour eradication pending period after which time the protection groups and their snapshots are completely eradicated and unrecoverable. Run purepgroup list --pending to display a list of protection groups and snapshots, including those that are pending eradication. Run purepgroup list --pending-only to only display a list of protection groups and their snapshots that are pending eradication.

During the eradication pending period, the destruction of the protection group and snapshots can be cancelled by running purepgroup recover, returning the protection group, including its replication schedule and snapshots, to its original state.

During the eradication pending period, the destroyed protection group and its snapshots can be eradicated by running purepgroup eradicate. This command terminates the eradication pending period and immediately begins reclamation of physical storage occupied by data "charged" to the snapshots of the destroyed protection group. Once eradication has begun, a protection group and its snapshots can no longer be recovered.

Generating Protection Group Snapshots On Demand

There are two ways to generate and replicate protection group snapshots:

  • Scheduled. Schedule the protection group to automatically generate local snapshots and/or replicate snapshot data to its target arrays on a regular, pre-defined basis.

    Configure protection group schedules through the purepgroup schedule command. For steps on how to configure a protection group snapshot and replication schedule, refer to purepgroup-setattr(1).

    View protection group schedules through the purepgroup list --schedule command. For more information about viewing protection group attributes and schedules, refer to purepgroup-list(1).

  • On Demand. Manually generate local protection group snapshots or replicate protection group snapshot data to its target arrays.

An on-demand snapshot represents a snapshot that is manually generated by running purepgroup snap. If the --replicate-now option is used, the on-demand snapshot is replicated immediately to the target arrays that allow protection group replication. Alternatively, if the --replicate option is used, the on-demand snapshot is queued for replication. Purity will begin replicating data to each allowed target only when all earlier replication sessions for the same protection group have been completed to that target, excluding those started with --replicate-now.

By default, an on-demand snapshot is retained indefinitely or until it is manually destroyed. Include the --apply-retention option to apply the scheduled snapshot or replication retention policy to the on-demand snapshot. For example, when generating a local snapshot on demand, include the --apply-retention option to keep the snapshot on the source array for the length of time based on the snapshot retention schedule. Likewise, when replicating a snapshot on demand, include the --apply-retention option to keep the snapshot on the target array for the length of time based on the replication retention schedule.

To replace the NNN snapshot number in the snapshot name with a custom string, include the --suffix option in the purepgroup snap command.

Destroying Protection Group Snapshots

Destroy a protection group snapshot if it is no longer required. Run purepgroup destroy to destroy the specified protection group snapshot.

Destroying a protection group snapshot destroys all of its protection group volume snapshots, thereby reclaiming the physical storage space occupied by its data.

Destroyed protection group snapshots follow the same eradication pending behavior as destroyed protection groups. When a protection group snapshot is destroyed, Purity automatically takes an undo snapshot. The undo snapshot enters a 24-hour eradication pending period, after which time the snapshot is eradicated. During the 24-hour pending period, the undo snapshot can be viewed, recovered, or permanently eradicated.

Protection group volume snapshots cannot be destroyed individually. A protection group volume snapshot can only be destroyed by destroying the protection group snapshot to which it belongs.

Restoring Volumes from Protection Group Snapshots

The purepgroup copy command restores the state of the volumes within a protection group to a previous protection group snapshot. The restored volumes are added as real volumes to a new or existing protection group.

The purepgroup copy command requires source (SOURCE) and destination (DEST) arguments.

The source argument represents the protection group snapshot to be restored. To restore a specific protection group snapshot, include the full protection group snapshot name in the source argument. For example, if source is specified as pgroup1.5213, Purity restores the volumes from protection snapshot pgroup1.5213. To restore volumes from the most recent, fully generated protection group snapshot (either locally generated or replicated from another array), specify the protection group name only. For example, if source is specified as pgroup1, Purity restores the volumes from the latest, fully generated protection group snapshot of pgroup1.

The source argument also determines whether the protection group snapshot to be restored was generated locally or replicated from another array. If the protection group snapshot was replicated from another array, include the name of the array in the source argument. For example, if source is specified as array1:pgroup1.5213, Purity restores the volumes from protection group snapshot pgroup1.5213, which was replicated over from array1.

The destination argument represents the name of the protection group to where the volumes will be restored. If the destination protection group and all of its volumes already exist, include the --overwrite option to overwrite all of the existing volumes with the snapshot contents. When using the --overwrite option, the names of the volumes that are being overwritten must match the names of the volumes that are being restored.

The following restrictions apply to the purepgroup copy command:

  • You cannot restore a volume if it already exists on the array unless you include the --overwrite option.

  • You cannot overwrite destination protection groups that contain hosts, host groups, or connected volumes.

  • You cannot run the purepgroup copy --overwrite command to create multiple clones of the protection group or its volume snapshots.

Restoring volumes from a protection group snapshot does not automatically expose the restored volumes to hosts and host groups. Run the purehgroup connect, purehost connect or purevol connect comamnd to establish connections.

If the protection group snapshot being restored is one that was replicated from another array, Purity automatically includes the original source array as a target array in the new protection group. By default, the original source array disallows replication from the target array. Therefore, to replicate the protection group and its newly restored volumes back to the original source array, allow replication on the original source array.

After the volumes are restored, the created date of the volumes is set to the date of the purepgroup copy action.

Examples

Example 1

  purepgroup create --vollist vol1,vol2,vol3 pgroup1
      

Creates protection group pgroup1 and associates volumes vol1,vol2,vol3 with it.

Example 2

  purepgroup destroy pgroup12
      

... less than 24 hours passes...

  purepgroup recover pgroup12
      

Destroys protection group pgroup12 and its snapshots and then recovers the destroyed protection group and its snapshots.

Example 3

  purepgroup destroy pgroup5.10
      

... less than 24 hours passes...

  purepgroup eradicate pgroup5.10
      

Destroys protection group snapshot pgroup5.10 and then eradicates the destroyed snapshot. Purity immediately begins reclaiming the physical storage space occupied by the snapshot. Protection group snapshot pgroup5.10 can no longer be recovered.

Example 4

  purepgroup snap --replicate-now pgroup10
      

Generates an on-demand snapshot of all volumes, hosts, or host groups in protection group pgroup10 and replicates the snapshot to all of the pgroup10 target arrays that have allowed protection group replication.

Example 5

purepgroup copy pgroup1 pgroup6
purevol connect --host host01 vol01 vol02
      

Restores the volumes from the most recent, fully and locally generated protection group snapshot of protection group pgroup1 to a new protection group named pgroup6 on the same array, and then connects newly restored volumes vol01 and vol02 to host host01.

Example 6

purepgroup copy array1:pgroup2.5213 pgroup25
      

Restores the volumes from protection group snapshot pgroup2.5213, which was replicated over from source array array1. The restored volumes are saved as real volumes to new protection group pgroup25 on the current array. To replicate new protection group pgroup25 and its restored volumes from the current array back to the original source array, enable replication and then allow replication from the source array.

Example 7

purepgroup copy --overwrite pgroup5.4765 pgroup5
      

Restores the volumes from locally generated protection group snapshot pgroup1.123 to existing protection group pgroup1, overwriting all of the existing volumes with the snapshot contents.

Author

Pure Storage Inc.