Ruby Logo

Here on DevCentral we’ve released libraries for a number of the big languages from Java and Perl to Powershell. Up until now there has not been much love for Ruby. Well, that’s all about to change: enter the new iControl Ruby Library. This project is a work in progress and the library is a mere 48 lines long as of this initial release. There will be many more features along with more example code coming in the near future.

The first set of installation instructions only cover the most recent Ubuntu release: Lucid 10.04, but should segue well with any distribution that has Ruby 1.8.6 or newer and RubyGems 1.2 or better. In addition to Ruby and Gems, you will also need the Ruby OpenSSL libraries and HTTPClient or newer. Please feel free to test this code on as many other distributions and operating systems as you can and post your feedback in the iControl Ruby Library forum. We will do our best to get your change requests heard and rolled into the next release. Without further ado, let’s get started.

Installing The Ruby iControl Libraries

This installation assumes you are starting with a fresh Ubuntu Lucid (10.04) install.

1. Install the Ruby, Ruby Gems, and Ruby OpenSSL libraries

apt-get install ruby rubygems libopenssl-ruby

3. Download the iControl Ruby Library Gem

4. Install the iControl Gem

gem install f5-icontrol-10.2.0.gem

5. Run one of the example files (located in /var/lib/gems/1.8/gems/f5-icontrol-10.2.0.a.1/examples/ if installed as ‘root’)

ruby get_version.rb admin admin
   => BIG-IP_v10.1.0

Installation Notes for Older Distributions

The age of the distribution does not matter nearly as much as the version of Ruby and RubyGems. If your Gems installation is too old you will get an “HTTP Response 302” and an error when trying to perform any remote actions. Ubuntu namely has not updated any of the RubyGems packages for Hardy (and older releases). As such you will see this error when trying to install iControl Ruby Library because Gems will try to remotely retrieve HTTPClient. If you are stuck using an older distribution we would suggest that you remove the old version of RubyGems and install a newer version (v1.4.1 as of this writing) manually. Instructions for manually installing RubyGems can be found on their download page.

Alternatively, the HTTPClient gem could be retrieved manually and installed locally prior to the iControl Ruby Library.

Example Code

There are currently two pieces of sample code included with this release: create-http-virtual-and-pool.rb and get-version.rb. The ‘create-http-virtual-and-pool.rb’ script will create HTTP pool with a number of members and an associated SNAT automapped HTTP virtual server. Take a look at this code if you are looking for reference on the syntax of complex types in iControl. We will be posting a full tech tip on understanding complex types in the near future, but this should get you started. The ‘get-version.rb’ script is rather simple and does exactly what it says: gets the version of the target BIG-IP. There will be many more pieces of example code coming shortly. More information on syntax and types can be found in the iControl SDK documentation.


Contained within the Gem is the iControl Ruby Library and the WSDLs for the most recent iControl SDK (currently v10.2.0). In order to keep things consistent, the first three numbers in the version correspond iControl SDK version that provided the WSDLs. The next ‘a’ signifies that this is an ‘alpha’ release, which will be dropped in subsequent releases. Lastly, the final number signifies the build number supplied by our local repository. Eventually when we deem the library stable, the version number will look something like v11.2.1.678, meaning that this future release was built using WSDLs from the version 11.2.1 iControl SDK and has a build number of 678.


Please keep in mind that this is our first ‘stab’ at an in-house iControl Ruby library and as such this is not by any means a finished product. There are a number of features we would like to add, but we wanted to start receiving your feedback as soon as possible. We feel that there is a lot of upward potential for this project and need your help and feedback to get it moving. We hope this will help all the Ruby shops out there finally start integrating iControl into their applications. Until next time, happy coding!

Comments on this Article
Comment made 10-Jan-2011 by John Allen
Windows Installs:

When i installed the gem under 1.8.7, it ran fine without having to install any additional SSL code:

C:\Ruby187\lib\ruby\gems\1.8\gems\f5-icontrol-10.2.0.a.1\examples>ruby get-version.rb admin admin
at depth 0 - 18: self signed certificate
at depth 0 - 18: self signed certificate

...although you do get those odd cert messages....YMMV
Comment made 11-Jan-2011 by George Watkins 492
Hi John,

I searched high and low for a way to disable the self-signed certificate errors, but was unable to find a way to disable these. In future releases there will be built-in certificate verification, which won't throw any warnings. If anyone know a way to silence these warnings, please interject.

Comment made 11-Jan-2011 by Joe Pruitt 6272
Just installed on my Mac with the default ruby install already on there and it's working great! No other gem's were needed! Can't wait to start playing with it.
Comment made 30-Apr-2011 by benjamin.indermuehle 0
the link to the ruby gem is dead

3. Download the iControl Ruby Library Gem

where can it be found ?
Comment made 27-May-2011 by benjamin.indermuehle 0
RHEL is using the Ruby version 1.8.5
your gems works fine with that version of ruby also. there is one little catch though.
It only allows numbers in the version string.


