iControl Apps - #01 - Disabling Node Servers

In version 4.x of BIG-IP, there was a concept of a Node Server (a top level object that consisted of a node's address and port).  Basically it was a top level rollup of all instances of a specific node address and port across all pools of servers.  In version 9 of BIG-IP, the top level Node object is a Node Address (minus the port).  You can still enable/disable a node address across all pool instances, it is not as simple to enable/disable all occurances of a node address AND port across all pools.  This article will discuss how to write an iControl implementation that will allow you to relive some of those good memories from 4.x time.

Introduction

This article will make use of the SOAP::Lite perl library for the iControl client toolkit.  See the perl getting started guide for details on setting up your environment for using this script (or just drop it on your BIG-IP and it will work there).

Now that you've got the configuration to run this script, then we can move on to the logic behind it. But first, we need to get rid of some of the busy work including the SOAP::Lite initialization code and parameter input.  This script is going to take 5 parameters with 2 being optional.  The first 3 parameters are the address, username, and password for the BIG-IP.  The optional parameters are a node_port combination in ip:port format and the state of enable or disable to set the node server to.  You'll see why these are optional later.

NodeServer.pl host uid pwd [[node_port] [enable|disable]]

So we'll need to parse those parameters and setup the SOAP::Lite objects for the Pool and PoolMember interfaces.  This is accomplished with the code below.

#!/usr/bin/perl
#----------------------------------------------------------------------------
# The contents of this file are subject to the "END USER LICENSE AGREEMENT FOR F5
# Software Development Kit for iControl"; you may not use this file except in
# compliance with the License. The License is included in the iControl
# Software Development Kit.
#
# Software distributed under the License is distributed on an "AS IS"
# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
# the License for the specific language governing rights and limitations
# under the License.
#
# The Original Code is iControl Code and related documentation
# distributed by F5.
#
# The Initial Developer of the Original Code is F5 Networks,
# Inc. Seattle, WA, USA. Portions created by F5 are Copyright (C) 1996-2004 F5 Networks,
# Inc. All Rights Reserved.  iControl (TM) is a registered trademark of F5 Networks, Inc.
#
# Alternatively, the contents of this file may be used under the terms
# of the GNU General Public License (the "GPL"), in which case the
# provisions of GPL are applicable instead of those above.  If you wish
# to allow use of your version of this file only under the terms of the
# GPL and not to allow others to use your version of this file under the
# License, indicate your decision by deleting the provisions above and
# replace them with the notice and other provisions required by the GPL.
# If you do not delete the provisions above, a recipient may use your
# version of this file under either the License or the GPL.
#----------------------------------------------------------------------------

#use SOAP::Lite + trace => qw(method debug);
use SOAP::Lite;
use MIME::Base64;

#----------------------------------------------------------------------------
# Validate Arguments
#----------------------------------------------------------------------------
my $sHost = $ARGV[0];
my $sPort = $ARGV[1];
my $sUID = $ARGV[2];
my $sPWD = $ARGV[3];
my $sNodePort = $ARGV[4];
my $sEnable = $ARGV[5];
my $sProtocol = "https";
my $sPort = 443;

if ( ("80" eq $sPort) or ("8080" eq $sPort) )
{
    $sProtocol = "http";
}

if ( ($sHost eq "") or ($sUID eq "") or ($sPWD eq "") )
{
    die ("Usage: NodeServer.pl host uid pwd [[node_port] [enable|disable]]\n");
}

#----------------------------------------------------------------------------
# support for custom enum types
#----------------------------------------------------------------------------
sub SOAP::Deserializer::typecast
{
    my ($self, $value, $name, $attrs, $children, $type) = @_;
    my $retval = undef;
    if ( "{urn:iControl}LocalLB.AvailabilityStatus" == $type )
    {
        $retval = $value;
    }
    return $retval;
}

#----------------------------------------------------------------------------
# Transport Information
#----------------------------------------------------------------------------
sub SOAP::Transport::HTTP::Client::get_basic_credentials
{
    return "$sUID" => "$sPWD";
}

$Pool = SOAP::Lite
    -> uri('urn:iControl:LocalLB/Pool')
    -> proxy("$sProtocol://$sHost:$sPort/iControl/iControlPortal.cgi");
eval { $Pool->transport->http_request->header
(
    'Authorization' =>
        'Basic ' . MIME::Base64::encode("$sUID:$sPWD", '')
); };

$PoolMember = SOAP::Lite
    -> uri('urn:iControl:LocalLB/PoolMember')
    -> proxy("$sProtocol://$sHost:$sPort/iControl/iControlPortal.cgi");
eval { $PoolMember->transport->http_request->header
(
    'Authorization' =>
        'Basic ' . MIME::Base64::encode("$sUID:$sPWD", '')
); };

Now we can move on to the program logic.

The problem

Since there is no top level node server object to set state on at a global level, you will have to loop through all the pools and it's pool members to look for matches.  Once you've found the pools that a node server is a member of (a pool member), then you can use the PoolMember.set_monitor_state() method to mark all instances of that node server across all the pools it belongs to.  But, your first question might be what node servers are defined on the system.  No good bit of code would be complete without the ability to verify your changes, so I've made the node_port and state parameters optional to allow for querying values.  The main application logic looks like this

#----------------------------------------------------------------------------
# main app logic
#----------------------------------------------------------------------------
if ( ($sNodePort ne "") && ($sEnable ne "") )
{
    &SetNodeServer($sNodePort, $sEnable)
}
else
{
    &ListPoolsAndMembers($sNodePort)
}

Listing Node Servers

For listing out all node servers, you will have to loop over all of the pools and query the pool members.  I've opted to use the get_object_status() in the PoolMember interface as it not only returns the pool members but also the objects status (enabled and availability states).  This also came in useful in that the listing can also include the state to verify your future state changes.  This routine takes an optional node_addr_port member so if you don't specify the node_port on the command line, it will list all of the pools and all pool members.  If you do specify a node_port, it will only display the pools that it is a member in.

#----------------------------------------------------------------------------
# sub ListPoolsAndMembers
#----------------------------------------------------------------------------
sub ListPoolsAndMembers()
{
    my ($node_addr_port) = (@_);
    my ($node_addr, $node_port) = split(/:/, $node_addr_port, 2);

    my @pool_list = &getPoolList();
    my @object_status_lists = &getObjectStatusLists(@pool_list);

    # Loop over pools
    for $i (0 .. $#pool_list)
    {
        $bFound = 0;
        $pool = @pool_list[$i];
       
        if ( "" == $node_addr )
        {
            # if no node given, print out full list
            print "Pool $pool\n";
            foreach $status (@{@object_status_lists[$i]})
            {
                $member  = $status->{"member"};
                $addr = $member->{"address"};
                $port = $member->{"port"};
               
                $ostat = $status->{"object_status"};
                $astat = $ostat->{"availability_status"};
                $estat = $ostat->{"enabled_status"};
               
                print "        $addr:$port ($astat, $estat)\n";
            }
            #print "\n";
        }
        else
        {
            # else, only print out where matches are found.
            foreach $status (@{@object_status_lists[$i]})
            {
                if ( !$bFound )
                {
                    $member  = $status->{"member"};
                    $addr = $member->{"address"};
                    $port = $member->{"port"};

                    $ostat = $status->{"object_status"};
                    $astat = $ostat->{"availability_status"};
                    $estat = $ostat->{"enabled_status"};

                    if ( ($node_addr eq $addr) && ($node_port eq $port) )
                    {
                        $bFound = 1;
                    }
                }
            }
            if ( $bFound )
            {
                print "Pool $pool : $node_addr:$node_port ($astat, $estat)\n";
            }
        }
    }
}

Setting Node Server State

Now, listing the objects fun, but the issue here is setting the state across all of the pools.  First, we'll need a method that takes as input a node address/port pair.  It will then loop through all the pool members and build a list of pools where that node server is defined in.  It will finally return the pool list to the calling routine.  This calling routine is the one that set's the state with the PoolMember.set_monitor_state() method effectively marking the pool member down through the monitoring system.  The set_monitor_state() method takes an array of pools, along with a 2-d array of MemberMonitorState structures, an array for each pool in the first parameter.

#----------------------------------------------------------------------------
# sub findPoolsFromMember
#----------------------------------------------------------------------------
sub findPoolsFromMember()
{
    my ($node_addr_port) = (@_);
    my ($node_addr, $node_port) = split(/:/, $node_addr_port, 2);
    my @pool_match_list;
   
    my @pool_list = &getPoolList();
    my @member_lists = &getMemberLists(@pool_list);

    for $i (0 .. $#pool_list)
    {
        $pool = @pool_list[$i];
        foreach $member (@{@member_lists[$i]})
        {
            $addr = $member->{"address"};
            $port = $member->{"port"};
           
            if ( ($node_addr eq $addr) && ($node_port eq $port) )
            {
                push @pool_match_list, $pool;
            }
        }
    }
    return @pool_match_list;
}

#----------------------------------------------------------------------------
# sub setNodeServer
#----------------------------------------------------------------------------
sub SetNodeServer()
{
    my ($node_addr_port, $state) = (@_);
    my ($node_addr, $node_port) = split(/:/, $node_addr_port, 2);
    my @pool_list = &findPoolsFromMember($node_addr_port);
    my $member = { address => $node_addr, port => $node_port };
    my $ENABLED_STATE = "STATE_ENABLED";
   
    if ( $state eq "disable" )
    {
        $ENABLED_STATE = "STATE_DISABLED";
    }
   
    my $MemberMonitorState  = { member => $member, monitor_state => $ENABLED_STATE };
    my @MemberMonitorStateList;
    push @MemberMonitorStateList, $MemberMonitorState;
   
    my @MemberMonitorStateLists;
    for $i (0 .. $#pool_list)
    {
        push @MemberMonitorStateLists, [@MemberMonitorStateList];
    }
   
    # Make call to set_monitor_state
    $soapResponse = $PoolMember->set_monitor_state(
        SOAP::Data->name(pool_names => [@pool_list]),
        SOAP::Data->name(monitor_states => [@MemberMonitorStateLists])
    );
    &checkResponse($soapResponse);
   
    print "Node Server $node_addr_port set to $ENABLED_STATE in pools: ";
    foreach $pool (@pool_list)
    {
        print "$pool, ";
    }
    print "\n";
}

Helper Routines

You may have noticed some routines in the listing and state sections of code.  I'm all about conserving space, so I've consolidated some common code into helper routines.  Things like retrieving lists of pools, pool members, object status, and validating SOAP responses are included below:

#----------------------------------------------------------------------------
# sub getPoolList
#----------------------------------------------------------------------------
sub getPoolList()
{
    # Get the list of pools
    $soapResponse = $Pool->get_list();
    &checkResponse($soapResponse);
    my @pool_list = @{$soapResponse->result};
 
    return @pool_list;
}

#----------------------------------------------------------------------------
# sub getMemberLists
#----------------------------------------------------------------------------
sub getMemberLists()
{
    my (@pool_list) = (@_);
   
    # Get the list of pool members for all the pools
    $soapResponse = $Pool->get_member
    (
        SOAP::Data->name(pool_names => [@pool_list])
    );
    &checkResponse($soapResponse);
    @member_lists = @{$soapResponse->result};
   
    return @member_lists;
}

#----------------------------------------------------------------------------
# sub getObjectStatus
#----------------------------------------------------------------------------
sub getObjectStatusLists()
{
    my (@pool_list) = (@_);
   
    # Get the list of pool members for all the pools
    $soapResponse = $PoolMember->get_object_status
    (
        SOAP::Data->name(pool_names => [@pool_list])
    );
    &checkResponse($soapResponse);
    @object_status_lists = @{$soapResponse->result};
   
    return @object_status_lists;
}

#----------------------------------------------------------------------------
# checkResponse
#----------------------------------------------------------------------------
sub checkResponse()
{
    my ($soapResponse) = (@_);
    if ( $soapResponse->fault )
    {
        print $soapResponse->faultcode, " ", $soapResponse->faultstring, "\n";
        exit();
    }
}

Sample Usage

PS > .\NodeServer.pl bigip username password
Pool pool_1
        10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)
        20.20.20.101:80 (AVAILABILITY_STATUS_RED, ENABLED_STATUS_ENABLED)
Pool pool_2
        20.20.20.102:80 (AVAILABILITY_STATUS_RED, ENABLED_STATUS_ENABLED)
Pool xpbert-http
        10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)

PS> .\NodeServer.pl bigip username password 10.10.10.149:80
Pool pool_1 : 10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)
Pool xpbert-http : 10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)

