Ruby and iControl: Remote BIG-IP Software Image Installation


I did a lot of BIG-IP installs and upgrades while I worked in the IT field. Most BIG-IP administrators are familiar with the process: go to, get the software image ISO, copy it to your target system, SSH to the BIG-IP (or use the web UI), install the image, reboot, and you’re done. F5’s upgrade process is relatively painless when compared to some of the other install/upgrade scenarios I’ve worked through, but there is still a lot that could be streamlined. Human error is greatly reduced by minimizing the amount of command line interaction one has with BIG-IP when performing lots of installs.

Automation with iControl and SCP

First of all, we need a method of transferring the BIG-IP software image to the target system. Secure Copy (scp) works great for this as it allows the administrator to easily and securely place image on the system. Rather an executing the scp command from within our code, we will use Ruby’s native Net::SCP library to accomplish this. Net::SCP is part of the larger Net::SSH library and provides the full suite of functionality.

A Ruby library called ProgressBar is used to notify the user of Secure Copy’s progress. We are able to update the progress through the ‘set’ method inside the SCP upload code block. There are only 7 lines of code that do the heavy lifting to copy the image up to the BIG-IP:

Net::SCP.start(bigip_address, bigip_shell_user, :password => bigip_shell_pass.chomp, :auth_methods =>["keyboard-interactive" ] ) do |scp|
    pbar =, 100)

    scp.upload!(install_image, "/shared/images/.") do |chunk, image, sent, total|


Once our image has been transferred, we want make sure that the unit is not ‘active’ prior to processing the upgrade. We can use the get_failover_state method within System::Failover interface to check the current state of our target system. The returned string will be either ‘FAILOVER_STATE_ACTIVE’ or ‘FAILOVER_STATE_STANDBY’. We’ll want to issue a warning to our administrator if they are attempting to install or upgrade an active unit:

if bigip["System.Failover"].get_failover_state == "FAILOVER_STATE_ACTIVE"
  question = "\nWARNING: you are installing on an ACTIVE unit! Are you sure you want to proceed? (no/yes) "

While the warning message may seem like an annoyance if you’re working in a lab or development environment, it can prevent a catastrophic clobbering in a production environment. This method can also be handy for detecting unit failovers. 

Lastly, we’ll want to go ahead and update the system. The software image install is facilitated by the install_software_image method in System::SoftwareManagement interface. The install_software_image method takes 4 arguments, all strings: install_volume (HD1.2), product (BIGIP), version (10.2.1), and build (297.0). If we wanted to install BIG-IP version 10.2.1, build 297.0 on our system, we’d issue the iControl call as such:

bigip["System.SoftwareManagement"].install_software_image('HD1.2', 'BIGIP', '10.2.1', '297.0')

We make short work of extracting these parameters from our ISO image file by using Ruby’s built-in scan method:

"BIGIP-".scan /(\w+)-(\d+\.\d+\.\d+)\.(\d+.\d+)/ => [["BIGIP"], ["10.2.1"], ["297.0"]]

The Application

Now that we’ve walked through the underpinnings, we can look  at the application as a whole and its usage. In order to connect to the BIG-IP via SSH and the web UI, we’ll need two separate users: one with root-level shell access and another with administrative privileges on the web UI. Some will set the ‘root’ and ‘admin’ passwords to be the same, but this application assumes the two are mutually exclusive. Along with credentials, we’ll also need to know the location of the software image ISO and what slot to install the image to. Bringing it all together, here is approximately what we’ll arrive at:

install-bigip-image.rb -b -u admin -s root -p admin --bigip-shell-pass default -f BIGIP- -h HD1.1

There is also a help section available if the application is executed without arguments:

install-bigip-image.rb -b  -u 
  -b (--bigip-address)    BIG-IP management-accessible address
  -u (--bigip-web-user)   BIG-IP web interface username (must have administrator privileges; defaults to 'admin')
  -p (--bigip-web-pass)   BIG-IP web interface user password (will prompt if not specified)
  -s (--bigip-shell-user) BIG-IP Secure Shell (SSH) username (must have root privileges; defaults to 'root')
     (--bigip-shell-pass) BIG-IP Secure Shell user password (will prompt if not specified)
  -f (--install-image)    path of ISO image for BIG-IP install image
  -x (--skip-upload)      skip uploading of ISO image (already on BIG-IP in /shared/images)
  -h (--hd-slot)          installation slot (HD slot) to install to
     (--help)             shows this help/usage dialog

The full application can be download from the iControl CodeShare under InstallSoftwareImage.

Published Apr 29, 2011
Version 1.0

Was this article helpful?

1 Comment

  • Bill_Church_988's avatar
    Historic F5 Account
    Great article! I especially like using the regex to pull the verision out of the .ISO file name.



    It's probably worth mentioning that the 'admin' account can be used for both the scp as well as the iControl portion as long as it's assigned a valid shell (advanced, tmsh, bigpipe, etc...)



    Some organizations frown on using root in such a manner.