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 Upgrade
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. You are prompted with:
Enter instance name:
Type the name of the instance you want to upgrade. If you do not type the name of an existing instance, you will begin an installation using the new kit instead of an upgrade. To confirm that you are upgrading an existing instance make sure you are prompted with:
Do you want to update InterSystems IRIS instance 'IRIS' <Yes>?
and not:
Do you want to create InterSystems IRIS instance 'IRIS' <Yes>?
Step 4: Choose Installation Type
You are prompted to choose which installation type to perform:
Select installation type.
1) Development - Install InterSystems IRIS server and all language bindings
2) Server only - Install InterSystems IRIS server
3) Custom
Setup type <1>?
Upgrades using the Development or Server only installation types have fewer options when performing the upgrade. The Custom installation type provides additional upgrade options.
Step 5: Modify Group to Start or Stop the Instance
You are prompted to change the group that is allowed to start and stop the instance:
What group should be allowed to start and stop this instance <existinggroup>?
where <existinggroup> is the group currently configured to start and stop the instance.
If you would like to change the group, enter the name or group ID number of an existing group; the installer will verify that the group exists before proceeding.
For more details, see Determining Owners and Groups.
Step 6: Configure Effective Group
Custom installation type only
You are prompted to configure the effective group for InterSystems IRIS processes:
What is the effective group for InterSystems IRIS processes <exisitinggroup>?
where <existinggroup> is the currently configured effective group for InterSystems IRIS processes. This is the InterSystems IRIS internal effective group ID, which also has all privileges to all files and executables in the installation. For maximum security, no actual users should belong to this group.
If you would like to change the group, enter the name or group ID number of an existing group; the installer will verify that the group exists before proceeding.
For details, see Determining Owners and Groups.
Step 7: Configure Web Server
If a local web server is detected, you are prompted if you would like to use the web server to connect to your installation:
Local web server detected. Would you like to use the web server to connect to this installation <Yes>?
If you enter y, the installer configures your web server to serve requests to your instance. If the web server was already configured, then no action is taken. When performing a custom installation, the installer prompts you to provide additional configuration information including the location of the httpd.conf file and the Apache httpd port number.
If you enter n, the web server will not be connected automatically. If a web server was already connected, it will not be disconnected. However, if a web server was not connected, you will have to configure it manually after the installation finishes.
If a web server is not detected, you are prompted if you would like to abort:
No local web server found. Would you like to abort the installation <Yes>?
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 installation or upgrade process. Make sure it is installed and running in the default installation location before beginning the upgrade process. In most cases, it is not necessary to manually configure the Apache web server.
Step 8: Activate License Key
If a license key is detected in the <install-dir>/mgr/ directory, then this step is skipped.
If a license key is not detected, you are prompted to enter a license key:
InterSystems IRIS did not detect a license key file
Do you want to enter a license key <No>?
If you input y, you are prompted to input the filepath:
License key file:
Input a path to the iris.key file to automatically activate the key; it is copied to the instance’s /mgr/ directory. If you do not specify a license key, you can activate a license key following installation. See Activating a License Key for information about licenses, license keys, and activation.
Step 9: Run the Upgrade
The installation script summarizes the upgrade options and again asks you to confirm the upgrade:
Please review the installation options:
---------------------------------------
...
<installation options>
...
---------------------------------------
Confirm InterSystems IRIS upgrade <Yes>?
Input y 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 10: 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.
