Skip to main content
Pure1 Support Portal

purehost

Name

purehost, purehost-create, purehost-delete, purehost-rename, purehost-setattr — manage creation, deletion, naming, and attributes of the Purity hosts used to identify computers ("hosts") that use FlashArray storage services

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

purehost-monitor — monitor host I/O performance

Synopsis

purehost create [--iqnlist IQN-LIST] [--wwnlist WWN-LIST] HOST...

purehost delete HOST...

purehost add --pgroup PGROUP HOST...

purehost remove --pgroup PGROUP HOST...

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

purehost rename OLD-NAME NEW-NAME

purehost setattr { --addiqnlist IQN-LIST | --addwwnlist WWN-LIST | --host-password | --host-user HOST-USER | --iqnlist IQN-LIST | --personality PERSONALITY | --remiqnlist IQN-LIST | --remwwnlist WWN-LIST | --target-password | --target-user TARGET-USER | --wwnlist WWN-LIST } HOST

Arguments

HOST

Host name.

NEW-NAME

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

OLD-NAME

Current name of the host 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.

--addiqnlist

Adds the iSCSI qualified names (IQNs) in the comma-separated list to those already associated with the specified host.

--addwwnlist

Adds the Fibre Channel worldwide names (WWNs) in the comma-separated list to those already associated with the specified host.

--balance

Displays I/O balance details.

--host-password

Sets the host password for CHAP authentication. The CLI prompts for the password interactively.

--host-user

Sets the host username for CHAP authentication.

--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 used with the --balance option, sets the interval at which I/O balance details are logged. Each I/O balance update consists of the I/O statistics collected during the entire interval.

If omitted, the interval defaults to every 5 seconds.

--iqnlist

Comma-separated list of one or more iSCSI qualified names (IQNs) to be associated with the specified host. In the purehost setattr command, this option replaces all IQNs previously associated with the specified host with those in the list.

--personality

Determines the way in which the host personality tunes the protocol used between the array and the initiator. If the host is running the HP-UX operating system, set the host personality to hpux.

--pgroup PGROUP

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

--remiqnlist

Disassociates the iSCSI qualified names (IQNs) in the comma-separated list from the specified host.

--remwwnlist

Disassociates the Fibre Channel worldwide names (WWNs) in the comma-separated list from the specified host.

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

--target-password

Sets the target password for CHAP authentication. The CLI prompts for the password interactively.

--target-user

Sets the target username for CHAP authentication.

--total

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

--wwnlist

Comma-separated list of one or more Fibre Channel worldwide names (WWNs) to be associated with the specified host. In the purehost setattr command, this option replaces all WWNs previously associated with the specified host with those in the list.

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

The host is the abstraction used by Purity to organize the storage network addresses (Fibre Channel worldwide names or iSCSI qualified names in the current release) of client computers and to control communications between clients and volumes. The host's only attributes are lists of one or more Fibre Channel worldwide names (WWNs) or iSCSI qualified names (IQNs) that identify the host's initiators.

Creating Hosts

The purehost create command creates a host and optionally associates one or more WWNs or IQNs with it.

To add WWNs or IQNs to a host during host creation, include the respective --wwnlist or --iqnlist option with the purehost create command.

Associating WWNs and IQNs with Hosts

The host cannot communicate with the array until at least one WWN or IQN has been associated with it.

WWNs and IQNs can be added to or removed from a host at any time.

To add WWNs or IQNs to an existing host, include the respective --addwwnlist or --addiqnlist option with the purehost setattr command. WWNs or IQNs that are already associated with the host are not affect.

To add WWNs or IQNs to an existing host, completely replacing the WWNs or IQNs that are currently associated with the host, include the respective --wwnlist or --iqnlist option with the purehost setattr command.

To remove WWNs or IQNs from an existing host, include the respective --remwwnlist or --remiqnlist option with the purehost setattr command.

Once the WWNs or IQNs have been specified, enable communication between the host and volumes by establishing connections, either private or shared, between the two.

Creating Host-Volume Connections

After a host has been created and the WWNs or IQNs have been specified, establish a connection, either private or shared, between the host and volumes. Host-volume connections can be established or broken at any time.

To establish a private connection, run the purehost connect or purevol connect --host command. To establish a shared connection, run the purehgroup connect or purevol connect --hgroup command.

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

Deleting Hosts

The purehost delete command removes hosts that are no longer required. A host cannot be deleted while it has connections to volumes, either private or shared.

Renaming Hosts

