NAME

IBM::SONAS - Perl API to IBM SONAS CLI

SYNOPSIS

IBM::SONAS is a Perl API to IBM SONAS CLI.

use IBM::SONAS;

# Create an IBM::SONAS object

my $ibm = IBM::SONAS->new(
			user     => 'admin',
			host     => 'my-sonas.company.com',
			key_path => '/path/to/my/.ssh/private_key'
	) or die "Couldn't create object! $!\n";

METHODS

new ( %ARGS )

my $ibm = IBM::SONAS->new(      
			user     => 'admin',
			host     => 'my-sonas.company.com',
			key_path => '/path/to/my/.ssh/private_key'
	) or die "Couldn't create object! $!\n";

Constructor - creates a new IBM::SONAS object. This method accepts three mandatory parameters and one optional parameter, the three mandatory parameters are:

user: The username of the user with which to connect to the device.
host: The hostname or IP address of the device to which we are connecting.
key_path: Either a relative or fully qualified path to the private ssh key valid for the user name and device to which we are connecting. Please note that the executing user must have read permission to this key.

disk ( $id )

        # Get the disk named "system_vol_00" as an 
	# IBM::StorageSystem::Disk object

        my $disk = $ibm->disk(system_vol_00);
        
        # Print the disk status

        print $disk->status;

        # Alternately

        print $ibm->disk(system_vol_00)->status;

Returns a IBM::StorageSystem::Disk object representing the disk specified by the value of the id parameter, which should be a valid disk name in the target system.

Note that this is a caching method and that a previously retrieved IBM::StorageSystem::Array object will be returned if one has been cached from previous invocations.

get_disk( $id )

This is a functionally equivalent non-caching implementation of the disk method.

get_disks

        # Print a listing of all disks in the target system including their 
	# name, the assigned pool and status

        printf( "%-20s%-20s%-20s\n", 
		"Name", 
		"Pool", 
		"Status" 
	);
        printf( "%-20s%-20s%-20s\n", 
		"-----", 
		"------", 
		"-------" 
	);

        foreach my $disk ( $ibm->get_disks ) { 
		printf( "%-20s%-20s%-20s\n", 
			$disk->name, 
			$disk->pool, 
			$disk->status 
		) 
	}

        # Prints something like:
        #
        # Name                Pool                Status              
        # -----               ------              -------             
        # silver_vol_00       silver              ready               
        # silver_vol_01       silver              ready               
        # silver_vol_02       silver              ready    
        # ... etc.

Returns an array of IBM::StorageSystem::Disk objects representing all disks in the target system.

get_exports

        # Print a listing of all configured exports containing the export name,
	# the export path, the export protocol and the export status.

        printf( "%-20s%-40s%-10s%-10s\n", 
		'Name', 
		'Path', 
		'Protocol', 
		'Active' 
	);

        foreach my $export ( $ibm->get_exports ) { 
                print '-'x55,"\n";
                printf( "%-20s%-20s%-10s%-10s\n", 
			$export->name, 
			$export->path, 
			$export->protocol, 
			$export->active 
		)
        }

        # Prints something like:
        #
        #Name                Path                Protocol  Active    
        # ------------------------------------------------------
        # homes_root          /ibm/fs1/homes      NFS       true      
        # ------------------------------------------------------
        # shares_root         /ibm/fs1/shares     NFS       true      
        # -------------------------------------------------------
        # test                /ibm/fs1/test       CIFS      true      
        # -------------------------------------------------------
        # ... etc.

Returns all configured exports on the target system as an array of IBM::StorageSystem::Export objects.

filesystem( $filesystem_name )

        # Print the block size of file system 'fs1'

        print $ibm->filesystem(fs1)->block_size;
        
        # Get the file system 'fs2' as a IBM::StorageSystem::FileSystem object

        my $fs = $ibm->filesystem(fs2);

        # Print the mount point of this file system

        print "fs2 mount point: " . $fs->mount_point . "\n";

        # Call a function if inode usage on file system 'fs2' exceeds 90% of 
	# maximum allocation.

        monitoring_alert( 
		'Inode allocation > 90% on '.$filesystem->device_name 
	) if ( ( ( $fs->inodes / $fs->max_inodes ) * 100 ) > 90 );

Returns the file system specified by the value of the named parameter as a IBM::StorageSystem::FileSystem object.

Note that this is a caching method and a cached object will be retrieved if one exists, If you require a non-cached object, then please use the get_filesystem method.

get_filesystem( $filesystem_name )

This is a non-caching functionally equivalent implementation of the filesystem method. Use this method if you require the file system information to be retrieved directly from the target system rather than cache.

get_filesystems

        # Do the same for all file systems
        map { 
		monitoring_alert( 'Inode allocation > 90% on '.$_->device_name ) 
	} grep { 
		( ( ( $_->inodes / $_->max_inodes ) * 100 ) > 90 ) 
	} $ibm->get_filesystems;

