Skip to main content
Pure1 Support Portal

Purity CLI Getting Started

FlashArrays present disk-like volumes to hosts. From the Purity standpoint, volumes and hosts are abstract objects which must be created by an administrator and connected to each other before actual host computers can write and read data on volumes.

Creating Volumes

Once a FlashArray is installed and initially configured, an administrator's typical first task is creation of volumes that hosts will subsequently format and use to store and access data. Example 1 illustrates three examples of volume creation using the CLI.

Example 1. Creating Volumes

$ purevol create vol1 1
usage: purevol create [-h] --size SIZE VOL ...
purevol create: error: argument --size is required
$ purevol create vol1 --size 100g 2
Name Size Serial
vol1 100G 7CBFCE0B2660CC3000010001
$ purevol create vol2 vol3 vol4 --size 200g 3
Name Size Serial
vol2 200G 7CBFCE0B2660CC3000010002
vol3 200G 7CBFCE0B2660CC3000010003
vol4 200G 7CBFCE0B2660CC3000010004
      

1

Command fails, because no virtual size is specified for the volume.

2

Creates a volume that hosts will perceive as containing 100 gigabytes of storage, although it occupies almost no physical space until hosts write data to it.

3

Creates three volumes in a single command. There is no practical limit to the number of volumes that can be created in a single command, but only one --size option can be specified in the command, so all volumes initially have the same virtual size.


The output of the purevol create command lists the name, size, and Purity-generated serial number of each volume created.

Creating Hosts

Internally, Purity represents host computers that use FlashArray storage services as host objects (usually just called "hosts"). A Purity host object has a name and one or more Fibre Channel worldwide names (WWNs) or iSCSI qualified names (IQNs). WWNs and IQNs correspond to initiators, typically host computers or host computer ports with which a FlashArray exchanges commands, data, and messages. Purity represents a host's WWNs and IQNs as a multi-valued attribute, specified via either the --wwnlist (alias --wwn) or the --iqnlist (alias --iqn) option when hosts are created. Fibre Channel WWNs consist of exactly 16 hexadecimal digits, and may be specified either as continuous strings or as eight digit pairs separated by colons. iSCSI IQNs conform to Internet fully-qualified domain name (FQDN) standards Example 2 illustrates four examples of host creation.

Example 2. Creating Hosts

$ purehost create host1 1
Name  WWN
host1 -
$ purehost create --wwnlist 0123456789abcde2 host2 2
Name  WWN
host2 01:23:45:67:89:AB:CD:E2
$ purehost create --wwnlist 0123456789abcde3,01:23:45:67:89:ab:cd:e4 host3 3
Name  WWN
host3 01:23:45:67:89:AB:CD:E3
    01:23:45:67:89:AB:CD:E4
$ purehost create --wwn 01:23:45:67:89:ab:cd:e4 host4 4
Error on host4: The specified WWN is already in use.
      

1

Creates host object host1. At the time of creation, host1 cannot connect to volumes because no WWNs or IQNs are associated with it.

2

Creates host2 and assigns WWN 0123456789abcde2 to it. Volumes can be connected to host2 immediately.

3

Creates host3 and associates two WWNs with it (typically because the host is equipped with two Fibre Channel ports). This example also illustrates the two forms in which worldwide names can be entered--continuous digit string and colon-separated two-digit groups.

4

Attempts to create host4 and fails, because the WWN specified is already associated with another host. Because they identify host ports on the storage network, WWNs must be unique within an array.


Connecting Hosts and Volumes

For a host to read and write data on a volume, a connection between the two must be established. A connection is effectively permission for an array to respond to I/O commands from a given set of storage network addresses (host WWNs or IQNs). In SCSI terminology, a connection is an Initiator-Target-LUN (I_T_L) nexus, a completely specified path for message and data exchange. By default, Purity chooses a LUN based on availability at both the initiator (host) and target (array) when a connection is established. Alternatively, an administrator can specify an unused LUN when establishing a connection.

The purehost connect command establishes private connections between a single volume and one or more hosts. The purevol connect command establishes connections between a single host and one or more volumes. The two commands are functionally identical. Both commands are provided for administrative convenience. Example 3 illustrates the use of both commands.

