Upgrade an Instance on UNIX®, Linux, or macOS
Step 1: Confirm Prerequisites
Confirm that you have completed all necessary pre-upgrade steps.
If you are upgrading a mirrored system, review Upgrading a Mirror for specific details on upgrading mirrored systems.
If you are upgrading an ECP configuration, review Upgrading ECP Configurations for specific details on upgrading ECP configurations.
If you are using a manifest as part of your upgrade process, see the instructions in Creating and Using an Installation Manifest before performing the standard installation steps.
If the profile of the user executing irisinstall has a value set for the CDPATH variable, the upgrade fails.
Step 2: Shut Down the Instance
Prior to beginning an upgrade of an instance, it is essential that the instance be shut down cleanly. To verify that the shutdown was clean, examine the messages.log file after the shutdown finishes. If the log contains entries similar to the following, then the shutdown was clean:
... 05/03/19-14:24:13:234 (5204) 0 Journal restore not required at next startup 05/03/19-14:24:13:234 (5204) 0 Transaction rollback not required at next startup ...
If these entries are not present, the instance did not shut down cleanly. Please contact the InterSystems Worldwide Response CenterOpens in a new tab before proceeding with the upgrade.
Step 3: Begin Installation
If your installation kit is in the form of a .tar file, you must first uncompress it. As a user with root privileges, start the installation procedure by running the irisinstall script, located at the top level of the installation files:
# sudo sh /<pathname>/irisinstall
where <pathname> is the location of the installation kit, typically the temporary directory to which you have extracted the kit.
The script displays a list of all existing instances on the host. At the Enter instance name: prompt, type the name of the instance you want to upgrade, and press Enter.
Step 4: Add New License Key
When prompted for a license key file, type keypath\iris.key, where keypath is the location of the new iris.key file. If the installation script detects the new license key in the install-dir/mgr directory, the script proceeds without prompting you for the license key file.
Step 5: Configure Web Server
If a local web server is detected, you will be asked if you would like to use the web server to connect to your installation. If you enter y, the web server will be connected automatically. If you enter n, the web server will not be connected automatically and you will have to configure it manually after the installation finishes. If a web server is not detected, you will be asked if you would like to abort. If you choose to continue the installation, you will have to configure your web server manually after the installation finishes.
InterSystems recommends using the Apache httpd web server because it can be automatically configured during the upgrade process. Make sure it is installed and running before beginning the upgrade process. In most cases, it is not necessary to manually configure the Apache web server.
Step 5.5: Change Effective Group for Processes (Custom Only)
Only applies to Custom Upgrades
If you selected a custom upgrade, the system prompts you to provide an Effective group for InterSystems IRIS processes. The default for this is to keep the same effective group from the original install. If you change the group, the system will update the ownership of all files in the installation directory that were previously owned by the original effective group to the new effective group. Please note that you are responsible for updating the ownership of any files created outside the IRIS installation directory to ensure continued access. Refer to the documentation on determining groups for more details.
Step 6: Run the Upgrade
The installation script summarizes the upgrade options and again asks you to confirm the upgrade. Press Enter to continue with the upgrade.
Do not interrupt the installation while it is in progress. If the upgrade fails with any error messages, correct the issues and restart the upgrade installation.
After the upgrade finishes, the instance restarts and any installation manifest is run.
Step 7: Examine Logs for Errors
Examine messages.log, iboot.log, and ensinstall.log in the install-dir/mgr directory for any errors. If any fatal error is found, correct the error, and then run the installation script again.
If your operating system is configured to use huge memory pages, check the startup messages to make sure shared memory is being allocated in accordance with these settings. If you see a message similar to the following, reallocate huge pages to be greater than the shared memory allocation, then reboot your server to avoid an out-of-memory situation.
Failed to allocate 1468MB shared memory using Huge Pages. Startup will retry with standard pages.