Returns an array of IBM::StorageSystem:FileSystem objects representing all configured file systems on the target system.

get_healths

        # Simple one-liner to print the sensor status and value for any error 
	# conditions.

        map { 
		print join ' -> ', ( $_->sensor, $_->value."\n" ) 
	} 
        grep { 
		$_->status =~ /ERROR/ 
	} $ibm->get_healths;

        # e.g.
        # CLUSTER -> Alert found in component cluster
        # MDISK -> Alert found in component mdisk
        # NODE -> Alert found in component node

Returns an array of IBM::StorageSystem::Health objects representative of all health sensors on the target system.

interface ( $id )

        # Get interface ethX0 on management node mgmt001st001 as an 
	# IBM::StorageSystem::Interface object

	my $interface = $ibm->node('mgmt001st001')->interface('ethX0');

        # Print the interface status

        print $interface->up_or_down;

        # Print the interface status

        print $interface->speed;

        # Alternately;

        print $ibm->interface('mgmt001st001:ethX0')->speed;

Returns the interface identified by the value of the id parameter as an IBM::StorageSystem::Interface object.

The value of the id parameter must be a valid node and interface name separated by a colon.

Note that this method implements caching and a cached object will be returned shoudl one be present. If you require a non-cached object then please use the get_iogroup method.

get_interface( $id )

This is a functionally equivalent non-caching implementation of the interface method.

get_interfaces

        # Print a list of all interfaces, their status, speed and role
        
        foreach my $interface ( $ibm->get_interfaces ) {
                print "Interface: " . $interface->interface . "\n";
                print "\tStatus: " . $interface->up_or_down . "\n";
                print "\tSpeed: " . $interface->speed . "\n";
                print "\tRole: " . $interface->isubordinate_or_master 
				 . "\n----------\n";
        }
        
	# Prints somethign like
	#
	# Interface: ethX0
	# 	Status: UP
	#	Speed: 2000
	#	Role: MASTER
	# ----------
	# Interface: ethXsl0_0
	# 	Status: UP
	#	Speed: 1000
	#	Role: SLAVE
	# ----------
	# etc.

Returns an array of IBM::StorageSystem::Interface objects representing all interfaces on the target system.

mount( $mount )

# Print mount status of file system fs1

print "Mount status: " . $ibm->mount(fs1) . "\n";

# Print only those file system that are not mounted

map { print $_->file_system . " is not mounted.\n" }
grep { $_->mount_status ne 'mounted' }
$ibm->get_mounts;

Returns the mount identified by the mount parameter as a IBM::StorageSystem::Mount object.

Note that this method implements caching and a cached object will be returned should one be present. If you require a non-cached object then please use the get_iogroup method.

get_mount( $mount )

This is a functionally equivalent non-caching implementation of the mount method.

get_mounts

This method returns an array of IBM::StorageSystem::Mount objects representing all mounts on the target system.

node( $node )

# Get node mgmt001st001 as an IBM::StorageSystem::Node object

my $node = $ibm->node( mgmt001st001 );

# Print the node description

print "Description: " . $node->description . "\n";

# Prints something like: "Description: active management node"
# Or alternately;

print "Description: " . $ibm->node( mgmt001st001 )->description . "\n";

Returns the node identified by the value of the node parameter as a IBM::StorageSystem::Node object.

Note that this method implements caching and that a cached object will be returned if one is available. If you require a non-cached object, then please use the non-caching get_node method.

get_node( $node )

This is a functionally equivalent non-caching implementation of the node method.

get_nodes

        # Print the GPFS and CTDB stati of all nodes

        foreach my $node ( $ibm->get_nodes ) {
                print "GPFS status: " . $node->GPFS_status 
		      . " - CTDB status: " . $node->CTDB_status . "\n"
        }

Returns an array of IBM::StorageSystem::Node objects representing all configured nodes on the target system.

get_quotas

        # Call a function to send a quota warning email for any quotas where 
	# the current usage exceeds 85% of the quota usage hard limit.

        map  { send_quota_warning_email( $_ )           }
        grep { ( $_->used_usage / $_->HL_usage ) > 0.85 }
        grep { $_->name ne 'root'                       }
        grep { $_->type eq 'U'                          } $ibm->get_quotas;

Returns all quotas defined on the target system as an array of IBM::StorageSystem::Quota objects.

replication( $eventlog_id )

Returns the replication event identified by the eventlog_id parameter as an IBM::StorageSystem::Replication object.

Note that this method implements caching and that a cached object will be returned if one is available. If you require a non-cached object, then please use the non-caching get_node method.

get_replication( $eventlog_id )

This is a functionally equivalent non-caching implementation of the replication method.

get_replications

        use Date::Calc qw(date_to_Time Today_and_Now);

        # Generate an alert for any replication errors in the last six hours

        foreach my $task ( $ibm->get_replications ) {

                if ( $repl->status eq 'ERROR' 
			and ( Date_to_Time( Today_and_Now ) 
                     - ( Date_to_Time( 
					split /-| |\./, $repl->time 
				) ) ) > 21_600 
		) {
                        alert( "Replication failure for filesystem " 
				. $repl->filesystem 
				. " - log ID: " . $repl->log_id . 
			     )
                }

        }

