Skip to main content
Pure1 Support Portal

purevol-list

Name

purevol-list, purevol-listobj — display volumes' attributes and information about the virtual and physical storage they consume

Synopsis

purevol list [ --all | --connect | --protect | --space ] [ --cli | --csv | --nvp ] [--filter FILTER] [ --historical { 1h | 3h | 24h | 7d | 30d | 90d | 1y } ] [--limit LIMIT] [--notitle] [--page] [ --pending | --pending-only ] [--pgrouplist PGROUPLIST] [ --private | --shared ] [--raw] [--snap] [--sort SORT] [--total] [VOL...]

purevol listobj [--csv] [ --pending | --pending-only ] [--pgrouplist PGROUPLIST] [ --type { host | snap | vol } ] [VOL...]

Arguments

VOL

Volume for which the information specified by options is to be displayed

Options

Options that control information displayed:

-h | --help

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

--all

Displays names, virtual sizes, connected hosts and host groups, and host and array worldwide names or IQNs for the specified volumes.

--connect

Displays names, virtual sizes, connected hosts and host groups for specified volumes.

--historical TIME

Used with purevol list --space to display historical size and space consumption information 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.

--pending

Includes destroyed volumes or snapshots that are in the eradication pending state. If not specified, volumes or snapshots that are pending eradication are not shown.

--pending-only

Only displays destroyed volumes or snapshots that are in the eradication pending state.

--pgrouplist

Used with purevol list --snap to only display volume snapshots that have been created as part of the specified protection group or protection group snapshot. Enter multiple protection group or protection group snapshot arguments in comma-separated format.

--private

Used with purevol list --connect to restrict the display to specified volumes' privately connected hosts. Invalid when combined with other options.

--protect

Displays all protected volumes and their associated protection groups.

--shared

Used with purevol list --connect to restrict the display to specified volumes' shared connections. Invalid when combined with other options.

--snap

Displays information for snapshots of the specified volumes rather than for the volumes themselves.

--space

Displays the following information about provisioned (virtual) size and physical storage consumption for each specified volume:

Size

Total provisioned size of the volume. Represents storage capacity reported to hosts.

Thin Provisioning

Percentage of volume sectors that do not contain host-written data because the hosts have not written data to them or the sectors have been explicitly trimmed.

Data Reduction

Ratio of mapped sectors within a volume versus the amount of physical space the data occupies after data compression and deduplication. The data reduction ratio does not include thin provisioning savings.

For example, a data reduction ratio of 5:1 means that for every 5 MB the host writes to the array, 1 MB is stored on the array's flash modules.

Total Reduction

Ratio of provisioned sectors within a volume versus the amount of physical space the data occupies after reduction via data compression and deduplication and with thin provisioning savings. Total reduction is data reduction with thin provisioning savings.

For example, a total reduction ratio of 10:1 means that for every 10 MB of provisioned space, 1 MB is stored on the array's flash modules.

Volume

Physical space occupied by volume data that is not shared across volumes, excluding array metadata and snapshots.

Snapshots

Physical space occupied by data unique to one or more snapshots.

Shared Space

Physical space occupied by deduplicated data, meaning that the space is shared with other volumes and snapshots as a result of data deduplication.

System

Physical space occupied by internal array metadata.

Total

Total physical space occupied by system, shared space, volume, and snapshot data.

--total

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

--type

Specifies the type of information (connected hosts, snapshots, or echoed volume names) about specified volumes to be produced in whitespace-separated list format suitable for scripting.

Options that control display format:

--cli

Displays output in the form of CLI commands that can be issued to reproduce the current configuration. The --cli output is not meaningful when combined with immutable attributes.

--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.

--nvp

Lists information in name-value pair (NVP) format, in the form ITEMNAME=VALUE. Argument names and information items are displayed flush left. The --nvp output is designed both for convenient viewing of what might otherwise be wide listings, and for parsing individual items for scripting purposes.

--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

The purevol list command displays a list of Purity virtual storage volumes on the array. The list includes volume attributes such as volume (virtual) size, volume creation date, and volume serial number (generated by Purity when the volume is created).

The purevol list command includes the mutually exclusive --all, --connect, and --space options, which are used to modify the display output of purevol list. The --all option displays volume connection details, including volume size, LUN number, and "paths" to connected hosts (host and corresponding array port WWNs or IQNs). The --connect option displays the hosts and host groups to which the specified volumes are connected, and the LUNs used by each to address them. The --protect option displays all protected volumes and their associated protection groups. The --space option displays information about provisioned (virtual) size and storage consumption for each volume. Include the --historical option with --space to display historical size and storage consumption details for each volume.

The purevol list --pending command displays a list of all volumes, including ones that have been destroyed and are in the eradication pending state. The purevol list --pending-only command only displays a list of volumes that have been destroyed and are in the eradication pending state.

The purevol list --total command displays the aggregate host-visible size of the volumes. The --total option cannot be run with the --all or --connect options because these options can conceivably display more than one output line per volume.

The purevol listobj command displays a list volume attributes, either in whitespace or comma-separated form, suitable for scripting. The --type option accepts the following arguments:

--type host

Display a list of hosts to which the specified volumes are connected. If no volumes are specified, the list contains the names of all hosts connected to any volume.

--type snap

