iControl 101 - #13 - Data Groups

Data Groups can be useful when writing iRules.  A data group is simply a group of related elements, such as a set of IP addresses, URI paths, or document extensions. When used in conjuction with the matchclass or findclass commands, you eliminate the need to list multiple values as arguments in an iRule expression.  This article will discuss how to use the methods in the LocalLB::Class interface to manage the Data Groups for use within iRules.


You will first notice a mixing up of terms.  A "Class" and a "Data Group" can be used interchangeably.  Class was the original development term and the marketing folks came up with Data Group later on so you will see "Class" embedded in the core configuration and iControl methods, thus the LocalLB::Class interface, and "Data Groups" will most often be how they are referenced in the administration GUI.

Data Groups come in 4 flavors: Address, Integer, String, and External.  Address Data Groups consist of a list of IP Addresses with optional netmasks and are useful for applying a policy based on a originating subnet.  Integer Data Groups hold numeric integers and, to add more confusion, are referred as "value" types in the API.  String Data Groups can hold a valid ascii-based string.  All of the Data Group types have methods specific to their type (ie get_string_class_list(), add_address_class_member(), find_value_class_member()).  External Data Groups are special in that they have one of the previous types but there are no direct accessor methods to add/remove elements from the file.  The configuration consists of a file path and name, along with the type (Address, Integer, String).  You will have to use the ConfigSync file transfer APIs to remotely manipulate External Data Groups.  External Data Groups are meant for very large lists of lists that change frequently.

This article will focus on String Data Groups, but the usage for Address and Integer classes will be similar in nature.


This article uses PowerShell and the iControl Cmdlets for PowerShell as the client environment for querying the data.  The following setup will be required for the examples contained in this article.

PS> Add-PSSnapIn iControlSnapIn
PS> Initialize-F5.iControl -Hostname bigip_address -Username bigip_user -Password bigip_pass
PS> $Class = (Get-F5.iControl).LocalLBClass

Listing data groups

The first thing you'll want to do is determine which Data Groups exist.  The get_string_class_list() method will return a array of strings containing the names of all of the existing String based Data Groups.

PS> $Class.get_string_class_list()

Creating a Data Group

You have to start from somewhere, so most likely you'll be creating a new Data Group to do your bidding.  This example will create a data group of image extensions for use in a URI based filtering iRule.  The create_string_class() takes as input an array of LocalLB::Class::StringClass structures, each containing the class name and an array of members.  In this example, the string class "img_extensions" is created with the values ".jpg", ".gif", and ".png".  Then the get_string_class_list() method is called to make sure the class was created and the get_string_class() method is called to return the values passed in the create method.

PS> $StringClass = New-Object -typename iControl.LocalLBClassStringClass
PS> $StringClass.name = "img_extensions"
PS> $StringClass.members = (".jpg", ".gif", ".png")
PS> $Class.create_string_class(,$StringClass)

PS> $Class.get_string_class_list()

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.gif, .jpg, .png}

Adding Data Group items

Once you have an existing Data Group, you most likely will want to add something to it.  The add_string_class_member() method will take as input the same LocalLB::Class::StringClass structure containing the name of the Data Group and the list of new items to add to it.  The following code will add two values: ".ico" and ".bmp" to the img_extensions Data Group and then will query the values of the Data Group to make sure the call succeeded.

PS> $StringClass.members = (".ico", ".bmp")
PS> $Class.add_string_class_member(,$StringClass)

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.bmp, .gif, .ico, .jpg...}

Removing Data Group Items

If you want to add items, you may very well want to delete items.  That's where the delete_string_class_member() method comes in.  Like the previous examples, it takes the LocalLB::Class::StringClass structure containing the name of the Data Group and the values you would like to remove.  The following example removes the ".gif" and ".jpg" value and queries the current value of the list.

PS> $StringClass.members = (".gif", ".jpg")
PS> $Class.delete_string_class_member(,$StringClass)

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.bmp, .ico, .png}

Deleting Data Groups

The interface wouldn't be complete if you couldn't delete the Data Groups you previously created.  The delete_class() method takes as input a string array of class names.  This example will delete the img_extensions Data Group and then call the get_string_class_list() method to verify that it was deleted.

PS> $Class.delete_class(,"img_extensions")

PS> $Class.get_string_class_list()


That's about it!  Just replace the "string" with "address" and "value" in the above methods and you should be well on your way to building any type of Data Group you need for all your iRule needs.


Get the Flash Player to see this player.
Published May 01, 2008
Version 1.0

Was this article helpful?


  • This notation is very confusing:





    What is seems you are trying to convey here is that get_string_class is expecting an array. It doesn't require an array, but will accept it. However arrays in PowerShell are denoted with the @ symbol. So these work and are generally less confusing:




  • @Erik, you can use the LocalLB.Class.get_* methods to pull out the values. For a string class named urimappnings, you could do something like this



    pull out the names from the string class;


    $StringClassA = (Get-F5.iControl).LocalLBClass.get_string_class(@("urimappings") );


    ValuesAofA = (Get-F5.iControl).LocalLBClass.get_string_class_member_data_value($StringClassA);


    Print out the results


    Write-Host "Data Group: urimappings"


    Write-Host "Names:"




    Write-Host "Values"





    Hope this helps...
  • @Joe - Thanks, i needed this to pull an address list, and the get_address_class pieces of it worked great. There are 137 addresses in this Data List, so this will make it much easier when there is a request to see what address exists in it rather than doing snapshots.
  • I like to use data groups with the webui as well as classes with iControl.



    I see the following problem, but have no clue to do it right:


    My c looks like this:



    LocalLBClassStringClass[] standardServices = f5Interface.LocalLBClass.get_string_class(new string[] { _SVersionen });


    String[][] standardVersions = this.f5Interface.LocalLBClass.get_string_class_member_data_value(standardServices);



    Perfectly fine all keys and values are accessible. Now I modify the values and perform the following:


    f5Interface.LocalLBClass.set_string_class_member_data_value(standardServices, standardVersionen);



    and a successive:



    standardServices = f5Interface.LocalLBClass.get_string_class(new string[] { _SVersionen });


    standardVersios = this.f5Interface.LocalLBClass.get_string_class_member_data_value(standardServices);



    and my values are "" (empty). Any hints to solve the issue are welcome :-)
  • or6680's avatar
    Icon for Nimbostratus rankNimbostratus

    Hey guys, I am trying to write power shell to add string and value to data group...


    i wrote that one with no luck: Initialize- -Hostname -Username admin -Password admin


    pull out the names from the string class;

    $StringClassA = (Get-;) ); $ValuesAofA = (Get-($StringClassA);


    Print out the results

    Write-Host "Data Group DNS-DB" Write-Host "IP's:" $StringClassA[0].members Write-Host "Countris" $ValuesAofA[0] $Class = (Get- $StringClass = New-Object -typename iControl.LocalLBClassStringClass $StringClass.name = "Test" $StringClass.members = (".idscs", ".bsmds") $Class.add_string_class_member((,$StringClass)) $ValueClass = New-Object -typename iControl.LocalLBClassValueClass $ValueClass.name = "Test" $ValueClass.members = ("2", "1") $Class.add_Value_class_member((,$ValueClass)) $Class.get_value_class_list()


    Can you asist please? Thanks