Skip to main content
Pure1 Support Portal

purevol

Name

purevol, purevol-copy, purevol-create, purevol-destroy, purevol-eradicate, purevol-recover, purevol-rename, purevol-snap — manage the creation, naming, and destruction of Purity virtual storage volumes and snapshots of their contents, as well as the reclamation of physical storage occupied by the data in them

purevol-add, purevol-remove — manage adding and removing of Purity volumes to and from protection groups, respectively

purevol-monitor — monitor volume I/O performance

Synopsis

purevol copy [--overwrite] SOURCE TARGET

purevol create --size SIZE VOL...

purevol destroy VOL...

purevol eradicate VOL...

purevol add --pgroup PGROUP VOL...

purevol remove --pgroup PGROUP VOL...

purevol monitor [--csv] [--filter FILTER] [ --historical { 1h | 3h | 24h | 7d | 30d | 90d | 1y } ] [--interval SECONDS] [--limit LIMIT] [--notitle] [--page] [--raw] [--repeat REPEAT-COUNT] [--size] [--sort SORT] [--total] [VOL...]

purevol recover VOL...

purevol rename OLD-NAME NEW-NAME

purevol snap [--suffix SUFFIX] VOL...

Arguments

NEW-NAME

Name by which the volume or volume snapshot is to be known after the command executes.

OLD-NAME

Current name of the volume or volume snapshot to be renamed.

SOURCE

Volume or snapshot from where data is copied. The data is copied to the TARGET volume.

TARGET

Volume to where data is copied. The data is copied from the SOURCE volume or snapshot.

VOL

Volume or volume snapshot to be created, destroyed, eradicated, or recovered. For purevol snap, volume to be snapped.

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.

Volume Sizes

Volume sizes are specified as an integer, followed by one of the suffix letters K, M, G, T, P, representing KiB, MiB, GiB, TiB, and PiB, respectively, where "Ki" denotes 2^10, "Mi" denotes 2^20, and so on.

Volumes must be between one megabyte and four petabytes in size. If a volume size of less than one megabyte is specified, Purity adjusts the volume size to one megabyte. If a volume size of more than four petabytes is specified, the Purity command fails.

Volume sizes cannot contain digit separators. For example, 1000g is valid, but 1,000g is not.

Options

-h | --help

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

--historical TIME

Display historical performance data over the specified range of time. Valid time range options include: 1 hour, 3 hours, 24 hours, 7 days, 30 days, 90 days, and one year.

--interval SECONDS

Sets the number of seconds between displays of real-time performance data. At each interval, the system displays a point-in-time snapshot of the performance data. If omitted, the interval defaults to every 5 seconds.

--overwrite

Allows purevol copy to overwrite an existing volume. Without this option, if the target volume already exists, the command fails.

--pgroup PGROUP

Comma-separated list of protection groups to which the specified volumes are added or from which the specified volumes are removed. Has no effect on volumes already associated with the protection group.

--repeat REPEAT-COUNT

Sets the number of times to display real-time performance data. If omitted, the repeat count defaults to 1.

--size

For purevol create, sets the virtual capacity of the volume as perceived by hosts.

For purevol monitor, displays the average I/O sizes per read and write operation.

--suffix

In the purevol snap subcommand, an optional suffix that is appended to the names of snapped volumes to create snapshot names. If not supplied, Purity constructs snapshot names of the form VOL.NNN, where NNN is a unique number assigned by Purity.

--total

Follows output lines with a single line containing column totals in columns where they are meaningful.

Options that control display format:

--csv

Lists information in comma-separated value (CSV) format. The --csv output can be used for scripting purposes and imported into spreadsheet programs.

--notitle

Lists information without column titles.

--page

Turns on interactive paging.

--raw

Displays the unformatted version of column titles and data. For example, in the purearray monitor output, the unformatted version of column title us/op (read) is usec_per_read_op. The --raw output is used to sort and filter list results.

Options that manage display results:

--filter

Displays only the rows that meet the filter criteria specified.

--limit

Limits the size of the list output to the specified maxmimum number of rows.

--sort

Sorts the list output in ascending or descending order by the column specified.

Description

This page describes the management of volumes and volume snapshots.

Volumes

Creating Volumes

The purevol create command creates one or more Purity virtual storage volumes of the host-visible size specified by the --size option.