Displays a list of volume snapshots, generated through volume or protection group snapshots, for the specified volumes. If no volumes are specified, the list contains the names of all volume snapshots.

--type vol (default if --type option not specified)

Lists the specified volume names. If no volume names are specified, the list contains the names of all volumes. Snapshots are not included in the list.

Lists are whitespace-separated by default. Include the --csv option to produce a comma-separated list.

Displaying and Listing Snapshots

The purevol list --snap command displays a list of volume snapshots rather than volumes. Both volume and snapshot arguments can be included in the same command. The --snap option can be specified with the --pending, --pending-only, and --space options.

The purevol list --snap --pgrouplist command only displays volume snapshots that are created as part of the specified protection group or protection group snapshot. Enter multiple protection group or protection group snapshot arguments in comma-separated format.

The --snap option is not valid with the --all, --connect, --private, or --shared options.

The purevol listobj --type snap command displays the names of volume snapshots generated through volume or protection group snapshots.

App Volumes

The Apps platform extends array functionality by integrating add-on, VM-based services into the Purity operating system. Each app within the platform provides one or more services.

Each app has a boot volume and a data volume. Run the purevol list command to see a list of app volumes. App volume names begin with a distinctive @ symbol.

The naming convention for app volumes is @APP_boot for the boot volume and @APP_data for the data volume, where APP denotes the app name.

The following example displays the boot and data volumes for the linux app.

$ purevol list @linux*
Name         Size  Source  Created                  Serial
...
@linux_boot  15G   -       2016-11-09 15:13:37 MST  AC97A330F2544A3C00011010
@linux_data  16T   -       2016-11-09 15:14:17 MST  AC97A330F2544A3C00011012
...

The boot volume represents a copy of the boot drive of the app. Do not modify or save data to the boot volume. When an app is upgraded, the boot volume is overwritten, completely destroying its contents including any other data that is saved to it. The data volume is used by the app to store data.

For more information about Apps, refer to pureapp(1).

Exceptions

None.

Examples

Example 1

purevol list
      

Displays names, sizes, and serial numbers of all volumes. Both directly connected hosts and hosts connected by virtue of their associations with host groups are displayed.

Example 2

$ purevol list @*
      

Displays a list of all app volumes on the array.

Example 3

purevol list --space --csv --notitle VOL1 VOL2 VOL3
      

Displays names, sizes, data reduction ratios, and physical storage space occupied by volume data and RAID-3D check data for volumes VOL1, VOL2, and VOL3, in comma-separate value format. The --notitle option suppresses the line of column titles that would ordinarily precede the output.

Example 4

purevol list --space --historical 3h --csv --notitle VOL1 VOL2 VOL3
      

Displays names, sizes, data reduction ratios, and physical storage space occupied by volume data and RAID-3D check data for volumes VOL1, VOL2, and VOL3, for the past 3 hours, in comma-separate value format. The --notitle option suppresses the line of column titles that would ordinarily precede the output.

Example 5

purevol list --connect --shared --nvp VOL4 VOL5
      

For volumes VOL4 and VOL5, displays names, sizes, connected host groups and their associated hosts, and LUNs used to address the volumes, all in name-value pair (ATTRIBUTE-NAME=ATTRIBUTE-VALUE) format. Only shared connections are included.

Example 6

purevol list --connect --shared VOL1
      

Displays host groups to which VOL1 has shared connections and the LUNs used by hosts in the groups to address it.

Example 7

purehost listobj --type vol --private $(purevol listobj --type host --private VOL1)
      

Produces a list of hosts with private connections to VOL1, which is input to the purehost listobj command to display a list of the volumes to which those hosts have private connections.

Example 8

purehost list --connect $(purevol listobj --type host VOL1)
      

The inner purevol listobj command produces a whitespace-separated list of hosts to which VOL1 is connected. The list becomes input to the outer purevol list command. The result is a display of information about hosts connected to VOL1.

Example 9

purevol destroy VOL2
purevol list --space --pending
      

Places VOL2 in the eradication pending state for 24 hours. Produces a space report of volumes, plus all volumes that are pending eradication (including destroyed volume VOL2). VOL2 continues to occupy space until the 24-hour pending period has elapsed or until the volume has been manually eradicated by the purevol eradicate command.

Example 10

purevol destroy VOL2
purevol destroy VOL3
purevol list --space --pending-only
      

Places VOL2 and VOL3 in the eradication pending state for 24 hours. Produces a space report of volumes that are pending eradication (including VOL2 and VOL3). VOL2 and VOL3 continue to occupy space until the 24-hour pending period has elapsed or until the volumes have been manually eradicated by the purevol eradicate command.

Example 11

purevol list --snap --pgrouplist PG1.1
      

Produces a list of volume snapshots created for protection group snapshot PG1.1.

Example 12

purevol list --snap --pgrouplist PG1,PG2 V1
      

Displays a list of volume snapshots of V1 that were created for all snapshots of protection groups PG1 and PG2.

Example 13

purevol destroy $(purevol listobj --type snap VOL1)
      

In this example:

  • The purevol listobj (inner) command produces a whitespace-separated list of the snapshots of VOL1.

  • The purevol destroy (outer) command destroys the snapshots enumerated in the inner command.

Author

Pure Storage Inc.