Run the purehost rename command to change the current name (OLD-NAME) of a host 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 Hosts to Protection Groups

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

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

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

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

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

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

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

Host I/O Performance and I/O Balance Monitoring

The purehost monitor command displays real-time I/O performance and I/O balance information for all or specified hosts. The purehost monitor displays I/O performance information, including the following data about bandwidth, IOPS, and latency:

  • Name: Host 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 --interval option to specify the number of seconds between each point-in-time update. Include the --repeat option to specify the number of times to repeat the update. The --interval and --repeat options can be combined.

The purehost monitor --balance command displays the I/O counts on each path between the host and the controller. Ideally, I/O counts on all the host paths should be as close to each other as possible. The purehost monitor --balance output includes the following I/O balance data:

  • Name: Host name

  • Time: Current time

  • Initiator WWN: Fibre Channel initiator port name

  • Initiator IQN: iSCSI initiator port name

  • Target: For WWN, target Fibre Channel component name. For IQN, target primary or secondary controller.

  • Target WWN: Target WWN port name. Only applies to WWN.

  • Failover: Port to which this array port has failed over. The port name only appears if the array port has failed over.

  • I/O Count: I/O count for the host path.

  • I/O Relative to Max: Percentage of I/O counts for this path relative to the path with highest number of I/O counts. The path with the highest number of I/O counts is displayed with an I/O Relative to Max percentage of 100%. The percentage values of all other paths in the host are then calculated relative to the path with the highest number of I/O counts.

The --interval and --repeat options can be used with the --balance option. Include the --interval option to set the interval at which I/O balance details are logged. Each I/O balance update consists of the I/O statistics collected during the entire interval. Include the --repeat option to specify the number of times to repeat the update.

Exceptions

Purity will not create a host if:

  • The specified name is already associated with another host in the array.

  • Any of the specified WWNs or IQNs is already associated with an existing host in the array.

  • The creation of the host would exceed the limit of concurrent hosts, or the creation of the WWN or IQN would exceed the limit of concurrent initiators.

Purity will not delete a host while it has connections to volumes, either private or shared.

Purity will not associate a WWN or IQN with a host if:

  • The creation of the WWN or IQN would exceed the maximum number of concurrent initiators.

  • The specified WWN or IQN is already associated with another host on the array.

Hosts are configured through the Purity GUI (Storage tab) and Purity CLI (purehost command).

Examples

Example 1

purehost create HOST1
      

Creates a host called HOST1. HOST1 cannot be connected to volumes or associated with a host group until at least one WWN has been associated with it.

Example 2

purehost create --wwnlist 0123456789abcde1,0123456789abcde2 HOSTFC
purehost create --iqnlist iqn.2001-04.com.example:diskarrays-sn-a8675309 HOSTISCSI
      

Creates a host called HOSTFC and associates WWNs 01:23:45:67:89:ab:cd:e1 and 01:23:45:67:89:ab:cd:e2 with it.

Creates a second host called HOSTISCSI and associates IQN iqn.2001-04.com.example:diskarrays-sn-a8675309 with it.

Example 3

purehost delete HOST5
      

Deletes host HOST5. HOST5's private connections and host group association (if any) must previously have been broken.

Example 4

purehost add --pgroup PGROUP1,PGROUP2 HOST1 HOST2
      

Adds hosts HOST1 and HOST2 to protection groups PGROUP1 and PGROUP2, respectively.

Example 5

purehost monitor --repeat 60 --interval 10 HOST1
      

Displays real-time performance data for host HOST1. Sixty (60) point-in-time updates are displayed, with each update taken every ten (10) seconds.

Example 6

purehost monitor --balance
      

Displays I/O balance details for all hosts.

Example 7

purehost monitor --balance --repeat 2 --interval 2 host3
      

Displays I/O balance details for host host3 containing 2 seconds' worth of data with 2 seconds between each update.

Example 8

purehost setattr --wwnlist 0123456789abcdef,01:23:45:67:89:ab:cd:ee HOST3
      

Replaces all WWN previously associated with HOST3 with the two specified. This example also illustrates the two formats for entering WWNs.

Example 9

purehost setattr --remwwnlist 01:23:45:67:89:ab:cd:ed HOST4
purehost setattr --addwwnlist 0123456789abcdec,0123456789abcdeb HOST4
      

Disassociates WWN 01:23:45:67:89:ab:cd:ed from HOST4 and replaces it with 01:23:45:67:89:ab:cd:ec and 01:23:45:67:89:ab:cd:eb. Other WWNs associated with HOST4 are unaffected.

Author

Pure Storage Inc.