Volumes do not consume physical storage until data is actually written to them, so volume creation has no immediate effect on an array's physical storage consumption.

Volumes created by the purevol create subcommand have a null value for the source attribute.

Connecting Volumes to Hosts or Host Groups

Volumes must be connected to hosts in order for the hosts to read and write data on them. The purevol connect command establishes either private connections between volumes and individual hosts or shared connections between volumes and host groups. The same connections can be established through the purehost connect and purehgroup connect commands. For more information about private connections, refer to purehost-connect(1), For more information about shared connections, refer to purehgroup-connect(1),

The purevol connect command also connects volumes to apps. For more information about Pure Apps and the pureapp command,

Renaming Volumes

Run the purevol rename subcommand to change the current (OLD-NAME) name of the volume or volume snapshot 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.

Copying Volumes

The purevol copy command can be used to create a volume from another volume, or to replace the contents of an existing volume with those of another volume. Volumes created in this way have a Source attribute whose value is the name of the originating volume. An undo snapshot is automatically taken (providing a 24-hour window during which the previous contents can be retrieved).

Destroying Volumes

When a volume or snapshot is no longer required, it can be destroyed to reclaim the physical storage occupied by its data (purevol destroy command). Destroying a volume implicitly destroys all of its snapshots.

Destroying an individual snapshot only reclaims space that is uniquely charged to the snapshot. Space shared with older snapshots or with the originating volume remains allocated. Before a volume can be destroyed, it must be disconnected (purevol disconnect command).

Destruction of volumes and snapshots is not immediate. The purevol destroy command places volumes and snapshots in the eradication pending state, making them immediately inaccessible, while leaving their data intact for 24 hours (known as the eradication pending period). At any time during the eradication pending period, an administrator can use the purevol recover command to recover the contents of a destroyed volume or destroyed snapshot.

When a destroyed volume's or snapshot's 24-hour eradication pending period has lapsed (or if an administrator eradicates the volume or snapshot during the eradication pending period), Purity reclaims the physical storage occupied by its data.

If the physical storage occupied by a destroyed volume's or destroyed snapshot's data is required immediately (for example, if a large amount of new data is to be written), an administrator can use the purevol eradicate command to terminate the eradication pending period and initiate immediate storage reclamation. The purevol eradicate command only acts on previously destroyed volumes and snapshots.

Once reclamation starts, whether because an eradication pending period has lapsed or because a purevol eradicate command was executed, a destroyed volume's or destroyed snapshot's data can no longer be recovered.

Adding Volumes to Protection Groups

The purevol add command adds existing volumes to existing protection groups. Multiple volumes can be added to multiple protection groups. Enter multiple protection groups in comma-separated format.

If a protection group already includes other volumes, those volumes are unaffected.

Only members of the same object type can belong to a protection group. For example, a volume cannot be added to a protection group that already contains hosts or host groups.

The purevol add command only accepts volumes that do not already belong to any of the specified protection groups. If any of the volumes already belong to any of the protection groups, the entire command fails.

Run the purevol list --protect command to see a list of all protected volumes and their associated protection groups.

The purevol remove command removes one or more volumes from one or more protection groups. All of the specified volumes must belong to all of the specified protection groups in the command; otherwise, the command fails.

Volumes can also be added to and removed from protection groups through the purepgroup setattr command.

Monitoring Volume I/O Performance

The purevol monitor command displays real-time and historical I/O performance information for all or specified volumes. The purevol monitor output includes the following data about bandwidth, IOPS, and latency:

  • Name: Volume name.

  • Time: Current time.

  • B/s: Bandwidth. Number of bytes read/written.

  • op/s: IOPS. Number of read/write requests processed per second.

  • us/op: Internal latency. Average time, measured in microseconds, it takes the array to process a read or write I/O request.

  • SAN us/op: SAN time. Average time, measured in microseconds, required to transfer data between the initiator and the array.

  • B/op: IOPS. Average I/O size per read, write, and both read and write (all) operations. Must include the --size option to see the B/op columns.

By default, the purevol monitor command displays real-time performance data. Include the --interval option to specify the number of seconds between each real-time update. Include the --repeat option to specify the number of times to repeat the real-time update. The --interval and --repeat options can be combined.

The purevol monitor --historical command displays historical performance data over any of the following ranges of time: 1 hour, 3 hours, 24 hours, 7 days, 30 days, 90 days, or 1 year.

