Installation FAQs

This section contains answers to common questions about installing Iguana.


If the Maintenance Expiry Date for the license has expired, then the server will not start after the upgrade. Therefore it can be useful to check before upgrading.

To solve this issue

  1. Check the Maintenance Expiry Date in Settings > Software License> Iguana ID & License Info:
    If the date is less than the the current date your server would not work after an upgrade (until a new license is obtained).
  2. Contact support at with your Iguana ID and request an updated license code with a more recent date.


This can happen for various reasons, the solution is always the same.

Usually it is because the Maintenance Expiry Date for the license has expired, or that a new Iguana ID was generated after the upgrade.

You can check the Maintenance Expiry Date in Settings > License Entitlement:
If the date is less than the the current date your server will not work until a new license is obtained.

To solve this issue

  1. Log into your user account and activate a temporary license to regain access to the software.
  2. Then contact support at with your Iguana ID and request an updated license code with a more recent date.

There are two options: Separate install directory, or Shared install directory and separate working directory

Separate install directory

Use the manual installation process and install each instance in a separate directory. This is the simplest setup, it’s good for a development and testing where you want to the flexibility to run different versions of Iguana.

  • Advantage: Less planning required to create multiple Iguana Instances
  • Advantage: Easier to add/remove Iguana Instances
  • Advantage: You can use several different versions of Iguana
  • Disadvantage: You need to upgrade each install separately
  • Disadvantage: Duplicate install directories use slightly more disk space

Shared install directory

Create a common install directory and use separate working directories, see Multiple instances of Iguana using a single install folder. This setup requires a little planning, it is good for a production environment where you need to ensure all your Iguana Instances are using the same version.

  • Advantage: All Iguana Instances will use the same version
  • Advantage: All instances are upgraded together
  • Advantage: A single install directory use slightly less disk space
  • Disadvantage: More planning required to create multiple Iguana Instances
  • Disadvantage: Harder to add/remove Iguana Instances

Sometimes you hear about features which are not in the formally released version of Iguana. That doesn’t mean you have to wait before you can try them out yourself.

It’s helpful to understand how we manage our builds.

When we develop new features they usually are put into the “head” or “unstable branch” of Iguana. This is because while these features are “under construction” they may result in bugs and other side effects. The “unstable branch” occasionally will get broken but it always has the newest set of features that are under development.

When features look mature enough, the changes get promoted into the “stable branch” of Iguana. This is what will become the next incremental release of Iguana, as delimited by the minor version numbers. The “stable branch” snapshot is much less bleeding edge.

Obviously the “unstable branch” snapshots should not be put into mission critical production environments, although you can often get away with using them in development so long as you are willing to test a little with your production release before deploying.

We make these snapshots publicly available. These are rebuilt and uploaded to our public download site every day. The help center download page has links to the automatic installer and manual install files for both branches. Enjoy.

When you are installing multiple instances of Iguana (as windows services) on a single server, you need to ensure that each instance uses a different service name. Before installing the service (using iguana --run) you need to change the the service_name and (optionally) the service_description (easier to differentiate between services). If you do not change the service name you will overwrite any existing service with the same name.

The iguana_service.hdf file that the iguana_service.exe file will load up (iguana_service.exe is bootstrap program responsible for invoking the main iguana.exe as a service). Under Windows it defines how the service will appear in the Services window.

Some key parameters:

  • service_name: the name of the service. Pick something like “Iguana5”. Then net start Iguana5 can be used to start the service.
  • service_description: how the service is described in the service window. Useful for putting in more descriptive information.
  • command_line: This is useful for including special flags to be passed to the main Iguana executable like --working_dir <dir-name>

It is important to change the service_name otherwise another Iguana service entry can be overwritten. Ideally you should also change the service_description to easily differentiate between services.

The other parameters typically do not need to be altered:

   service_kill_timeout = 500000 
   service_display_name=iNTERFACEWARE Iguana
   service_description=HL7 Integration Engine
   path_registry_entry_win32 = SYSTEMCurrentControlSetControlSession ManagerEnvironment

This can occur when you are installing multiple instances of Iguana on a single machine (particularly for the first time). Don’t panic it is very simple to fix!

It’s possible that you might make this mistake:

  1. You start off with an Iguana instance installed by the automatic installer at say “C:Program FilesiNTERFACEWAREIguana”
  2. But overwrite the service entry by doing a manual installation of Iguana without editing iguana_service.hdf to change the service name.
    For more information see the FAQ: “How to change Iguana Service details in the iguana_service.hdf file”.

Now what you will see is only one Iguana service registered, but it will be the new Iguana not the old instance.

Your old Iguana instance is still there. All you need to do is:

  1. Use the command prompt to do cd “C:Program FilesiNTERFACEWAREIguana” or wherever your original Iguana was installed.
  2. Run iguana_service –install

