This gem allows you to connect to a F5 appliance
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


IControl: F5 BigIP SOAP API Client

IControl allows you to easily connect to a BigIP F5 load balancer and by means of the SOAP API. You can programmatically do almost the same things that you would do throught the Web Interface.


Install the gem:

gem install icontrol


In order to configure you just have to set up the username, password and the server you're connecting to:

IControl.config = 'username' IControl.config = 'secret' IControl.config = “”

Using the library

Bassically the library is the same as the one documented in the f5 devcentral but using ruby docs ( The main difference is that while the icontrol api does allow the bulk operation over a number of elements at the same time, in this case we limit it to just one at a time. So, for example, if you one to set the default pool for a virtual server, in the f5 doc, it says you have to pass 2 parameters

   in String [] virtual_servers,
   in String [] default_pools

So you can change several default pools at a time. On the contrary this library adopts a more object oriented design and only allows to work with one object at a time, i. e. and talking ruby, you don't have a set_default_pool_name class method but an instance one, so you have to first retreive the virtual server and later set its default pool. Something like this

IControl::LocalLB::VirtualServer.find("my_virtual_server).set_default_pool_name(:default_pool => "the default pool name")

if you want to do it in every virtual server then you do something like this.

IControl::LocalLB::VirtualServer.find(:all).each { |vs| vs.set_default_pool_name(:default_pool => "the default pool name") }

I think you get the point. Note that now the parameter name is :default_pool and not :default_pools, because of the semantics change.


The documentation can be found in

Virtual Servers

You can retreive, create, delete and modify virtual servers, for more information see IControl::LocalLB::VirtualServer. As an example of you what you can do:

Creating a virtual Server

IControl::LocalLB::VirtualServer.create(:definition => {
                                          :address => "",
                                          :name => "test_virtual_server",
                                          :port => "4",
                                          :protocol => IControl::Common::ProtocolType::PROTOCOL_TCP
                                        :wildmask => "",
                                        :resource => {
                                          :type => IControl::LocalLB::VirtualServer::VirtualServerType::RESOURCE_TYPE_POOL,
                                          :default_pool_name => ""
                                        :profiles => [])

Obtaining an instance of a virtual server

my_virtual_server = IControl::LocalLB::VirtualServer.find("virtual_server_name")

Changing its default pool

my_virtual_server.set_default_pool_name(:default_pool => "my_pool_name")

Destroying it


Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


This documentation is based on the original documentation procided by F5 Networks, Inc., Seattle, Washington Copyright © 2010 Jose Fernandez (magec). See LICENSE for details.