Example 3. Establishing Host-Volume Connections

$ purehost connect --vol vol1 host1 host2 host3 1
Name   Vol   LUN
host1  vol1  1
host2  vol1  1
host3  vol1  1
$ purevol connect --host host1 vol2 vol3 vol4 2
Name  Host Group  Host   LUN
vol2  -           host1  2
vol3  -           host1  3
vol4  -           host1  4
$ purevol connect --lun 249 --host host1 vol5 3
Name  Host Group  Host   LUN
vol5  -           host1  249
$ purehost disconnect --vol vol1 host2 4
Name   Vol
host2  vol1
$ purevol disconnect --host host3 vol1 5
Name Hgroup Host
vol1        host3
      

1

Connects vol1 to hosts host1, host2, and host3.

2

Connects host1 to volumes vol2, vol3, and vol4.

3

Connects host1 to vol5, manually associating LUN 249 with the connection. Any available LUNs in the range [1...4095] can be used for private or shared connections.

4 5

The purehost disconnect or purevol disconnect commands in the example break the private connections between host2 and vol1, and between host3 and vol1 respectively. Either can be used to break a private connection between a host and a volume, regardless of how the connection was established. As with the connect subcommands, purehost disconnect can disconnect multiple hosts from a single volume, and purevol disconnect can disconnect multiple volumes from a single host. The two subcommands are provided for administrative convenience.


Whichever way a connection is made, the host administrator can immediately rescan the host's flash modules (if necessary) to discover the logical units represented by newly-connected volumes, create file systems, and mount them for storing and retrieving data.

Resizing Volumes

FlashArray administrators also perform routine management tasks on objects within an array. Typically the most frequent of these are operations on volumes. You can change the size (host-visible storage capacity) of a volume, disconnect it from hosts, rename it, destroy it, eradicate all or part of the data it contained, and under certain circumstances, restore the contents of a destroyed volume or truncated sector range.

To minimize the possibility for inadvertent errors, the CLI uses different subcommands for increasing and decreasing the host-perceived sizes of volumes. The purevol setattr command increases the sizes of one or more volumes to a given level; the purevol truncate command decreases volumes’ sizes. Both commands can operate on multiple volumes, but purevol setattr can only increase volume sizes, and purevol truncate can only decrease them.

Example 4 illustrates the use of these commands to change volumes’ sizes.

Example 4. Resizing Volumes

$ purevol list vol1 vol2 vol3 vol4
Name  Size  Serial
vol1  100G  7CBFCE0B2660CC3000010001
vol2  200G  7CBFCE0B2660CC3000010002
vol3  200G  7CBFCE0B2660CC3000010003
vol4  200G  7CBFCE0B2660CC3000010004
$ purevol setattr --size 300g vol1 vol2 1
Name  Size  Serial
vol1  300G  7CBFCE0B2660CC3000010001
vol2  300G  7CBFCE0B2660CC3000010002
$ purevol truncate --size 100g vol3 vol4 2
Name  Size  Serial
vol3  100G  7CBFCE0B2660CC3000010003
vol4  100G  7CBFCE0B2660CC3000010004
$ purevol setattr --size 250g vol2 vol3 3
Name  Size  Serial
vol3  250G  7CBFCE0B2660CC3000010003
Error on vol2: Implicit truncation not permitted.
$ purevol list vol2 vol3
Name  Size  Serial
vol2  300G  7CBFCE0B2660CC3000010002
vol3  250G  7CBFCE0B2660CC3000010003
$ purevol truncate --size 275g vol2 vol3 4
Name  Size  Serial
vol2  275G  7CBFCE0B2660CC3000010002
Error on vol3: Target size exceeds volume size.
$ purevol list vol2 vol3
Name  Size  Serial
vol2  275G  7CBFCE0B2660CC3000010002
vol3  250G  7CBFCE0B2660CC3000010003
        

1

Increases the sizes of vol1 and vol2 from 100 gigabytes and 200 gigabytes respectively to 300 gigabytes.

2