PS> .\NodeServer.pl bigip username password 10.10.10.149:80 disable
Node Server 10.10.10.149:80 set to STATE_DISABLED in pools: pool_1, xpbert-http,

PS> .\NodeServer.pl bigip username password 10.10.10.149:80
Pool pool_1 : 10.10.10.149:80 (AVAILABILITY_STATUS_RED, ENABLED_STATUS_ENABLED)
Pool xpbert-http : 10.10.10.149:80 (AVAILABILITY_STATUS_RED, ENABLED_STATUS_ENABLED)

PS> .\NodeServer.pl bigip username password 10.10.10.149:80 enable
Node Server 10.10.10.149:80 set to STATE_ENABLED in pools: pool_1, xpbert-http,

PS> .\NodeServer.pl bigip username password 10.10.10.149:80
Pool pool_1 : 10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)
Pool xpbert-http : 10.10.10.149:80 (AVAILABILITY_STATUS_GREEN, ENABLED_STATUS_ENABLED)

The one question you may have is what's up with the AVAILABILITY_STATUS and what does GREEN mean versus RED.  It's all defined in the iControl API for that method but, in short, GREEN means UP, RED means DOWN.

Conclusion

This sample application was written in Perl but the logic behind it could easily be implemented in Java, .Net, PowerShell, or whatever language your heart desires.  With this little bit of code, you can relive your 4.x days and enable/disable node servers to your hearts content.

The entire script is located in the iControl Codeshare under DisablingNodeServers