Skip to main content
Pure1 Support Portal

purehgroup

Name

purehgroup, purehgroup-create, purehgroup-delete, purehgroup-rename, purehgroup-setattr — manage the creation, deletion, naming, and population of Purity host groups.

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

purehgroup-monitor — monitor host group I/O performance.

Synopsis

purehgroup create [--hostlist HOST-LIST] HGROUP...

purehgroup delete HGROUP...

purehgroup add --pgroup PGROUP HGROUP...

purehgroup remove --pgroup PGROUP HGROUP...

purehgroup monitor [--csv] [--filter FILTER] [--interval SECONDS] [--limit LIMIT] [--notitle] [--raw] [--repeat REPEAT-COUNT] [--size] [--sort SORT] [--total] [HGROUP...]

purehgroup rename OLD-NAME NEW-NAME

purehgroup setattr { --addhostlist HOST-LIST | --hostlist HOST-LIST | --remhostlist HOST-LIST } HGROUP

Arguments

HGROUP

Host group name.

NEW-NAME

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

OLD-NAME

Current name of the host group to be renamed.

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.

Options

-h | --help

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

--addhostlist

Comma-separated list of one or more additional hosts to be associated with the host group. Has no effect on hosts already associated with the group.

--hostlist

Comma-separated list of one or more hosts to be associated with the host group. When specified in the purehgroup setattr command, replaces the entire membership of a host group. To disassociate all hosts from a host group, set to an empty string ("").

--pgroup PGROUP

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

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

--remhostlist

Comma-separated list of one or more hosts whose associations with the host group are to be broken.

--repeat REPEAT-COUNT

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

--size

Displays the average I/O sizes per read and write operation.

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

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

A Purity host group is an abstraction that implements consistent connections between a set of hosts and one or more volumes. Connections are consistent in the sense that all hosts associated with a host group address a volume connected to the group by the same LUN. Host groups are typically used to provide a common view of storage volumes to the hosts in a clustered application.

Creating Host Groups

The purehgroup create command creates a host group and assigns it a name. Optionally, include the --hostlist option with the purehgroup create command to add hosts during host group creation.

Adding Hosts to Host Groups

Adding a host to a host group automatically connects the host to all volumes associated with the group. A host can only belong to one host group.

Hosts can be added to or removed from a host group at any time.

To add hosts to an existing host group, include the --addhostlist or --hostlist option with the purehgroup setattr command. The --addhostlist option adds hosts to an existing host group. Hosts that are already associated with the host group are not affected. The --hostlist option adds hosts to an existing host group, completely replacing any existing hosts that are already associated with the host group.

To remove hosts from a host group, run the purehgroup setattr --remhostlist command. Alternatively, remove hosts from a host group by running the purehgroup setattr --hostlist "" command to replace the existing list of hosts with a null set.

Creating Shared Host-Volume Connections

To connect the hosts within a host group to a volume, establish a shared connection by running the purehgroup connect or purevol connect --hgroup command. Shared connections can be created or broken at any time. Once a connection is established, the volume is assigned a logical unit number (LUN), which all hosts within the host group use to communicate with the volume.

For more information about shared connections and LUNs, refer to purehgroup-connect(1).

Deleting Host Groups

The purehgroup delete command removes host groups that are no longer required. A host group can only be deleted if it is empty, so remove all hosts from a host group before deleting the group.

Renaming Host Groups

Run the purehgroup rename command to change the current name (OLD-NAME) of a host 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.

Adding Host Groups to Protection Groups

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

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

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

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

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

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

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

Host Group I/O Performance Monitoring

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

  • Name: Host group 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.

Include the --repeat option to specify the number of times to repeat the real-time update. If not specified, the repeat value defaults to 1. Include the --interval option to specify the number of seconds between each real-time update. At each interval, the system displays a point-in-time snapshot of the performance data. If not specified, the interval value defaults to every 5 seconds. The --interval and --repeat options can be combined.

Exceptions

Purity will not create a host group if:

  • A host group with the specified name already exists in the array.

  • The creation of the host group would exceed the limit of concurrent host groups.

Purity will not delete a host group if:

  • Any hosts are associated with the host group or any volumes are connected to it.

A host cannot be added to a host group if:

  • The host is associated with another host group. A host can only be associated with one host group at a time.

  • The host has a private connection to a volume associated with the host group.

Examples

Example 1

purehost create --wwnlist 0123456789abcde6,0123456789abcde7 HOST6
purehost create --wwnlist 0123456789abcde8,0123456789abcde9 HOST7
purevol  create --size 100g VOL1 VOL2 VOL3 VOL4
purehgroup create --hostlist HOST6,HOST7 HGROUP3
purehgroup connect --vol VOL1 HGROUP3
purehgroup connect --vol VOL2 HGROUP3
purehgroup connect --vol VOL3 HGROUP3
purehgroup connect --vol VOL4 --lun 25 HGROUP3
      

Typical usage of the purehgroup create command. Creates hosts HOST6 and HOST7. Creates 100 gigabyte volumes VOL1, VOL2, VOL3, and VOL4. Creates host group HGROUP3 and associates HOST6 and HOST7 with it. Connects VOL1, VOL2, VOL3, and VOL4 to HGROUP3. Purity automatically assigns LUNs to volumes VOL1, VOL2, and VOL3 by counting down from 254 and assigning the first available numbers to each of the respective volumes. If available, LUN 25 is assigned to VOL4. Both hosts communicate with the volumes via the same LUNs.

Example 2

purehgroup create --hostlist HOST1,HOST2,HOST3 HGROUP1
      

Creates host group HGROUP1 and associates hosts HOST1, HOST2, and HOST3 with it. No volumes are connected to the group at the time of creation.

Example 3

purehgroup create HGROUP2
      

... time passes...

purehgroup connect --vol VOL1 --lun 11 HGROUP2
      

... more time passes...

purehgroup setattr --addhostlist HOST4,HOST5 HGROUP2
      

Creates host group HGROUP2, but does not associate any hosts with it. At a later time, VOL1 is connected to the group, with LUN 11 assigned to it. Still later, HOST4 and HOST5 are associated with HGROUP2, causing Purity to establish shared connections between them and VOL1, using LUN 11 for communication.

Example 4

purehgroup monitor --repeat 60 HGROUP1
      

Displays real-time performance data for host group HGROUP1. Sixty (60) updates are displayed, with each point-in-time update taken at the default interval of every five (5) seconds.

Example 5

purehgroup setattr --host "" HGROUP2
purehgroup delete HGROUP2
      

Removes all hosts from HGROUP2 and deletes the host group.

Author

Pure Storage Inc.