That will restore your original service. Then:

  1. Use the command prompt to cd back into the directory of your new manually installed Iguana.
  2. Edit the iguana_service.hdf to change the service name to be something different from the first install.
  3. Register it as a service using iguana_service --install

That should leave you with two independent Iguana services.

The IguanaConfiguration.xml file is usually located in the Iguana IguanaConfigurationRepo directory (<Iguana Install directory>/IguanaConfigurationRepo). To change settings simply open the file in a text editor and change the desired settings (you can use TextEdit on Mac if you disable Smart Quotes “Edit>Substitutions>Smart Quotes”). As a precaution it is wise to make a backup copy of the file first.

Note: The IguanaConfigurationRepo directory and the IguanaConfiguration.xml file are not included in the install, instead they are created the first time that you run Iguana.

Tip: If you cannot find the IguanaConfiguration.xml file.

The IguanaConfiguration.xml file is actually located in the Iguana working directory, which defaults to the Iguana install directory. This means that you have a custom install and the working directory has been changed. You need to look at the –working_dir option for the command_line or command_line_unix entry in the iguana.hdf file. For example:

command_line=C:IguanaAppiguana.exe --working_dir "C:Program FilesiNTERFACEWAREIguanaIguanaDev" -- path quoted because it has spaces
command_line_unix=/home/iguana/iguana_app/iguana --working_dir /home/iguana/dev/

The most commonly edited setting are:

  • The web configuration port: The “port” attribute in the <web_config> element
  • The log directory: The “log_directory” attribute in the <log_config> element
  • The plugin port: The “port” attribute in the <rpc_config> element
 server_label="Iguana A Instance"/>

To move or copy Iguana working directory:

  1. Make sure that all the unsaved files are saved to milestones.
  2. Move (or copy) the working directory to a new location.
  3. Go to the new location and erase the edit sub-directory.
  4. Different actions are required for moving or copying the working directory
    • Moving: Update the command_line entry in Iguana service/daemon file (iguana.hdf) file to reflect the new working directory:
      command_line=iguana.exe --working_dir <new-dir-name>
    • Copy: Usually you would be copying to a new (or different) Iguana Instance, you will need to update the appropriate target service/daemon file, e.g., iguana.hdf in another install directory (or another machine), or possibly iguanaA.hdf/iguanaB.hdf./iguana<your-name>.hdf if you are running multiple “shared install” instances (see Multiple instances of Iguana using a single install folder for an example of how “shared install” works).

If you ever encounter any problems with the installation or uninstallation of the Iguana service, you can easily install (or uninstall) the service from a command prompt.

To install the Iguana Service:

  • Open the Command Prompt window.
  • At the command prompt, type in iguana_service –install as shown below:
C:Documents and SettingsAdministrator>iguana_service --install
Installing service...
Service installed.

To uninstall the Iguana Service:

  • Open the Command Prompt window.
  • At the command prompt, type in iguana_service –uninstall as shown below:
C:Documents and SettingsAdministrator>iguana_service --uninstall
Uninstall the service...
Service uninstalled.

Mapped drives will only be accessible for the user that originally created the drive mapping. This means that the Iguana service must log-in as that user to access that drive. In order to make mapped drives accessible for all users, you must change the Iguana Log On Properties for the Iguana service called iNTERFACEWARE Iguana.

Note: The Local System account cannot be granted permissions to shared files or directories because they are on another machine. Therefore a different user must be created and granted share permissions, and then used as Iguana Service logon.

To get the Iguana service to work with your network drive in Windows:

  1. Create the Iguana service user and assign local administrator rights.
  2. Logon as the new user and map the shared drive.
  3. Click Start > Settings > Control Panel > Administrative Tools > Services. The Services window appears:
  4. Right-click iNTERFACEWARE Iguana, and select Properties. The iNTERFACEWARE Iguana Properties window appears:
  5. In the iNTERFACEWARE Iguana Properties window, click the Log On tab.
  6. Under Log on as, select This account.
  7. In the This account field, type in the user name the Iguana service will log on as, or use the Browse button to select a user name from a list:
  8. In the Password and Confirm Password fields, type in the user name passwords.
  9. Click Apply to save your changes, and then click OK.

You must also change all of your VMD paths in Iguana to the network path name.

To determine what the network path name is for your shared network drive:

  1. Open the Command Prompt window.
  2. At the command prompt, type in the drive letter of your shared network drive.
  3. Then type in net use as shown below:
    G:>net use
    New connections will not be remembered.
    Status Local Remote Network
    OK G: \server_namedirectory Microsoft Windows Network
    The command completed successfully.
  4. In Iguana, replace all of the VMD path names with the network path name. In the example above, the network path name is \server_namedirectory.

Leave A Comment?