F5::Icontrol

This is the F5-icontrol gem. If you have an F5, it can use the iControl API to automate things

This is not the official library. That one is here. This copy is without warranty. Heck, it probably doesn't even work.

I originally set out to improve the official one:

Improve testing using rspec and vcr
Convert to a supported SOAP parser, such as savon
Support Ruby 2.0.0 and 2.1.0
Make the interface to the library more Ruby-esque

But given the original one was pretty bare-bones, I started over.

Installation

Add this line to your application's Gemfile:

gem 'f5-icontrol'

And then execute:

$ bundle

Or install it yourself as:

$ gem install f5-icontrol

Usage (REST interface)

NOTE: The REST interface is still a work in progress! The conventions may change until we release.

First configure an instance of the API to point to your F5

require 'f5/icontrol'

f5 = F5::Icontrol::RAPI.new username: 'admin', password: 'admin', host: '10.1.1.1'

After that, the calls should line up directly to the API Docs. For collections, use the following methods:

HTTP Verb	Method
GET	get_collection

Note that get_collection is optional if you call #each or some Enumberable method. So foo.get_collection.each can be shortened to foo.each.

For resources

HTTP Verb	Method
GET	load
PUT	update
DELETE	delete
POST	create

For example, to get all the pools:

pools = f5.mgmt.tm.ltm.pool.get_collection

puts pools.map(&:name)

# shorter method
puts f5.mgmt.tm.ltm.pool.map(&:name)

It'll also understand subresources:

members = pools.members.load
puts members.map(&:address)

Or, let's create a pool:

api.mgmt.tm.ltm.pool.create(name: 'seanstestrest')

Usage (SOAP interface)

Note - SOAP will likely be deprecated prior to version 1.0 of this gem. The REST interface is more intuitive and dropping SOAP makes this gem so much lighter.

First, configure the gem:

F5::Icontrol.configure do |f|
  f.host = "hostname.of.bigip"
  f.username = "username"
  f.password = "password"
end

Then use it:

api = F5::Icontrol::API.new
response = api.LocalLB.Pool.get_list

or You can configure per api client.

api = F5::Icontrol::API.new(
    host: "hostname.of.bigip",
    username: "username",
    password: "password",
)
response = api.LocalLB.Pool.get_list

See specs subdir for more examples, especially as it pertains to passing parameters.

Logging

This gem uses the Savon client to wrap the SOAP endpoints, and it is sometimes useful to be able to see the SOAP request and response XML.

You can pass in a few options during configuration of the api client which are forwarded to the internal Savon client:

api = F5::Icontrol::API.new(
    host: "hostname.of.bigip",
    username: "username",
    password: "password",

    # Savon logging options
    enable_logging: true,   # defaults to: false
    log_level: :debug,      # defaults to: debug
    pretty_print_xml: true, # defaults to: true
)

CLI

There's a command line version that's still being roughed out. You'll need a ~/.f5.yml file containing your login information:

default:
  host: foo.bar.com
  username: admin
  password: abc123
lb2:
  host: 1.2.3.4
  username: admin
  password: abc123

Then run f5 and it'll provide help

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request