Volume Snapshots

A volume snapshot is a point-in-time image of the contents of a volume.

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

  • VOL is the name of the volume.

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

Creating Volume Snapshots

The purevol snap command creates point-in-time snapshots of the contents of one or more volumes. FlashArray snapshots make use of Purity deduplication technology; they consume space only when data is written to the volumes on which they are based.

All snapshots taken as a result of a single purevol snap command are atomic. They represent the specified volumes' contents as of a single instant in time.

Snapshots are immutable; they cannot be connected to hosts or host groups, and therefore the data they contain cannot be read or written.

Renaming Volume Snapshots

Run the purevol rename subcommand to change the current snapshot suffix name (OLD-NAME) of the volume to the new snapshot suffix 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.

Destroying Volume Snapshots

When a snapshot is no longer required, it can be destroyed to reclaim the physical storage occupied by its data (purevol destroy command).

Destroying an individual snapshot only reclaims space that is uniquely charged to the snapshot. Space shared with older snapshots or with the originating volume remains allocated.

Destruction of snapshots is not immediate. The purevol destroy command places snapshots in the eradication pending state, making them immediately inaccessible, while leaving their data intact for 24 hours (known as the eradication pending period). At any time during the eradication pending period, an administrator can use the purevol recover command to recover the contents of a destroyed snapshot.

When a destroyed snapshot's 24-hour eradication pending period has lapsed (or if an administrator eradicates the snapshot during the eradication pending period), Purity reclaims the physical storage occupied by its data.

If the physical storage occupied by a destroyed destroyed snapshot's data is required immediately (for example, if a large amount of new data is to be written), an administrator can use the purevol eradicate command to terminate the eradication pending period and initiate immediate storage reclamation. The purevol eradicate command only acts on previously destroyed snapshots.

Once reclamation starts, whether because an eradication pending period has lapsed or because a purevol eradicate command was executed, a destroyed snapshot's data can no longer be recovered.

Restoring Volumes from Volume Snapshots

The purevol copy command can be used to restore a volume by creating the volume from a snapshot, or to replacing the contents of the existing volume with those of the snapshot. Restoring a volume brings the volume back to the state it was when the snapshot was taken. When a volume is restored from a snapshot, Purity overwrites the entire volume with the snapshot contents. After you restore a volume, the created date of the overwritten volume is set to the snapshot created date. Purity automatically takes an undo snapshot of the overwritten volume. The undo snapshot enters a 24-hour eradication pending period, after which time the snapshot is destroyed. During the 24-hour pending period, the undo snapshot can be viewed, recovered, or permanently eradicated through the Destroyed Volumes folder.

Volumes created in this way have a Source attribute whose value is the name of the originating volume.

A snapshot's size attribute cannot be changed. When a snapshot is restored to create new or replace an existing volume, the volume's size becomes that associated with the snapshot.

Volume and Snapshot Space Accounting

FlashArray snapshots are inherently space saving in that a snapshot only consumes physical storage when data on its source volume is overwritten. Similarly, a volume created from a snapshot only consumes space when its contents change.

Output of the purevol list --snap command displays the amount of physical storage charged to specified volumes and their snapshots.

For example, if two snapshots of a volume, s1 and s2, are taken at times t1 and t2 (t1 < t2), space consumption is accounted as follows:

Volume data written before t1

If no snapshots exist, the volume is charged for space occupied by host-written data.

Volume data written after t1 but before t2

Snapshot s1 is charged for space occupied by the pre-update contents of the updated volume data.

Volume data written after t2

Snapshot s2 is charged for space occupied by the pre-update contents of the updated volume data (s1 shares the pre-update contents with s2).

If s1 is destroyed but s2 remains, storage charged to s1 is reclaimed because there is no longer a need to preserve pre-update content for updates made prior to t2. If s2 is destroyed, however, storage charged to it must be preserved (it represents pre-update content for updates made after t1, which must be preserved as long as s1 exists).

To generalize, if a volume has two or more snapshots taken at different times:

Destroying the oldest snapshot

Space charged to the destroyed snapshot is reclaimed (after the 24-hour eradication delay period has elapsed or after a purevol eradicate command is executed).

Destroying a snapshot other than the oldest

Space charged to the destroyed snapshot is charged to the next older snapshot unless it is already reflected in that snapshot (because the same volume block address was written both after the next older snapshot and after the snapshot being destroyed), in which case it is reclaimed.

