• Introduction
• Using the Tool
• How it works
• More Information

Introduction

Iguana Configuration Utility: This is a Iguana web application which is designed to reduce the effort and risk involved in upgrading an Iguana 6.0 instance to a more recent version.

The tool:

1. Discovers what versions of Iguana are available on our download website.
2. Will download and unpack each version that you as a the user select.
3. Makes it easy to update the maintenance expiry date.
4. Will stop the current Iguana instance and restart it to use the desired version of Iguana.

The tool automates the best practices as described for Multiple instances of Iguana using a single install folder.

Before you use the tool make sure that:

1. The host operating system is either Linux or Windows.
2. That you know the username and password of a user with administration privileges on windows if you are using windows.
3. That you know the username and password for the iNTERFACEWARE members licensing portal.
4. That the machine has internet access to our licensing system and to our download site.  If your organization has restrictions around this access, then the utility is not likely to work.
5. That you have a valid Iguana ID which has been correctly registered through our members licensing portal.
6. Your company has valid paid up maintenance and support.
7. If you are using Linux then you will need to have it set up to start under a given user account using cron – as configured by this tool. It is unlikely to work if you have your own custom scripts to stop and start Iguana until you change it to be compatible with this tool. See how it works for more information.
8. That you try this utility on a test or development system successfully before attempting to use this utility in production.

Using the Tool [top]

• Import the Iguana Configuration Utility channel from the Builtin: Iguana-Upgrade repository.
• Run the channel.
• This is an HTTP(S) channel – click on it’s URL and you should see a mini version dashboard.  The current version of Iguana will be highlighted in green.  For example:
• Upgrade the maintenance expiry date by clicking on the Update? link as shown. You will see a screen like this:
• Enter your valid username and password for our licensing portal.  If you enter the correct details and your account is up to date with maintenance you should see this:
• To download a version of Iguana which has not been downloaded yet, click on the No hyperlink with the red rectangle:
• After you have clicked on the link if the utility has successfully downloaded this version of Iguana the screen should look something like this:
• To stop the current instance of Iguana and restart it to run with a new version, click on the Activate? link.
• In Windows you will be prompted for the username and password of a Windows user that has administrative privilege on the host windows operating system.
• The screen should refresh and display a dialog like this:
• You should then be taken to the login screen for Iguana which will take you into the dashboard of the given Iguana instance running the new version of the application.
• If you go back into the Iguana Configuration Utility you should see something like this:
• If you wanted to roll back to the earlier version of Iguana you would click on the Activate? link for that version.
• Since the utility stores each version of Iguana in it’s own separate directory you might choose to click on the Remove? link to remove these files to save disk space when you are confident that a rollback to this version is not required.

In summary this utility makes it very fast and convenient to upgrade to a new release of Iguana – yet gives the control to easily roll back to your current version if there are any issues that make this necessary. This is a new valuable tool in making it easier to manage the otherwise tedious process of upgrading Iguana to the most recent version.

How it works [top]

The tool is a scripted implementation of the best practices described in the Multiple instances of Iguana using a single install folder.

It takes the current working directory of the running Iguana instance and does not change it. The configuration files, GIT repository and SQLite databases that are stored in the working directory are left alone.

For this matter any Iguana application files which might be present in the working directory are also left alone for safety. If you are careful you may choose to remove these at a later date – but this utility does take the risk of automatically modifying these files.

It looks at the available 6.0 versions of Iguana by visiting https://dl.interfaceware.com/iguana/windows/  or https://dl.interfaceware.com/iguana/linux/ and listing all the versions above 6.0.  The utility will not work on older versions of Iguana.

When it downloads each version it unpacks the manual install package into a directory structure with a separate directory for each version.

For Linux the directory structure is:

• $(HOME)/Iguana-6/Releases/6_A_B where A and B are the minor and patch release numbers respectively.  $HOME is the home environmental variable defined for the user id that the Iguana instance is running under.

For Windows the directory structure is:

• <program files>\Iguana-6\Releases\6_A_B where A and B are the minor and patch release numbers respectively.

This follows the best practices of separating the Iguana configuration files from the Iguana application files which makes it easy for the utility to swap versions.

On Windows the utility makes use of the Windows Scheduler to:

• Stop the current instance of Iguana
• Unregister the service for that version.
• Register the new version of Iguana
• Start the service.

On Linux the utility has to follow a different approach which most likely won’t be compatible with how you start and stop Iguana on your current Linux system.  To use the utility this means you’ll need to change your Linux configuration if you wish to use this utility. This is how it works:

1. It creates a script in the home directory of the user ID that Iguana is running under – $(HOME)/iguana_restart.bash.
2. It invokes this script.
3. The script will:
   • Terminate the iguana_service process
   • Close any file descriptors inherited from Iguana (the parent process)
   • Start Iguana up again by calling “iguana_service” from the appropriate “$(HOME)/Iguana-6/Releases/…” directory

The restart can be fast – but be aware that if you:

1. Have a very long GIT history for the Iguana instance.
2. Very big log files

That these two things may slow down the restart of Iguana. As always we do advise that you use this utility on a test or development system first to validate that it is compatible with your environment before trying this in production.

More information [top]

• Read about Multiple instances of Iguana using a single install folder.
• The source code to the utility can be found on Github in https://github.com/interfaceware/iguana-upgrade