iControl - A Perl interface to the F5 iControl API
use iControl; my $ic = iControl->new( server => 'bigip.company.com', username => 'api_user', password => 'my_password', port => 443, proto => 'https' ); my @node_list = $ic->get_node_list();
my $ic = iControl->new( server => 'bigip.company.com', username => 'api_user', password => 'my_password', port => 443, proto => 'https' );
Constructor method. Creates a new iControl object representing a single interface into the iControl API of the target system.
Required parameters are:
The target F5 BIGIP device. The supplied value may be either an IP address, FQDN or resolvable hostname.
The username with which to connect to the iControl API.
The password with which to connect to the iControl API.
The port on which to connect to the iControl API.
The protocol with to use for communications with the iControl API (should be either http or https).
Return a SystemInformation struct containing the identifying attributes of the operating system. The struct information is described below;
Member Type Description ---------- ---------- ---------- system_name String The name of the operating system implementation. host_name String The host name of the system. os_release String The release level of the operating system. os_machine String The hardware platform CPU type. os_version String The version string for the release of the operating system. platform String The platform of the device. product_category String The product category of the device. chassis_serial String The chassis serial number. switch_board_serial String The serial number of the switch board. switch_board_part_revision String The part revision number of the switch board. host_board_serial String The serial number of the host motherboard. host_board_part_revision String The part revision number of the host board. annunciator_board_serial String The serial number of the annuciator board. annunciator_board_part_revision String The part revision number of the annunciator board.
Gets a list of the cluster names.
Gets the current fail-over mode that the device is running in.
Gets the current fail-over state that the device is running in.
Gets the cluster enabled states.
$ic->save_configuration('backup.ucs'); # is equivalent to $ic->save_configuration('backup'); # Not specifying a filename will use today's date in the # format YYYYMMDD as the filename. $ic->save_configuration(); # is equivalent to $ic->save_configuration('today');
Saves the current configurations on the target device.
This method takes a single optional parameter; the filename to which the configuration should be saved. The file extension .ucs will be suffixed to the filename if missing from the supplied filename.
Specifying no optional filename parameter or using the filename today will use the current date as the filename of the saved configuration file in the format YYYYMMDD.
my @virtuals = $ic->get_vs_list();
Returns an array of all defined virtual servers.
my $destination = $ic->get_vs_destination($vs);
Returns the destination of the specified virtual server in the form v4_ip_address%route_domain:port.
print "Virtual server $vs is in state ",$ic->get_vs_enabled_state($vs),"\n";
Return the enabled state of the specified virtual virtual server.
Returns the traffic statistics for all configured virtual servers. The statistics are returned as VirtualServerStatistics struct hence this method is useful where access to raw statistical data is required.
For parsed statistic data, see get_vs_statistics_stringified.
For specific information regarding data and units of measurement for statistics methods, please see the Notes section.
my $statistics = $ic->get_vs_statistics($vs);
Returns all statistics for the specified virtual server as a VirtualServerStatistics object. Consider using get_vs_statistics_stringified for accessing virtual server statistics in a pre-parsed hash structure.
my $statistics = $ic->get_vs_statistics_stringified($vs); foreach (sort keys %{$stats{stats}}) { print "$_: $stats{stats}{$_}\n"; }
Returns all statistics for the specified virtual server as a multidimensional hash (hash of hashes). The hash has the following structure:
{ timestamp => 'yyyy-mm-dd-hh-mm-ss', stats => { statistic_1 => value, statistic_2 => value, ... statistic_n => value } }
This function accepts a single parameter; the virtual server for which the statistics are to be returned.
print "Virtual Server: $virtual_server\nDefault Pool: ", $ic->get_default_pool_name($virtual_server), "\n";
Returns the default pool names for the specified virtual server.
print join " ", ($ic->get_pool_list());
Returns a list of all pools in the target system.
foreach my $pool ($ic->get_pool_list()) { print "\n\n$pool:\n"; foreach my $member ($ic->get_pool_members($pool)) { print "\t$member\n"; } }
Returns a list of the pool members for the specified pool. This method takes one mandatory parameter; the name of the pool.
Pool member are returned in the format IP_address:service_port.
print join "\n", ($ic->get_node_list());
Returns a list of all configured nodes in the target system.
Nodes are returned as IP addresses.
foreach ($ic->get_node_list()) { print "Node: $_ (" . $ic->get_screen_name($_) . ")\n"; }
Retuns the screen name of the specified node.
$ic->get_node_status(
Returns the status of the specified node as a StatusObject struct.
For formatted node status information, see the get_node_status_as_string() method.
Retuns the availability status of the node.
Retuns the enabled status of the node.
Returns a descriptive status of the specified node.
Returns the node status as a descriptive string.
Gets the current availability status of the specified node addresses.
Returns all statistics for the specified node.
my %stats = $ltm->get_node_statistics_stringified($node); foreach (sort keys %{stats{stats}}) { print "$_:\t$stats{stats}{$_}{high}\t$stats{stats}{$_}{low}\n"; }
Returns a multidimensional hash containing all current statistics for the specified node. The hash has the following structure:
This function accepts a single parameter; the node for which the statistics are to be returned.
Returns all registered event subscriptions.
This method is an analog of get_event_subscription
my $subscription = $ic->create_subscription_list ( name => 'my_subscription_name', url => 'http://company.com/my/eventnotification/endpoint, username => 'username', password => 'password', ttl => -1, min_events_per_timeslice => 10, max_timeslice => 10 );
Creates an event subscription with the target system. This method requires the following parameters:
A user-friendly name for the subscription.
The target URL endpoint for the event notification interface to send event notifications.
The basic authentication username required to access the URL endpoint.
The basic authentication password required to access the URL endpoint.
The time to live (in seconds) for this subscription. After the ttl is reached, the subscription will be removed from the system. A value of -1 indicates an infinite life time.
The minimum number of events needed to trigger a notification. If this value is 50, then this means that when 50 events are queued up they will be sent to the notification endpoint no matter what the max_timeslice is set to.
This maximum time to wait (in seconds) before event notifications are sent to the notification endpoint. If this value is 30, then after 30 seconds a notification will be sent with the events in the subscription queue.
This module was written for version 10.x and less of BIGIP. The iControl API has changed significantly with the most recent version (11) and some features may not exist in older version (9.x).
Within iControl, statistical values are a 64-bit unsigned integer represented as a Common::ULong64 object. The ULong64 object is a stuct of two 32-bit values. This representation is used as there is no native support for the encoding of 64-bit numbers in SOAP.
The ULong object has the following structure;
({ STATISTIC_NAME => { high => long low => long } }, bless Common::ULong64)
Where high is the unsigned 32-bit integer value of the high-order portion of the measured value and low is the unsigned 32-bit integer value of the low-order portion of the measured value.
In non-stringified statistic methods, these return values are ULong64 objects as returned by the iControl API. In stringified statistic method calls, the values are processed on the client side into a local 64-bit representation of the value using the following form.
$value = ($high<<32)|$low;
Stringified method calls are guaranteed to return a correct localised 64-bit representation of the value.
It is the callers responsibility to convert the ULong struct for all other non-stringified statistic method calls.
Luke Poskitt, <ltp@cpan.org>
To install iControl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm iControl
CPAN shell
perl -MCPAN -e shell install iControl
For more information on module installation, please visit the detailed CPAN module installation guide.