Exceptions

  • Destroyed volumes cannot be truncated directly. They must be recovered to their original sizes first (provided that eradication has not begun) and then truncated. Truncation is immediate and irrevocable.

  • Volumes cannot be eradicated unless (a) they have previously been destroyed, and (b) they are within their 24-hour eradication pending periods.

  • The names of destroyed volumes cannot be reused to create other volumes until eradication has begun.

  • When a volume is destroyed, all of its existing snapshots are destroyed as well. Similarly, when a volume is recovered, snapshots that were implicitly destroyed as a consequence of the volume's destruction are recovered as well. Snapshots that are destroyed explicitly are not recovered by a purevol recover command specifying the volumes from which they were created.

Examples

Example 1

purevol create --size 100G VOL1 VOL2 VOL3
      

Creates three volumes called VOL1, VOL2, and VOL3, each with a host-visible capacity of 100 gigabytes (10^2 * 2^30 bytes).

Example 2

purevol create --size 100G VOL5 VOL6
      

... time passes...

purevol destroy VOL5
      

... less than 24 hours passes...

purevol eradicate VOL5
      

Creates 100-gigabyte volumes VOL5 and VOL6. Some time later, destroys VOL5, making it inaccessible to hosts and starting the 24 hour eradication pending period after which Purity reclaims the physical storage occupied by its data. The purevol eradicate command begins reclamation of physical storage occupied by VOL5's data immediately; VOL5 can no longer be recovered after this point.

Example 3

purevol destroy VOL4.415
      

... less than 24 hours later...

purevol recover VOL4.415
      

Destroys volume snapshot VOL4.415 and starts the 24-hour eradication pending period after which Purity would begin to reclaim the physical storage occupied by the volume snapshot's data. During the eradication pending period, the volume snapshot is restored to active status with its data intact.

Example 4

purevol monitor
      

Displays real-time performance data for all volumes.

Example 5

purevol monitor --repeat 60 --size
      

Displays real-time performance data for all volumes. The output includes average I/O sizes. Sixty (60) point-in-time updates are displayed, with each update taken at the default interval of every five (5) seconds.

Example 6

purevol monitor --historical 24h --csv VOL1 VOL2
      

Displays a CSV output of historical performance data for volumes VOL1 and VOL2 over the past 24 hours.

Example 7

purevol rename VOL1 VOL1NEW
      

Changes the name of VOL1 to VOL1NEW.

Example 8

purevol rename VOL1.SUFFIX1 VOL1.SUFFIX2
      

Changes the suffix of volume snapshot VOL1.SUFFIX1 from SUFFIX1 to SUFFIX2.

Example 9

purevol snap VOL1 1
purevol snap --suffix MONDAY1 VOL1 2
purevol snap --suffix MONDAY2 VOL1 VOL2 3
      

1

Create snapshot VOL1.1. (Purity chooses the unique number.)

2

Create snapshot VOL1.MONDAY1, representing VOL1 at time t1.

3

Create two snapshots:

  • VOL1.MONDAY2, representing VOL1 at time t2.

  • VOL2.MONDAY2, representing VOL2 at time t2.

Example 10 (Using a snapshot to recover from data corruption)

purevol snap --suffix SNAPSHOT VOL1 1

  ... applications using VOL1 encounter data corruption...

purevol copy VOL1.SNAPSHOT GOODVOL1 2

  ... hosts connect to GOODVOL1, validate data, and resume...

purevol destroy VOL1.SNAPSHOT 3
purevol eradicate VOL1.SNAPSHOT 4
      

1

Create snapshot VOL1.SNAPSHOT at a time when data is known to be correct. Some time later, applications using VOL1 encounter data corruption.

2

Create volume GOODVOL1 from snapshot VOL1.SNAPSHOT. The volume contains a pre-corruption data image of VOL1. Hosts recover lost information, for example by replaying logs, and continue processing data on GOODVOL1.

3

Destroy snapshot VOL1.SNAPSHOT when it is no longer required.

4

Start the process of reclaiming physical storage charged to VOL1.SNAPSHOT.

Example 11 (Cloning multiple volumes from a snapshot)

purevol snap --suffix TUESDAY VOL1 VOL2 1

  ... main application continues using VOL1 and VOL2...