Reduces the sizes of vol3 and vol4 from 200 gigabytes to 100 gigabytes.

3

Attempts to change the sizes of vol2 and vol3 to 250 gigabytes. The command succeeds for vol3, but fails for vol2 because it is already larger than 250 gigabytes.

4

Attempts to change the sizes of vol2 and vol3 to 275 gigabytes. The command succeeds for vol2, but fails for vol3 because it is already smaller than 275 gigabytes (the “target size”).


Increasing a volume's host-perceived size does not increase its consumption of physical storage. Volumes only consume storage when hosts write data to previously unused volume block addresses or overwrite blocks with less-compressible data.

When a volume is truncated, Purity automatically takes an undo snapshot (providing a 24-hour window during which the previous contents can be retrieved). If the physical storage occupied by data in truncated sectors is urgently required, the eradication pending period can be terminated, and space reclamation initiated immediately by calling purevol eradicate on the undo snapshot.

Destroying Volumes

When the data stored in a volume is no longer of interest, the purevol destroy command obliterates the data it contains and frees the storage it occupies. Destroyed volumes become invisible to hosts and to most CLI and GUI displays immediately, but their data is not obliterated, nor is the storage it occupies reclaimed until a 24-hour eradication pending period has elapsed. During this period, a destroyed volume can be recovered with its data intact. The purevol eradicate command terminates the eradication pending period and begins storage reclamation immediately. Once eradication has begun, a volume can no longer be recovered.

Example 5 illustrates the use of the purevol destroy command.

Example 5. Destroying Volumes

$ purevol list --connect vol1 1
Name Size LUN Hgroup Host
vol1 100G 1          host1
$ purevol destroy vol1 2
Error on vol1: Cannot destroy volume because it is currently connected.
$ purevol disconnect --host host1 vol1
Name Hgroup Host
vol1        host1
root@gt2-ct0:~# purevol destroy vol1 3
Name
vol1
$ purevol list 4
Name  Size  Serial
vol2  200G  27CA508DA38AF9F400010001
vol3  300G  27CA508DA38AF9F400010002
vol4  300G  27CA508DA38AF9F400010003
$ purevol list --pending 5
Name  Size  Time Remaining  Source  Created               Serial
vol1  100G  1 day, 0:00:00  -       2013-04-01 15:45 PDT  27CA508DA38AF9F400010000
vol2  100G  -               -       2013-04-01 15:46 PDT  27CA508DA38AF9F400010001
vol3  100G  -               -       2013-04-01 15:47 PDT  27CA508DA38AF9F400010002
vol4  100G  -               -       2013-04-01 15:48 PDT  27CA508DA38AF9F400010003
        

1

As background, illustrates that vol1 is connected to host1

2

Attempt to destroy vol1 fails, because it has a connection.

3

After vol1's connection to host1 is broken, the purevol destroy command succeeds.

4 5

Illustrates that a volume in the eradication pending state (vol1) is only displayed by the purevol list command, when the --pending option is specified.


Recovering and Eradicating Destroyed Volumes

To provide a margin of error for administrators, Purity retains a volume's contents and structure for 24 hours after it is destroyed. The purevol recover command restores a destroyed volume to its size at the time of destruction with its contents intact, as Example 6 illustrates.

Example 6. Recovering and Eradicating Volumes

$ purevol destroy vol1
Name
vol1
$ purevol list --pending vol1
Name  Size  Source  Time Remaining  Created               Serial
vol1  100G  -       1 day, 0:00:00  2013-04-12 15:45 PDT  27CA508DA38AF9F400010004
$ purevol recover vol1 1
Name
vol1
$ purevol list vol1
Name  Size  Source  Created               Serial
vol1  100G  -       2013-04-12 15:45 PDT  27CA508DA38AF9F400010004
$ purevol destroy vol2
Name
vol2
$ purevol eradicate vol2 2
Name
vol2
$ purevol recover vol2 3
Error on vol2: Volume does not exist.
        

1

