Skip to main content
Pure1 Support Portal

pureman

Name

pureman — displays man pages for Purity commands

Synopsis

pureman { pureadmin | purealert | purearray | purecert | pureconfig | puredns | puredrive | pureds | purehgroup | purehost | purehw | purelicense | purelog | pureman | puremessage | purenetwork | purepgroup | pureplugin | pureport | puresmis | puresnmp | purevol }

Description

Enter the command pureman with one of the arguments listed in the synopsis to display the man page for that Purity command.

Help on Purity subcommands is also supported.

Enter the subcommand preceded with a hyphen. For example:

pureman purevol-list
      

CLI Conventions

The following list describes the conventions used in CLI help documentation:

  • Text in fixed-width (Courier) font must be entered exactly as shown. For example, purehost list.

  • Text not enclosed in brackets represents mandatory text.

  • Text inside square brackets (“[ ]”) represents optional items. Do not type the brackets.

  • Text inside curly braces (“{ }”) represents text, where one (and only one) item must be specified. Do not type the braces.

  • The vertical bar (|) separates mutually exclusive items.

  • Uppercase italic text represents entered text whose value is based on the nature of the subcommand or option. For example, --size SIZE, where SIZE represents the value to be entered, such as 100g.

CLI Command Syntax

Purity CLI commands have the general form:

command subcommand --options OBJECT-LIST
        

The parts of a command are:

COMMAND

Type of FlashArray object to be acted upon, prefixed by "pure". For example, the purevol command acts on Purity virtual storage volumes.

Run the purehelp command to see a list of Purity CLI commands.

SUBCOMMAND

Action to be performed on the specified object. Most CLI subcommands are common to some or all object types.

For example, purehost list lists all hosts on the array, while purevol list lists all volumes on the array.

The following subcommands are common to most or all object types:

create

Creates and names one or more FlashArray objects.

delete

Deletes one or more specified objects.

list

Lists information about one or more objects. To list information for all objects, do not specify the object in the command.

listobj

Creates whitespace-separated lists of objects or attributes related to one or more objects. For example, purevol listobj --type host creates a list of the hosts to which volumes have connections. The listobj subcommand is primarily used to create lists of object and attribute names for scripting purposes.

rename

Changes the name of the specified object. Purity identifies the object name in administrative operations and displays. The new name is effective immediately and the old name is no longer recognized in Purity GUI and CLI interactions. In the Purity GUI, the new name appears upon page refresh. Hardware object names cannot be changed.

setattr

Changes the attribute values of the specified objects.

OPTIONS

Options that specify attribute values or modify the action performed by the subcommand.

For example, in the following command, the --addvollist option adds volumes VOL1, VOL2, and VOL3 to protection group PGROUP1:

purepgroup setattr --addvollist VOL1,VOL2,VOL3 PGROUP1
                

Some options, such as --hostlist, inherently apply only to a single object. Other options, such as --size, can be set for multiple objects in a single command.

Some options can be multi-valued. For example, in the following command, the --hostlist option associates multiple hosts (HOST1, HOST2, and HOST3) with the host group HGROUP1.

purehgroup setattr --hostlist HOST1,HOST2,HOST3 HGROUP1
                

OBJECT-LIST

Object or list of objects upon which the command is to be operated.

If a subcommand changes the object state, then at least one object must be specified. Examples of subcommands that change the object state include create, delete, and setattr. For example, purehost create HOST1 creates host HOST1. In the command synopses, OBJECT specifications that are not enclosed in square brackets (for example, "HOST") represent ones that are required.

Passive subcommands, such as list, which do not change object state, do not require object specification. Leaving out the object is equivalent to specifying all objects of the type. For example, purevol list with no volumes specified displays information about all volumes in an array. In the command synopses, OBJECT specifications enclosed in square brackets (for example, "[HOST]") represent ones that are optional.

Most subcommands act on a single object. For example, in the following command, the setattr subcommand can only be run on a single host group to change the attributes of that host group.

purehgroup setattr --addhostlist HOST1 HGROUP1
                

Certain subcommands can operate on multiple objects. For example, the following command connects volume VOL1 to host groups HGROUP1 and HGROUP2.

purehgroup connect --vol VOL1 HGROUP2 HGROUP2
                

In the command synopses, OBJECT specifications that are followed by ellipses (for example, HGROUP...) indicate that multiple objects can be entered.

CLI Output

Various Purity CLI subcommands, including list and monitor, generate list outputs. With the ability to create and manage hundreds of volumes and snapshots, list outputs can become very long.

The Purity CLI includes options to control the way a list output is displayed and formatted. The CLI also includes sort, filter, and limit options to control the results you see and the order in which you see them.

Interactive Paging

Pagination divides a large output into discrete pages. Pagination is disabled by default and is only in effect if the --page option is specified and the number of lines in the list output exceeds the size of the window.

To interactively move through a paginated list output:

  • Press the [Right Arrow] key or space bar to move to the next page.

  • Press the [Left Arrow] key to move to the previous page.

To quit interactive paging and exit the list view, press q .

