IBM::XCLI - A Perl interface to the IBM XIV XCLI
use IBM::XCLI; my $xiv = IBM::XCLI->new( ip_address => $ip_address, username => $user password => $password, xcli => $xcli ); my @volumes = $xiv->vol_list(); foreach (@volumes) { s/^"\|"$//g; my(@volume) = split /","/; print "Volume:\t$volume[0]\tSize:\t$volume[1]\tUsed:\t$volume[6]\n"; }
This module provides a simple object oriented interface to the IBM XIV XCLI utility.
The IBM XIV XCLI is a utility providing a command line interface to an IBM XIV storage array exposing complete management and administrative capabilities of the system.
This module provides a simple interface to the IBM XIV XCLI utility by providing convenient wrapper methods for a number of XCLI native method calls. These methods are named for and are analagous to their corresponding XCLI counterparts; for example, a call to the vol_list method exposed by this module returns the same data as would an execution of the native vol_list command would be expected to return.
The primary difference between the return value of method calls exposed by this module and the return value of native XCLI calls is that methods in this module using native method names return a nested hash rather than whitespace delimited or comma-separated data.
Note that if access to the raw data as returned by the XCLI native method call is required then the raw methods can be used to retrieve CSV data as retured directly from the XCLI. See the RAW METHODS section below for further details.
The XCLI utility must be installed on the same machine as from which the script is ran.
my $xiv = IBM::XCLI->new( ip_address => $ip_address, username => $user password => $password, xcli => $xcli );
Constructor method. Creates a new IBM::XCLI object representing a connection to and an instance of a XCLI connection to the target XIV unit.
Required parameters are:
The IP address of a management interface on the target XIV unit.
The username with which to connect to the target XIV unit.
The password with which to connect to the target XIV unit.
The path to the XCLI binary. This must be an absolute path to a local file for which the executing user has appropriate privileges.
This method is analagous to the native XCLI command 'host_list' and returns a nested hash containing the details of all configured hosts and indexed by host name. The hash has the following structure:
host-name-1 => { cluster => string, creator => string, fc_ports => comma-separated list of WWPNs, iscsi_ports => comma-separated list of WWPNs, iscsi_chap_secret => string, iscsi_chap_name => string, name => string, performance_class => string, type => string, user_group => string }, ... host-name-n => { ... }
This method is analagous to the native XCLI command 'pool_list' and returns a nested hash containing the details of all configured pools indexed by pool name. The hash has the following structure:
pool-name-1 => { create_last_consistent_snapshot => boolean, creator => string, empty_hard_space_gb => int, empty_hard_space_mib => int, empty_space_gb => int, empty_space_mib => int, hard_size_gb => int, hard_size_mib => int, lock_behavior => string, locked => boolean, name => string, protected_snapshots_priority => int, size_gb => int, size_mib => int, snapshot_size_gb => int, snapshot_size_mib => int, used_by_snapshots_gb => int, used_by_snapshots_mib => int, used_by_volumes_gb => int, used_by_volumes_mib => int }, ... pool-name-2 => { ... }
This method is analagous to the native XCLI command 'mirror_list' and returns a nested hash containing the details of all configured mirrors index by mirror name. The hash has the following structure:
mirror-name-1 => { active => boolean, designation => string, last_replicated => timestamp (YYYY-MM-DD HH:MM:SS), link_up => boolean, mirror_error => string, mirror_object => string, mirror_type => string, name => string-f, operational => boolean, remote_peer => string-f, remote_rpo => time (hh:mm:ss), remote_system => string, role => string, rpo => time (hh:mm:ss), schedule_name => string, size_to_sync_mb => signed int, status => string, sync_progress_percent => percent (range 0-100) }, ... mirror-list-n => { ... }
This method is analagous to the native XCLI command 'vol_list' and returns a nested hash containing the details of all configured volumes indexed by voluem name. The hash has the following structure:
vol-list-1 => { capacity_blocks => int, consistency_group => string, creator => vcuser, deletion_priority => int, locked => boolean, locked_by_pool => boolean, master_copy_creation_time => timestamp (YYYY-MM-DD HH:MM:SS),, master_name => int, mirrored => boolean, modified => boolean, name => string, pool => string, serial_number => int, short_live_io => boolean, size_gb => int, size_mib => int, snapshot_creation_time => timestamp (YYYY-MM-DD HH:MM:SS),, snapshot_format => boolean, snapshot_group_name => string, snapshot_of => string, snapshot_of_snap_group => string, used_capacity_gb => int, used_capacity_mib => int, vaai_disabled_by_user => boolean, vaai_enabled => boolean, wwn => WWN }, ... vol-list-n => { ... }
This method is analagous to the native XCLI command 'cluster_list' and returns a nested hash containing the details of all configured clusters index by cluster name. The hash has the following structure:
cluster-1 => { creator => string, hosts => comma-separated list of host names, name => string, type => string, user_group => string }, ... cluster-n => { ... }
This method is analagous to the native XCLI command 'target_list' and returns a nested hash containing the details of all configured targets index by target name. The hash has the following structure:
target-1 => { connected => boolean, connection_threshold => int, creator => string, iscsi_name => IQN, max_initialization_rate => percentage (range 0-100), max_resync_rate => int, max_syncjob_rate => int, name => string, number_of_ports => int, scsi_type => string, system_id => int, xiv_target => boolean } ... target-n => { ... }
This method is analagous to the native XCLI command 'dest_list' and returns a nested hash containing the details of all configured destinations indexed by destination name. The hash has the following structure:
dest-list-1 => { area_code => int, creator => string, email_address => email address, gateways => string, heartbeat_days => int, heartbeat_time => int, name => string, phone_number => phone number, snmp_manager => string, type => string, user => string }, ... dest-list-n => { ... }
This method is analagous to the native XCLI command 'snap_group_list' and returns a nested hash containing the details of all configured snap groups indexed by snap grop name. The hash has the following structure:
snap-group-1 => { cg => string, deletion_priority => int, locked => boolean, modified => boolean, name => string, snapshot_group_format => boolean, snapshot_time => timestamp (YYYY-MM-DD HH:MM:SS) }, ... snap-group-n => { ... }
This method is analagous to the native XCLI command 'ipinterface_list' and returns a nested hash containing the details of all configured IP interfaces indexed by IP interface name. The hash has the following structure:
ipinterface-1 => { default_gateway => IP address (A.B.C.D), ip_address => IP address (A.B.C.D), module => Module designation (e.g. 1:Module:1), mtu => int, name => string, network_mask => netmask (A.B.C.D), ports => int, type => string }, ... ipinterface-n => { ... }
This method is analagous to the native XCLI command 'target_port_list' and returns a nested hash containing the details of all configured target ports iSCSI IP address. The hash has the following structure:
target-port-1 => { active => boolean, iscsi_address => IP address (A.B.C.D), iscsi_port => int, port_type => string, target_name => string, wwpn => WWPN }, ... target-port-n => { ... }
This method is analagous to the native XCLI command 'reservation_key_list' and returns a nested hash containing the details of all configured reservation keys indexed by reservation key. The hash has the following structure:
reservation-key-1 => { initiator_port => WWPN, reservation_key => string, volume_name => string }, ... reservation-key-2 => { ... }
This method is analagous to the native XCLI command 'fc_port_list' and returns a nested hash containing the details of configured FC ports in the target unit. Note that FC ports are defined in this context as being FC ports physically belonging to the XIV unit.
The hash is indexed by FC port WWPN and has the following structure:
wwpn-1 => { active_firmware => string, component_id => component ID (1:FC_Port:1:1), configured_rate_gbaud => string, credit => int, current_rate_gbaud => int, currently_functioning => boolean, enabled => int, error_count => int, hba_vendor => string, link_type => string, maximum_supported_rate_gbaud => string, model => string, module => module ID (e.g. 1:Module:1), original_model => string, original_serial => string, port_id => string, port_number => int, port_state => string, requires_service => string, role => string, serial => string, service_reason => string, status => string, user_enabled => boolean, wwpn => WWPN }, ... wwpn-n => { ... }
This method is analagous to the native XCLI command 'fc_connectivity_list' and returns a nested hash containing the details of connected FC ports in the target unit. Note that FC ports are defined in this context as being FC ports physically belonging to the XIV unit.
wwwpn-1 => { component_id => connected component ID (e.g. 1:FC_Port:1:1), port_id => int, role => string, wwpn => WWPN }, ... wwwpn-n => { ... }
This method is analagous to the native XCLI command 'host_connectivity_list' and returns a nested hash containing all details of configured host ports in the target unit.
The hash is indexed by WWPN (the same as the value of 'host_port') and has the following structure:
wwpn-1 => { host => string, host_port => WWPN, local_fc_port => connected component ID (e.g. 1:FC_Port:1:1), local_iscsi_port => IQN, module => connected module ID (e.g. 1:Module:5), type => string }, ... wwpn-n => { ... }
This method is analagous to the native XCLI command 'ups_list' and returns a nested hash containing details of all UPSs (Untinterruptible Power Supplys) indexed by the UPS component identifier (the same as the value of component_id). The hash has the following structure:
ups-id-1 => { aos_version => string, apparent_load_percent_va => int, battery_charge_level => percentage (range 0-100), battery_week_born => signed int, battery_year_born => signed int, component_id => component ID (i.e. 1:UPS:1), component_test_status => string, currently_functioning => boolean, input_power_on => boolean, last_calibration_date => date (MM/DD/YYYY), last_calibration_result => string, last_self_test_date => date (MM/DD/YYYY), last_self_test_result => string, load_percent_watts => int, monitoring_enabled => boolean, next_self_test => timestamp (YYYY-MM-DD HH:MM:SS), original_serial => string, power_consumption => int, predictive_power_load_percent => int, predictive_remaining_runtime => int, requires_service => string, self-test_status => string, serial => string, service_reason => string, status => string, temperature => int, ups_manufacture_date => date (MM/DD/YYYY), ups_status => string, runtime_remaining => int ` }, ... ups-id-n => { ... }
This method is analagous to the native XCLI command 'psu_list' and returns a nested hash containing details of all PSUs (Power Supply Units) indexed by the PSU component identifier (the same as the value of component_id). The hash has the following structure:
psu-id-1 => { component_id => component ID (e.g. 1:PSU:1:1), currently_functioning => boolean, hardware_status => string, requires_service => string, service_reason => string, status => string }, ... psu-id-n => { ... }
This method is analagous to the native XCLI command 'ats_list' and returns a nested hash containing details of all ATSs (Automatic Transfer Switches) indexed by the ATS component identifier (the same as the value of component_id). The hash has the following structure:
ats-id-1 => { 3-phase => boolean, a_pick-up => boolean, b_pick-up => boolean, c_pick-up => boolean, d_pick-up => boolean, ats_connect_errors => int, ats_reply_errors => int, coil_a_on => boolean, coil_b_on => boolean, coil_c_on => boolean, coil_d_on => boolean, component_id => component ID (e.g. 1:ATS:1), currently_functioning => boolean, default_calibration => boolean, dual_active => boolean, firmware_j1_version => string, firmware_j2_version => string, firmware_version => string, interlock_failed => boolean, j1_source => boolean, j2_source => boolean, l1_input_ok => boolean, l2_input_ok => boolean, logic_power => boolean, no_oc_switching => boolean, outlet_1_state => string, outlet_2_state => string, outlet_3_state => string, output_10a => boolean, output_30a_no1 => boolean, output_30a_no2 => boolean, output_30a_no3 => boolean, over-current_j1_phase_a => boolean, over-current_j1_phase_b => boolean, over-current_j1_phase_c => boolean, over-current_j2_phase_a => boolean, over-current_j2_phase_b => boolean, over-current_j2_phase_c => boolean, p1_current_fault => boolean, p3_current_fault => boolean, p2_current_fault => boolean, requires_service => string, rms_current_outlet_p1 => int, rms_current_outlet_p3 => int, rms_current_outlet_p2 => int, serial_control => boolean, service_reason => string, status => string, us_type => boolean }, ... ats-id-n => { ... }
This method is analagous to the native XCLI command 'cf_list' and returns a nested hash containing details of all CFs (Compact Flash cards) indexed by the CF component identifier (the same as the value of component_id). The hash has the following structure:
cf-id-1 => { component_id => component ID (e.g. 1:CF:1:1, currently_functioning => boolean, device_name => string, hardware_status => string, original_part_number => string, original_serial => string, part_no => string, requires_service => string, serial => string, service_reason => string, status => string }, ... cf-id-n => { ... }
This method is analagous to the native XCLI command 'dimm_list' and returns a nested hash containing details of all DIMMS (Dual Inline Memory Modules) indexed by the DIMM component identifier (the same as the value of component_id). The hash has the following structure:
dimm-id-1 => { bank => int, channel => int, component_id => component ID (e.g. 1:DIMM:1:1), currently_functioning => boolean, hardware_status => string, manufacturer => string, original_part_number => string, original_serial => string, part_no => string, requires_service => string, serial => string, sizemb => int, speedmhz => int, status => string }, ... dimm-id-1 => { ... }
This method is analagous to the native XCLI command 'fan_list' and returns a nested hash containing details of all fans indexed by the fan component identifier (the same as the value of component_id). The hash has the following structure:
fan-id-1 => { component_id => component ID (e.g. 1:Fan:1:1), currently_functioning => boolean, requires_service => string, service_reason => string, status => string }, ... fan-id-n => { ... }
This method is analagous to the native XCLI command 'mm_list' and returns a nested hash containing details of all maintenance modules indexed by the maintenance module identifier (the same as the value of component_id). The hash has the following structure:
mm-id-1 => { component_id => component ID (e.g. 1:MaintenanceModule:1), currently_functioning => boolean, enabled => boolean, free_disk_/ => int, free_disk_/var => int, free_memory => int, linkno1 => boolean, linkno2 => boolean, original_serial => string, original_part_number => string, part_no => string, requires_service => string, service_reason => string, serial => string, status => string, temperature => string, total_memory => int, version => string }, ... mm-id-n => { ... }
This method is analagous to the native XCLI command 'switch_list' and returns a nested hash containing details of all switches indexed by the switch component identifier (the same as the value of component_id). The hash has the following structure:
switch-id-1 => { ac_power_state => string, component_id => component ID (e.g. 1:Switch:1), current_active_version => string, currently_functioning => boolean, dc_power_state => string, failed_fans => int, interconnect => string, original_serial => string, next_active_version => string, requires_service => string, serial => string, service_reason => string, status => string, temperature => int, temperature_status => string }, ... switch-id-n => { ... }
This method is analagous to the native XCLI command 'service_list' and returns a nested hash containing details of all component generic services indexed by the service component identifier (the same as the value of component_id). The hash has the following structure:
server-id-1 => { component_id => service component ID (e.g. 1:Data:1), currently_functioning => boolean, status => string, target_status => string }, ... service-id-n => { ... }
This method is analagous to the native XCLI command 'component_list' and returns a nested hash containing details of all system components indexed by the system component identifier (the same as the value of component_id). The hash has the following structure:
component-id-1 => { component_id => system component ID (e.g. 1:Data:9), currently_functioning => boolean, requires_service => string, service_reason => string, status => string }, ... component-id-n => { ... }
This method is analagous to the native XCLI command 'ethernet_cable_list' and returns a nested hash containing details of all Ethernet cables indexed by the system Ethernet cable identifier (the same as the value of component_id). The hash has the following structure:
ethernet-cable-1 => { component_id => Ethernet cable component ID (e.g. 1:Ethernet_Cable:6:8), connected_to => switchport component ID (e.g. 1:Switch:1:1), currently_functioning => boolean, interface_role => string, link_status => string, requires_service => string, service_reason => string, should_be_connected_to => switchport component ID (e.g. 1:Switch:1:1), status => string }, ... ethernet-cable-n => { ... }
This method is analagous to the native XCLI command 'fs_list' and returns a nested hash containing details of all file systems indexed by the file system module identifier (the same as the value of module_id). The hash has the following structure:
module-id-1 => { device => string, good => boolean, module_id => module identifier (e.g. 1:Module:1), mount_point => string, total_inodes => int, total_size => int, type => string, used_inodes => int, used_size => int, writable => boolean }, ... module-id-n => { ... }
This method is analagous to the native XCLI command 'cg_list' and returns a nested hash containing details of all consistency groups indexed by the consistency group name. The hash has the following structure:
consistency-group-name-1 => { mirrored => boolean, name => string, pool_name => string }, ... consistency-group-name-n => { ... }
This method is analagous to the native XCLI command 'rule_list' and returns a nested hash containing details of all event notification rules and indexed by the rule name. The hash has the following structure:
rule-name-1 => { active => boolean, category => string, creator => string, destinations => string (destination name), escalation_only => boolean, escalation_rule => string, escalation_time => int, event_codes => string, except_codes => string, minimum_severity => string, name => string, snooze_time => int }, ... rule-name-n => { ... }
This method is analagous to the native XCLI command 'metadata_list' and returns a nested hash containing details of all metatdata objects indexed by the object name. The hash has the following structure:
metadata-object-name-1 => { key => string, name => string, object_type => string, value => string }, ... metadata-object-name-n => { ... }
This method is analagous to the native XCLI command 'reservation_list' and returns a nested hash containing details of all volume reservations indexed by volume name. The hash has the following structure:
volume-name-1 => { initiator_uid => signed integer, persistent_access_type => string, persistent_reservation_type => string, pr_generation => int, reservation_age => string, reservation_type => string, reserving_port => string, volume_name => string }, ... reservation-volume-name-n => { ... }
This method is analagous to the native XCLI command 'event_threshold_list' and returns a nested hash containing details of all event threshold events for volumes indexed by volume name. The hash has the following structure:
volume-name-1 => { code => string, critical => percentage (range 0-100), criticaldef => percentage (range 0-100), has_thresholds => boolean, informational => string, informationaldef => percentage (range 0-100), major => percentage (range 0-100), majordef => percentage (range 0-100), minor => percentage (range 0-100), minordef => percentage (range 0-100), not_in_use => boolean, replaced_by => string, warning => percentage (range 0-100), warningdef => percentage (range 0-100) }, ... volume-name-1 => { ... }
This method is analagous to the native XCLI command 'snapshot_list' and returns a nested hash containing details of all snapshots for the specified volume indexed by snapshot name. The hash has the following structure:
snapshot-1 => { capacity_blocks => int, consistency_group => string, creator => string, deletion_priority => int, locked => boolean, locked_by_pool => boolean, master_copy_creation_time => string, master_name => string, mirrored => boolean, modified => boolean, name => string, pool => string, serial_number => int, short_live_io => boolean, size_gb => int, size_mib => int, snapshot_creation_time => string, snapshot_format => boolean, snapshot_group_name => string, snapshot_of => string, snapshot_of_snap_group => string, used_capacity_gb => int, used_capacity_mib => int, vaai_disabled_by_user => boolean, vaai_enabled => boolean, wwn => WWN }. ... snapshot-n => { ... }
This method is analagous to the native XCLI command 'mapping_list' and returns a nested hash containing mapping details of all volumes for the specified host indexed by volume name. The hash has the following structure:
volume-1 => { locked => boolean, lun => int, master => string, serial_number => int, size => int, volume => string }, ... volume-n => { ... }
The methods below return data as retrieved directly from a call to the corresponding XCLI method with no additional data formatting. These methods may be useful if you wish to perform data processing or manipulation in your own custom methods rather than using the methods above.
This method is analagous to the native host_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native pool_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native mirror_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native vol_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native cluster_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native target_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native dest_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native snap_group_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native ipinterface_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native target_port_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native reservation_key_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native fc_port_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native connectivity_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native host_connectivity_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native ups_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native psu_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native ats_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native cf_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native dimm_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native fan_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native mm_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native switch_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native service_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native component_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native ethernet_cable_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native fs_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native cg_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native rule_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native metadata_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native reservation_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native event_threshold_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native snapshot_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
This method is analagous to the native mapping_list XCLI command, it returns an unformatted response as retrieved directly from the XCLI invocation.
Luke Poskitt, <ltp at cpan.org>
<ltp at cpan.org>
Please report any bugs or feature requests to bug-ibm-xcli at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IBM-XCLI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-ibm-xcli at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc IBM::XCLI
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=IBM-XCLI
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/IBM-XCLI
CPAN Ratings
http://cpanratings.perl.org/d/IBM-XCLI
Search CPAN
http://search.cpan.org/dist/IBM-XCLI/
Copyright 2012 Luke Poskitt.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install IBM::XCLI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IBM::XCLI
CPAN shell
perl -MCPAN -e shell install IBM::XCLI
For more information on module installation, please visit the detailed CPAN module installation guide.