Restores destroyed volume vol1 (provided that the command executes within the volume's eradication pending period).

2

Obliterates the data from destroyed volume vol2, and begins reclamation of the storage it had occupied.

3

Fails to recover vol2, illustrating that once it is eradicated, a volume can no longer be recovered.


Renaming Volumes

Volume names identify volumes in CLI and GUI commands and displays. Volume names are assigned at creation, and, as with other objects can be changed at any time by the purevol rename command, as Example 7 illustrates. Renaming a volume has no effect on its attributes or connections.

Example 7. Renaming Volumes

$ purevol rename vol4 NewVol4
Name
NewVol4
$ purevol list vol4
Error on vol4: Volume does not exist.
$ purevol list NewVol4
Name     Size  Source  Created               Serial
NewVol4  300G  -       2013-04-12 15:48 PDT  27CA508DA38AF9F400010003
        

The name of vol4 is changed to NewVol4. The purevol list commands that follow illustrate that after renaming, a volume is is immediately visible under its new name, and is no longer visible under its former name. All attributes, including the volume serial number, which is visible to hosts, remain unchanged.


Ongoing Administration of Hosts

Purity host administration includes the following tasks:

  • Creation, deletion and renaming of host objects

  • Connecting hosts to and disconnecting them from volumes

  • Changing the Fibre Channel WWNs or iSCSI IQNs associates with a host

  • Adding hosts to and removing them from from host groups.

Example 2 illustrates host creation.

Example 3 illustrates both connection of multiple volumes to a single host (purevol connect) and multiple hosts to a single volume (purehost connect).

Example 8 illustrates the remaining host operations.

Example 8. Administrative Operations on Hosts

$ purehgroup listobj --type host hgroup1 1
host1
host2
$ purehost list --connect host1 2
Name   LUN  Vol  Host Group
host1  1    vol1
$ purehost delete host1 3
Error on host1: Could not delete host.
$ purehgroup setattr --remhost host1 hgroup1
Name     Hosts
hgroup1  host1
$ purehost delete host1 4
Error on host1: Could not delete host.
$ purehost disconnect --vol vol1 host1 5
Name   Vol
host1  vol1
$ purehost delete host1
Name
host1
      

1 2

These commands illustrate that host1 is associated with host group hgroup1, and has a private connection to vol1.

3

Attempt to delete host1 fails because it is associated with a host group.

4

After host1 is removed from hgroup1, the attempt to delete it still fails because it is still connected to volume vol1.

5

Deletion of host1 succeeds because it is not associated with a host group and has no private connections to volumes.


Monitoring I/O Performance

The purevol monitor command produces periodic displays of I/O performance information for some or all of an array's volumes, as Example 9 illustrates. Use purehost monitor, purehgroup monitor, and purearray monitor commands to display I/O performance information for host, host group, or the whole array.

Example 9. Monitoring I/O Performance

$ purevol monitor --interval 1 --repeat 3 --total
Name    Time                     B/s (read) B/s (write) op/s (read) op/s (write) us/op (read) us/op (write)
vol1    2014-08-15 13:23:19 PDT  3.16M      1.51M       808         386          119          155
vol2    2014-08-15 13:23:19 PDT  1.53M      1.58M       392         405          93           156
(total) 2014-08-15 13:23:19 PDT  4.69M      3.09M       1K          791          110          156
Name    Time                     B/s (read) B/s (write) op/s (read) op/s (write) us/op (read) us/op (write)
vol1    2014-08-15 13:23:20 PDT  3.23M      1.47M       828         376          117          154
vol2    2014-08-15 13:23:20 PDT  1.57M      1.63M       401         417          92           153
(total) 2014-08-15 13:23:20 PDT  4.80M      3.10M       1K          793          109          154
Name    Time                     B/s (read) B/s (write) op/s (read) op/s (write) us/op (read) us/op (write)
vol1    2014-08-15 13:23:21 PDT  3.05M      1.55M       780         398          119          155
vol2    2014-08-15 13:23:21 PDT  1.57M      1.53M       401         391          91           157
(total) 2014-08-15 13:23:21 PDT  4.61M      3.08M       1K          789          109          156
      

The --interval option specifies the number of seconds between displays of data. The --repeat option specifies the number of displays that the command produces. The default interval is 5 seconds; the default repetition count is 1.

Displays read and write operations and data transfer performance for volumes vol1 and vol2 with totals. Three sets of results are produced (--repeat 3) at intervals of one second (--interval 1).


Using listobj Output

The shell in which the Purity CLI runs supports command substitution, the embedding of a list-type inner command within an outer command, so that the output of the inner command becomes the argument list for the outer one. The listobj subcommands of the purehost, purehgroup, purevol, and purealert commands are included in the CLI primarily for this purpose.

The output of an embedded command becomes input to the command in which it is embedded. This feature can be used, for example, to operate on selected sets of objects, as Example 10 illustrates.

Example 10. Using the Output of the listobj Subcommand

purevol list $(purehost listobj --type vol HOST1 HOST2)
Name             Size   Source  Created                  Serial
vol35            4T     -       2013-09-03 16:47:18 PDT  64939A0301530F5400010050
vol57            6T     -       2013-11-04 16:42:23 PST  64939A0301530F5400010054
vol58            3T     -       2013-02-25 13:42:16 PST  64939A0301530F5400010045
vol634           4000G  -       -                        64939A0301530F540001001B
vol659           3T     -       2013-02-25 13:48:46 PST  64939A0301530F5400010046
vol1324          4000G  -       -                        64939A0301530F540001001A
vol256           4T     -       -                        64939A0301530F5400010024
      

In the above example, the inner purehost listobj command produces a whitespace-separated list of the volumes connected to HOST1 and HOST2. The outer purevol list command displays the names, sizes, and serial numbers of the volumes specified in the inner command.


Administrators can also use shell scripting to construct sequences of commands dynamically. Example 11 illustrates one use of scripting.

Example 11. Shell Scripting with the listobj Subcommand

$ BASENAME=VOL
$ for I in 100 150 200
> do
> purevol create --size $I\g $BASENAME$I\GB
> purevol connect --host host1 $BASENAME$I\GB
> done
Name      Size  Source  Created               Serial
VOL100GB  100G  -       2013-04-12 15:57 PDT  1B4B44F7DEAFEF5000010010
Name      Host Group  Host   LUN
VOL100GB  -           host1  3
Name      Size  Source  Created               Serial
VOL150GB  150G  -       2013-04-12 15:57 PDT  1B4B44F7DEAFEF5000010011
Name      Host Group  Host   LUN
VOL150GB  -           host1  4
Name      Size  Source  Created Serial
VOL200GB  200G  -       2013-04-12 15:57 PDT  1B4B44F7DEAFEF5000010012
Name      Host Group  Host   LUN
VOL200GB  -           host1  5
      

The purevol create command within the loop creates three volumes whose names are keyed to their sizes: Vol100GB has a size of 100 gigabytes, etc. The purevol connect command, also within the loop, connects each newly-created volume to host1 in turn.


Example 12 demonstrates another way to use the listobj subcommand to build an argument list.

Example 12. Building Arguments with the listobj Subcommand

$ for VOLNAME in $(purehost listobj --type vol host1)
> do
> purevol disconnect --host host1 $VOLNAME
> purevol truncate --size 80g $VOLNAME
> purevol destroy $VOLNAME
> purevol eradicate $VOLNAME
> done
Name      Host Group  Host
VOL100GB  -           host1
Name      Size  Serial
VOL100GB  80G   1B4B44F7DEAFEF5000010015
Name
VOL100GB
Name
VOL100GB
Name      Host Group  Host
VOL150GB  -           host1
Name      Size  Serial
VOL150GB  80G   1B4B44F7DEAFEF5000010016
Name
VOL150GB
Name
VOL150GB
Name      Host Group  Host
VOL200GB  -           host1
Name      Size  Serial
VOL200GB  80G   1B4B44F7DEAFEF5000010017
Name
VOL200GB
Name
VOL200GB
      

The purehost listobj command creates a whitespace-separated list of volumes that have private connections to host1. The list becomes the set of objects for which the do loop iterates. The four commands within the loop use the volume names to disconnect, truncate, destroy, and eradicate each of the volumes in succession.