With pagination, each page of the CLI list output begins with the column titles. To suppress the column titles, run the command with the --notitle option.

Using Wildcards

The asterisk (*) symbol denotes a wildcard character used in list or monitor operations to represent zero or more characters in an object name. The object name can include multiple asterisks.

When performing a list or monitor operation, include the asterisk in the name argument to expand the list results. For example, the purehost list *cat* command displays a list of all hosts that contain "cat", such as cat, catnap, happycats, and lolcat. If the asterisks were not included, only the host named cat would be returned. As another example, the purevol list *vol* command displays a list of all volumes that contain "vol", including ones that begin or end with "vol".

$ purevol list *vol*
Name      Size  Source  Created
Myvol     100G  -       2016-04-11 10:18:07 PDT
MyVol-01  100G  -       2016-04-11 10:18:07 PDT
vol       1G    -       2016-04-11 11:19:19 PDT
vol01     100G  -       2016-04-11 10:17:23 PDT
Volume    100G  -       2016-04-11 10:17:23 PDT
        

If Purity cannot find matches for the wildcard argument specified, an error message appears.

Asterisks are also allowed in Purity CLI options that take a list of object names. For example, the purevol list --snap --pgrouplist *pg* command displays a list of all volume snapshots that are created as part of a protection group snapshot with "pg" in the protection group name. As another example, the following command displays a list of volume snapshots for all volumes that end with "01" and are created as part of a protection group snapshot with "pg" in the protection group name.

$ purevol list --snap --pgrouplist *pg* *01
Name                    Size  Source  Created
pgroup01.001.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.123.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.abc.vol01      100G  vol01   2016-04-13 11:44:46 PDT
pgroup01.backup.vol01   100G  vol01   2016-04-13 11:44:45 PDT
pgroup01.snap001.vol01  100G  vol01   2016-04-13 11:44:45 PDT
pgroup01.snap002.vol01  100G  vol01   2016-04-13 11:44:42 PDT
pgroup01.suffix.vol01   100G  vol01   2016-04-13 11:44:46 PDT
        

Formatting

Format options control the way list outputs are displayed. The following format options are common to most list and monitor subcommands:

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

Here is a comparison between the purehost list output with formatted column titles and data, and the same output with unformatted column titles and data:

$ purehost list --space
Name  Size  Thin Provisioning  Data Reduction  ...
H001  60T   57%                1.5 to 1        ...

$ purehost list --space --raw
name  size            thin_provisioning  data_reduction  ...
H001  65970697666560  0.5712341          1.5123          ...

Sorting

When running a list or monitor operation, include the --sort option to sort a column of the output in ascending or descending order. The following commands support the --sort option: purehgroup, purehost, purepgroup, pureport, and purevol.

The sort option adheres to the following syntax:

--sort SORT

SORT represents a comma-separated list of columns to sort. Use the unformatted title name (--raw) of the column to represent each column listed. To sort a column in descending order, append the minus (-) sign to the column name.

For example, run the following commands to get the unformatted column titles in the purehost list output, and then sort the same output by host group in descending order:

$ purehost list --raw
name                       ...  hgroup
ESXi-GRP-Cluster02-H0001   ...  ESXi-GRP-Cluster02-HG003
ESXi-GRP-Cluster02-H0002   ...  ESXi-GRP-Cluster02-HG003
ESXi-IT-Cluster01-H0001    ...  ESXi-IT-Cluster01-HG001
ESXi-IT-Cluster02-H0001    ...  ESXi-IT-Cluster02-HG002
ESXi-STG-Cluster03-H0001   ...  ESXi-STG-Cluster03-HG005

$ purehost list --sort hgroup-
Name                       ...  Host Group
ESXi-STG-Cluster03-H0001   ...  ESXi-STG-Cluster03-HG005
ESXi-IT-Cluster02-H0001    ...  ESXi-IT-Cluster02-HG002
ESXi-IT-Cluster01-H0001    ...  ESXi-IT-Cluster01-HG001
ESXi-GRP-Cluster02-H0002   ...  ESXi-GRP-Cluster02-HG003
ESXi-GRP-Cluster02-H0001   ...  ESXi-GRP-Cluster02-HG003

If multiple columns are specified, the output is sorted by the order of the columns listed.

If a sorted column contains non-unique values and a secondary sort argument is not specified, Purity automatically performs a secondary sort using the default sort criteria (typically by Name).

Examples

Example 1: Display a list of volumes sorted in descending order by physical space occupied.

$ purevol list --space --sort "total-"

Example 2: Display a list of protection groups sorted in ascending order by source array name.

$ purepgroup list --sort "source"

Example 3: Display a list of volumes that are sorted in descending order by volume size. If any of volumes are identical in size, sort those volumes in descending order by physical space occupied.

$ purevol list --space --sort size-,total-

Filtering

When running a list or monitor operation, include the --filter option to narrow the results of the output to only the rows that meet the filter criteria. The following commands support the --filter option: purehgroup, purehost, purepgroup, pureport, and purevol. Filtering can be performed on any column of the list output.

Filtering with Operators

When filtering with operators, use the following syntax:

--filter "RAW_TITLE OPERATOR VALUE"

RAW_TITLE represents the unformatted title name of the column by which to filter. Run the list or monitor operation with the --raw option to get the unformatted title name.

OPERATOR represents the type of filter match (=, !=, <, >, <=, or >=) used to compare RAW_TITLE to VALUE.

VALUE represents the value (number, date, or string) that determines the results to be included in the list output. Literal strings must be wrapped in quotes.

Filtering supports the following operators:

OperatorDescription
=Equals
!=Does not equal
<Less than
>Greater than
<=Less than or equal to
>=Greater than or equal to

Filtering supports the asterisk wildcard character. For example, the value "*esx*" in the purepgroup list --filter "hosts=*esx*" command displays a list of all protection groups with hosts members that contain "esx" in the host name.

The AND and OR operators can be used to further refine your filter. The AND operator displays only the results that meet all of the filter criteria in the command. The OR operator displays the results that meet at least one of the filter criteria in the command.

Examples

Example 1: Display a list of protection groups configured on source array pure-001.

$ purepgroup list --filter "source = 'pure-001'"

Example 2: Display a list of volumes that were created on or before 2016-05-23 13:09:39.

$ purevol list --filter "created <= '2016-05-23 13:09:39 PDT'"

Example 3: Display a list of volume snapshots that are greater than 2 gigabytes in size.

$ purevol list --space --snap --filter "snapshots > '2G'"

Example 4: Display a list of volumes that are currently inactive.

$ purevol monitor --filter "output_per_sec=0 and input_per_sec=0"

Example 5: Display a list of volumes that begin with "vol10" or are greater than 100 gigabytes in size.

$ purevol list --filter "name = 'vol0*' or size > '100G'"

Filtering with Functions

The filter option supports the CONTAINS and NOT functions.

--filter FUNCTION(PARAMETERS)

FunctionDescription
contains(raw_title,string)

Contains the enclosed string.

Takes exactly two parameters, where raw_title represents the unformatted title name of the column by which to filter and string represents the string to search within the column. Run the list or monitor operation with the --raw option to get the unformatted title name.

not(expression) Inverse of the enclosed expression.

Examples

Example 1: Get a list of all volumes that include "cluster03" in the volume name.

$ purevol list --filter "contains(name, 'cluster03')"

Example 2: Get a list of all hosts that are associated with host groups with "PROD" in the host group name.

$ purehost list --filter "contains(hgroup, 'PROD')"

Example 3: Get a list of all hosts that are not associated with host groups with "PROD" in the host group name.

$ purehost list --filter "not(contains(hgroup, 'GRP'))"

Existence Checks

The Purity CLI supports existence checks. For example, the purevol list --filter "name" command checks to see if the "name" column exists in the volume list output.

Examples

Example 1: Get a list of all hosts associated with a host group.

$ purehost list --filter "hgroup"

Example 2: Get a list of all volumes that were not created from another source.

$ purevol list --filter "not(source)"

Example 3: Get a list of all hosts that are not associated with Fibre Channel WWNs.

$ purehost list --filter "not(wwn)"

Setting Limits

When running a list or monitor operation, include the --limit option to restrict the result size to the limit specified. The following commands support the --limit option: purehgroup, purehost, purepgroup, pureport, and purevol.

The limit option adheres to the following syntax:

--limit ROWS

ROWS represents the maximum number of rows to return.

For example, run the following command to list only the first 5 rows of the purevol list output:

$ purevol list --limit 5
Name                   Size  Source  Created                  Serial
ESXi-Cluster01-vol001  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011021
ESXi-Cluster01-vol002  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B0001101D
ESXi-Cluster01-vol003  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011024
ESXi-Cluster01-vol004  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011018
ESXi-Cluster01-vol005  100G  -       2016-05-23 13:09:40 PDT  B143778B8ACE487B00011025

Combining Sorting, Filtering, and Limit Options

The --sort, --filter, and --limit options can all be combined together.

Examples

Example 1: Display the top 10 volumes that occupy the largest amount of physical space and include "esx" in the volume name.

$ purevol list --space --sort "total-" --limit 10 --filter "name = '*esx*'"

Example 2: Display the top 10 volumes that have the largest physical space occupied by data unique to one or more snapshots.

purevol list --space --sort "snapshots-" --limit 10

Example 3: Display the top 10 volumes with the highest data reduction ratios.

$ purevol list --space --sort "data_reduction-" --limit 10

Example 4: Display the top 10 volumes that use the most read bandwidth.

$ purevol monitor --sort "output_per_sec-" --limit 10

Example 5: Display the top 10 volumes with the largest provisioned sizes and have shared connections to host groups with "PROD" in the host group name.

$ purevol list --connect --filter "hgroup = '*PROD*'" --sort size- --limit 10

Examples

Example 1

pureman purehost
      

Displays the Purity man page for the purehost command.

Example 2

pureman purehost-connect
      

Displays the Purity man page for the purehost connect subcommand.

Related Command

The command purehelp displays a list of the available Purity commands.

Author

Pure Storage Inc.