Returns all asynchornous replication tasks as an array of IBM::StorageSystem::Replication objects.

service( $service )

        # Print the enabled status of the NFS service

        print $ibm->service(NFS)->enabled;

        # Print the configured and enabled status of all services

        printf( "%-20s%-20s%-20s\n", 'Service', 'Configured', 'Active' );

        map { 
		printf( "%-20s%-20s%-20s\n", 
			$_->name, 
			$_->configured, 
			$_->active ) 
	} $ibm->get_services;

Returns a IBM::StorageSystem::Service object representing the service identified by the value of the service parameter.

Note that this method implements caching and that a cached object will be returned if one is available. If you require a non-cached object, then please use the non-caching get_node method.

get_service( $service )

This is a functionally equivalent non-caching implementation of the service method.

get_services

Returns an array of IBM::StorageSystem::Service objects representing all configured services on the target system.

task( $task )

# Print the status of the SNAPSHOTS task

my $snapshots = $ibm->task( SNAPSHOTS );
print "Status: " . $snapshots->status . "\n";

# Alternately

print "Status: " . $ibm->task( SNAPSHOTS )->status . "\n";

Return the task identified by the value of the task parameter as an IBM::StorageSystem::Task object.

Note that this method implements caching and that a cached object will be returned if one is available. If you require a non-cached object, then please use the non-caching get_node method.

get_task( $task )

This is a functionally equivalent non-caching implementation of the task method.

get_tasks

# Call an alert function for any tasks that are not in an OK state

map { alert( $_->name ) } grep { $_->status ne 'OK' } $ibm->get_tasks;

Returns an array of IBM::StorageSystem::Task objects representing all tasks on the target system.

cluster_throughput ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterThroughput performance data on bytes read and written acorss all nodes and all GPFS filesystems in the cluster.

The method accepts a single optional parameter; the time period for which to return the data. The allowed values for this parameter are one of; minute, hour, day, week, month, quarter and year. If omitted, this parameter will default to minute.

cluster_client_throughput ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterClientThroughput performance data on client throughput across all nodes in the target cluster.

cluster_create_delete_latency ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterCreateDeleteLatency performance data on cluster file creation and deletion latency across all nodes in the target cluster.

cluster_create_delete_operations ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterCreateDeleteOperations performance data on cluster file creation and deletion operations across all nodes in the target cluster.

cluster_open_close_latency ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterOpenCloseLatency performance data on cluster file open and close latency across all nodes in the target cluster.

cluster_open_close_operations ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterCreateDeleteOperations performance data on cluster file open and close operations across all nodes in the target cluster.

cluster_read_write_latency ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterReadWriteLatency performance data on cluster file read and write latency across all nodes in the target cluster.

cluster_read_write_operations ( $interval )

Returns either a single, or list, of IBM::StorageSystem::StatisticsSet objects containing IBM::StorageSystem::Statistics::ClusterReadWriteOperations performance data on cluster file read and write operations across all nodes in the target cluster.

AUTHOR

Luke Poskitt, <ltp at cpan.org>

BUGS

Please report any bugs or feature requests to bug-ibm-sonas at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=IBM-SONAS. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc IBM::SONAS

You can also look for information at:

RT: CPAN's request tracker (report bugs here)

http://rt.cpan.org/NoAuth/Bugs.html?Dist=IBM-SONAS
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/IBM-SONAS
CPAN Ratings

http://cpanratings.perl.org/d/IBM-SONAS
Search CPAN

http://search.cpan.org/dist/IBM-SONAS/

LICENSE AND COPYRIGHT

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::SONAS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm IBM::SONAS

CPAN shell

perl -MCPAN -e shell
install IBM::SONAS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

METHODS

new ( %ARGS )

disk ( $id )

get_disk( $id )

get_disks

get_exports

filesystem( $filesystem_name )

get_filesystem( $filesystem_name )

get_filesystems

get_healths

interface ( $id )

get_interface( $id )

get_interfaces

mount( $mount )

get_mount( $mount )

get_mounts

node( $node )

get_node( $node )

get_nodes

get_quotas

replication( $eventlog_id )

get_replication( $eventlog_id )

get_replications

service( $service )

get_service( $service )

get_services

task( $task )

get_task( $task )

get_tasks

cluster_throughput ( $interval )

cluster_client_throughput ( $interval )

cluster_create_delete_latency ( $interval )

cluster_create_delete_operations ( $interval )

cluster_open_close_latency ( $interval )

cluster_open_close_operations ( $interval )

cluster_read_write_latency ( $interval )

cluster_read_write_operations ( $interval )

AUTHOR

BUGS

SUPPORT

LICENSE AND COPYRIGHT

Module Install Instructions