i have repackaged the gem with a different version string and it works fine now.
It would be really cool if you could remove the letter from the versionstring in future versions.
Anyways thanks a lot for that awesome gem !
Comment made 01-Jun-2011 by Steven Wagner 0
I just got bitten by that same "only numbers in the gemspec" issue whilst developing on RHEL 5.5...
Comment made 15-Jun-2011 by George Watkins 492
Hi Benjamin and Steven,

Thanks for the feedback! I'm going to release a new version shortly and I'll pull the 'a' out of the gemspec version.

Benjamin: I fixed that link a few weeks ago and forgot to reply to your request. Thanks again for pointing that out for us!

Comment made 21-Jun-2011 by George Watkins 492
Version of the Ruby iControl library is now available:
Comment made 28-Oct-2011 by John Allen
Revised link for what George posted above:
Comment made 29-May-2012 by Tom Duckering 0
Hi - I'm having trouble listing things. I know I have virtual servers in my BIG IP but when I ask for a list via LocalLB.VirtualServers.get_list I get zero length array returned.

Have I missed something stupid?
Comment made 29-May-2012 by Tom Duckering 0
Hi - I'm having trouble listing things. I know I have virtual servers in my BIG IP but when I ask for a list via LocalLB.VirtualServers.get_list I get zero length array returned.

Have I missed something stupid?
Comment made 29-May-2012 by Joe Pruitt 6272
Tom, are you using admin partitions on your LTM to section off configuration objects? If so, iControl defaults to the "/Common" partition. You'll need to change the "active" partition in your client code before making the get_list() call. I went over this a bit in this article:

Comment made 12-Jun-2012 by George Watkins 492

Give this a shot:

bigip ='test-ltm-01', 'admin', 'admin', ['LocalLB.VirtualServer']).get_interfaces

That returns ["/Common/ELN_Remote_Access_vs", "/Common/ELN_Remote_Access_vs_redirect", "/Common/test-vs-01"] for me.

Hope that helps,

Comment made 13-Jun-2012 by Sven 0
I had to patch the file lib/f5-icontrol.rb in order to make it work for me:
- It lacked the usage of the http_proxy I configured in my env, fixed by:
@proxy = ENV['https_proxy'] in initialize()
- The endpoint_url wasn't constructed the right way:
makes the F5 do respond with a 302 (redirect) to the location "/tmui/login.jsp" which results in this error:
/usr/lib/ruby/gems/1.8/gems/httpclient-2.2.5/lib/httpclient/util.rb:117:in `https?': undefined method `downcase' for nil:NilClass (NoMethodError)
from /usr/lib/ruby/gems/1.8/gems/httpclient-2.2.5/lib/httpclient/session.rb:738:in `connect'

This diff addresses both problems:
--- /tmp/f5/lib/f5-icontrol.rb 1970-01-01 01:00:00.000000000 +0100
+++ lib/f5-icontrol.rb 2012-06-13 12:20:11.369138428 +0200
@@ -14,6 +14,7 @@
@wsdls = wsdls
@endpoint = '/iControl/iControlPortal.cgi'
@interfaces = {}
+ @proxy = ENV['https_proxy']

def get_interfaces
@@ -25,10 +26,11 @@
@interfaces[wsdl] ='file://' + wsdl_path).create_rpc_driver
@interfaces[wsdl].options['protocol.http.ssl_config.verify_mode'] = OpenSSL::SSL::VERIFY_NONE
@interfaces[wsdl].options['protocol.http.ssl_config.verify_callback'] = lambda{ |arg1, arg2| true }
+ @interfaces[wsdl].options['protocol.http.proxy'] = @proxy if !@proxy.nil?

- @interfaces[wsdl].options['protocol.http.basic_auth'] << ['https://' + @hostname + '/' + @endpoint, @username, @password]
- @interfaces[wsdl].endpoint_url = 'https://' + @hostname + '/' + @endpoint
+ @interfaces[wsdl].options['protocol.http.basic_auth'] << ['https://' + @hostname + @endpoint, @username, @password]
+ @interfaces[wsdl].endpoint_url = 'https://' + @hostname + @endpoint
Comment made 11-Jan-2013 by MrTeleBird 0
I get an ERROR message when running the examples scripts.

/usr/lib64/ruby/gems/1.8/gems/httpclient-2.3.2/lib/httpclient/session.rb:803:in `initialize': Connection refused - connect(2) (://:0) (Errno::ECONNREFUSED)

I can see that there is traffic going to and from my F5 BigIP device, therefore I dono think this is a firewall issue. If I telnet over port 443 it works.

any ideas what could be wrong??
Comment made 27-Sep-2013 by Gerard Lynch 16
For those looking for the gem download link, you can get it here:
Comment made 26-Jan-2015 by DavidGamba 1
Can't use it with ruby 2