- Introduction
- Why is this important?
- Initial Configuration
- Changing the Logs Directory
- Upgrading an Iguana Instance
- Rolling back to an older version
- Troubleshooting
- Helpful Tips
- More Information
Introduction
This document outlines best practices for installing Iguana in a manner which:
- Makes upgrades easy and risk free.
- Keeps it simple to reliably back up your Iguana server.
- Simplifies important system administration tasks such a rebuilding a server, patching the operating system and so on.
The key concept here is the separation of concerns by having different directories for Iguana’s:
- Application files.
- Configuration files.
- Logs.
The document assumes you are using Windows but the concepts can be applied to other operating systems. It also assumes an environment that is only running one instance of Iguana per server and the upgrades are done with the entire instance at once.
The key thing is to understand the principles explained, as there is no single solution for all scenarios, please contact support at support@interfaceware.com if you need more help with your installation.
Why is this important? [top]
The default automatic installer of Iguana lumps all of these files together. This is okay for a casual non production installation. We want to make it easy for people who are curious about Iguana to get up and running. But it is not the best practice for a system configured by a professional system administrator for production.
An interface engine is like a database, anyone can download and click through an automated installer and ‘install Oracle’ but it takes more care to do a professional production installation of Oracle that will be correct for production deployment.
Fortunately installing Iguana correctly is a lot easier than the skillset required for an Oracle database administrator. To do the job right though takes a little more care than just clicking on the automated installer. It’s about investing a little time and thought up front and not getting caught with your pants down later.
Let’s go through the advantages of cleanly separating out the parts of Iguana.
Configuration files are valuable and need to be protected
Configuration files which include channel configuration, lua scripts, vmd files for many customers represent intellectual property in which literally hundreds or even thousands of labor hours have been invested. Having these in a separate directory makes it easy to do backups. It makes it easy to rebuild a server if the operating system gets corrupted. It limits the sizes of those backups so that they can be done more frequently. It makes it more transparent and easier for technical people working on the server to troubleshoot when issues occur.
Keeping them separated from log files is a good idea because logs files are huge, they change much more frequently and so a different kind of backup routine is desirable.
Log files belong on their own partition
Best practice means that log files should ideally be installed on a partition which is different from the partition that the operating system is installed on. Consider if you have an interface which goes rogue. This results in a huge unexpected volume of log data. If the logs are on the same partition as the operating system it can seriously affect the integrity of the server.
Application files should be disposable
As a system administrator you should be able to drop in a new version of Iguana and delete an old version without the slightest bit of worry of losing your configuration files or your log files. That’s why it makes sense to keep application files in their own directory.
Why not just rely on virtual machine snapshots?
It’s tempting to think these things don’t matter when you have virtualized servers that make it easy to roll a server back. But, it’s not as good of a solution because of the lack of separation of concerns.
Some operating systems like Windows do degrade over time. They need to be patched. You periodically need to upgrade to new server OS versions. Sometimes to make windows servers run well the need arises to reinstall from scratch. If you rely on snapshots to manage backups it makes it opaque as to how to rebuild a machine from scratch which is a necessary part of system administration.
If you need to restore an older configuration but you need to keep the logs then it’s harder to do that. Also backing up the entire machine with logs takes a lot more storage, whereas if the configurations are backed up independently it’s a lot easier to store the history for those backups for a longer period of time because the amount of data is much smaller.
Initial Configuration [top]
Keep your Iguana configuration files in a common directory like:
C:\IguanaConfig\
The log files should be installed on a separate partition like:
D:\IguanaLogs\
Each version of Iguana should be stored in its own directory which should include the version number like:
C:\Iguana-5-6-15\ (C:\Iguana-<version number>\)
It is easy to get the latest no installer version of Iguana just click the Other downloads are available below link on our iNTERFACEWARE Downloads page, and select the Windows 32 or 64 bit Manual Installer. See Download other install files for all other operating systems and older releases.
Just unpack the contents of this zip file into a directory explicitly named after the version.
i.e. C:\Iguana-5-6-15\.
Within this directory it is necessary to edit a file called iguana_service.hdf which gives the configuration for running the Iguana service. The content of the file should be this:
application{
service_kill_timeout = 500000
service_display_name=iNTERFACEWARE Iguana
service_name=Iguana
service_description=HL7 Integration Engine
command_line=iguana.exe --working_dir C:\IguanaConfig\
command_line_unix=./iguana
path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
Note: If your working directory path contains spaces (like C:\Program Files\iNTERFACEWARE\Config\) you will need to enclose it in quotes, like this:
application{
service_kill_timeout = 500000
service_display_name=iNTERFACEWARE Iguana
service_name=Iguana
service_description=HL7 Integration Engine
command_line=iguana.exe --working_dir "C:\Program Files\iNTERFACEWARE\Config\"
command_line_unix=./iguana
path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
The critical piece of information is the –working_dir argument. This tells Iguana where to get its configuration files from, in this case you can see we are getting them from C:\IguanaConfig\.
Tip: You may want also to change the display_name and/or the service_name to match the version number of Iguana, to make it more obvious which version the service is running.
The result would look like something this:
application{
service_kill_timeout = 500000
service_display_name=iNTERFACEWARE Iguana 5.6.20
service_name=Iguana_5_6_20
service_description=HL7 Integration Engine
command_line=iguana.exe --working_dir C:\IguanaConfig\
command_line_unix=./iguana
path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session Manager\Environment
}
To install the Iguana service one needs to use the command line console, change into the directory and run this command, i.e.
cd C:\Iguana-5-6-15\ iguana_service --install
You can then start the Iguana service using the Windows Service control panel or if you are comfortable using the command line then:
net start Iguana net stop Iguana
Can be used to start and stop the Iguana service.
Changing the Logs Directory [top]
An Iguana Installation configured as described above (in Initial Configuration) will store logs here:
C:\IguanaConfig\logs
This location can be changed by editing:
C:\IguanaConfig\IguanaConfiguration.xml
And altering the “log_directory” attribute of the <log_config> tag, for example to D:\IguanaLogs\:
<log_config
log_purge_time_hour="0"
log_purge_time_minute="0"
log_directory="D:\IguanaLogs\"
max_log_age_days="60"
log_sync_type="off"
And then re-starting the Iguana Service.
If you want to preserve any existing logs then it will be necessary to copy them from their original location C:\IguanaConfig\logs (the original location C:\IguanaConfig\logs should then be deleted).
Upgrading an Iguana Instance [top]
Upgrading an Iguana instance that has been professionally configured as above is an easy 15 minute process. Before you start it though you should check the ‘maintenance expiry’ date on your instance of Iguana. You might need to ask iNTERFACEWARE to refresh this license key if the date is less than the date that the new version of Iguana that you are installing was released. See refreshing maintenance expiry date for more information.
- Download a no installer zip file for the new version of Iguana. Make sure you pick the right operating system and 32 vs. 64 build etc.
- Extract the zip into a fresh new versioned folder. i.e. C:\Iguana-5-6-15\
- Replace the iguana_service.hdf file with the following contents:
application{ service_kill_timeout = 500000 service_display_name=iNTERFACEWARE Iguana service_name=Iguana service_description=HL7 Integration Engine command_line=iguana.exe --working_dir C:\IguanaConfig\ command_line_unix=./iguana path_registry_entry_win32 = SYSTEM\CurrentControlSet\Control\Session\Manager\Environment } - Use the command line console to change directory into the folder you extracted the files into.
- Then run the command:
iguana_service --install - This will stop the existing service and replace it with the new service.
- You must restart the Iguana service now to begin running the new version of Iguana.
- Login into the Iguana dashboard and verify that the channels are running correctly that should be running.
The beauty of this process is that it doesn’t take long and it’s really easy to roll back to an older copy of Iguana. The rollback process is even easier if you keep the service_name parameter as it’s default value of “Iguana”.
Rolling back to an older version [top]
Rolling back to an older version of Iguana is a very similar process to that described above (in Upgrading an Iguana Instance).
- Use the command line to change into the application directory of the current Iguana version.
- Run the command:
iguana_service –uninstallNote: If you are using the same service_name as previously then uninstalling the old service is not strictly necessary, as the install command (iguana –install) will stop the existing service and replace it with the new service (with the same service name).
However we recommend that you perform the uninstall to “prove” that old service is removed (rather than trusting the install command to do a “silent” uninstall).
- Use the command line to change into the application directory of the older Iguana version to rollback to.
- Run the command:
iguana_service --install - Restart the Iguana service using the Services control panel or using net start Iguana at the command line.
- Login into the Iguana dashboard and verify that the channels are running correctly.
Warning: If you are using any new features in the current install you will need to disable them before rolling back, you can do this by setting the scripts in the affected channels to run earlier milestones (or by modifying the scripts).
Troubleshooting [top]
One of the great things about this process of installation is that it makes things very transparent and easy to troubleshoot. If the Iguana service does not start then one can see what is going on by running Iguana as a console process and looking at its output. It’s easy.
To do it change into the Iguana application directory and run it like this:
>iguana –run –working_dir C:\IguanaConfig\
This is a great way to diagnose problems such as Iguana not being able to listen on a given webport, issues with log files and so on. I would recommend it as a technique for any Iguana system administrator as a means of validating each stage of an installation or upgrade.
See troubleshooting for more information.
Helpful Tips [top]
Disabling Auto-Start of Channels.
Sometimes during upgrades it can make sense to turn off auto-starting of all channels. There is a helpful screen you can do this from, called the Channel Properties screen.
Extracting Configuration Files from an Existing Iguana Installation.
If you have inherited an existing Iguana installation that has everything in one directory you will need to copy out the install files into a C:\IguanaConfig\ directory. A good reference for this is to see the backup procedure which documents the handful of files that you need to copy.
License keys
License keys for Iguana are keyed off the configuration directory. So if you change the configuration directory you will need a new license key. However if you do not, then this is not necessary.
Deleting old Iguana versions
This is not strictly necessary, but it is easy to do when you are happy no rollback is required. Just delete the contents of the directory which contain the application files. It’s easy when you have only application files in the Iguana application directory.