purevol copy Vol1.TUESDAY Vol1Backup
purevol copy Vol2.TUESDAY Vol2Backup 2
purevol connect --host HostBackup Vol1Backup Vol2Backup 3

  ... backup starts ...

purevol copy Vol1.TUESDAY Vol1Analytics 4
purevol connect --host HostAnalytics Vol1Analytics 5

  ... analytics starts, using VOL1 image only ...
  ... backup completes ...

purevol disconnect --host HostBackup Vol1Backup Vol2Backup
purevol destroy Vol1Backup Vol2Backup 6

  ... analytics completes ...

purevol disconnect --host HostAnalytics Vol1Analytics
purevol destroy Vol1Analytics 7

purevol eradicate Vol1Analytics Vol1Backup Vol2Backup 8
      

1

Create snapshots VOL1.TUESDAY and VOL2.TUESDAY, representing the data on the respective volumes at a single instant in time. The main application continues to operate using VOL1 and VOL2.

2

Create accessible volumes Vol1Backup and Vol2Backup.

3

Connect the two backup volumes to HostBackup, making it possible to back up the data images they contain.

4

(Assuming that the analytics application only requires data from VOL1.) Create volume Vol1Analytics from the same snapshot used to create Vol1Backup.

5

Connect Vol1Analytics to HostAnalytics, making it possible to analyze the data image from VOL1.

6

When backup application completes, disconnect the two backup volumes from HostBackup and destroy them.

7

When analytics application completes, disconnect Vol1Analytics from HostAnalytics and destroy the volume.

8

Eradicate the three volumes used by the ancillary backup and analytics applications, starting the process of reclaiming the space charged to them.

Example 12 (Destroying and recovering snapshots and volumes)

purevol snap --suffix FirstSnap VOL1
purevol snap --suffix SecondSnap VOL1
purevol snap --suffix ThirdSnap VOL1
purevol snap --suffix FourthSnap VOL1 1
purevol destroy VOL1.FirstSnap
purevol eradicate VOL1.FirstSnap 2
purevol destroy VOL1.SecondSnap 3
purevol destroy VOL1 4
purevol recover VOL1 5
purevol recover VOL1.SecondSnap 6
      

1

Create snapshots of VOL1 at four different points in time.

2

Destroy and eradicate VOL1.FirstSnap. The snapshot is no longer recoverable.

3

Destroy, but do not eradicate, VOL1.SecondSnap. For 24 hours after the command executes, VOL1.SecondSnap can be recovered.

4

Destroy, but do not eradicate, VOL1, and implicitly, its two remaining snapshots, VOL1.ThirdSnap and VOL1.FourthSnap.

5

(Executes within 24 hours of 4 execution). Recover VOL1 and the snapshots that were implicitly destroyed along with it. Recover VOL1.ThirdSnap and VOL1.FourthSnap, but not VOL1.SecondSnap (because it was destroyed separately), or VOL1.FirstSnap (because it was destroyed and eradicated separately).

6

(Executes within 24 hours of 3 execution). Recover snapshot VOL1.SecondSnap. Because VOL1.FirstSnap was eradicated, it is not possible to recover it with a similar command.

Example 13 (Refreshing volume contents from snapshots and volumes)

purevol snap --suffix SNAPSHOT VOL1 1

  ... applications continue to access VOL1...

purevol copy VOL1.SNAPSHOT VOL1Image 2

  ... update data format on VOL1Image...

purevol disconnect --host HOST1 VOL1
purevol copy --overwrite VOL1Image VOL1
purevol connect --host HOST1 VOL1 3

  ... restart applications using updated data format...

  ... detect problem with updated format...

purevol disconnect --host HOST1 VOL1
purevol copy --overwrite VOL1.SNAPSHOT VOL1
purevol connect --host HOST1 VOL1 4

  ... resume applications using older data format...
      

1

Create snapshot VOL1.SNAPSHOT of volume VOL1.

2

Create volume VOL1Image. Use it to update data format for applications that use VOL1.

3

Momentarily disconnect HOST1 from its data, and overwrite said data with data in the updated format from volume VOL1Image. Applications detect problems with updated data format.

4

Momentarily disconnect HOST1 from its volume, revert data on VOL1 to previous format by copying from snapshot VOL1.SNAPSHOT, and reconnect VOL1 to HOST1 so that applications can resume processing using older format data.

Author

Pure Storage Inc.