ROCm Offline Installer Creator#
2024-11-19
29 min read time
The ROCm Offline Installer Creator creates an installation package for a preconfigured setup of ROCm, the AMDGPU driver, or a combination of the two on a target system without network or internet access.
On a system with internet access (known as the host), the tool creates an installer package. It uses the host system as the template for a matching offline system (known as a target). After creating the offline installer package, you can run it on a target without network access to install ROCm and the AMDGPU driver.
The ROCm Offline Installer Creator lets you customize multiple unique configurations for use when installing ROCm on a target.
The ROCm Offline Installer Creator features:
A lightweight user interface
An easy-to-use user interface for configuring the creation of the installer
Support for multiple Linux distributions
Installer support for different ROCm releases
Installer support for specific ROCm components
Optional driver or driver-only installer creation
Optional post-install preferences
Lightweight installer packages, which are unique to the preconfigured ROCm setup
Resolution and inclusion of dependency packages for offline installation
Prerequisites#
The ROCm Offline Installer Creator requires the following configuration:
The host must be connected to the network and internet when running the ROCm Offline Installer Creator.
The host system running the ROCm Offline Installer Creator and the target system running the installer must use the same Linux distribution, release version, and Linux kernel version.
For example, if the host system uses Ubuntu 22.04.4 with the 6.5.0-44-generic kernel, only an Ubuntu 22.04.4 target with the 6.5.0-44-generic kernel can use the offline installer. If the base OS distribution version and the kernel version of that distribution do not match on both systems, installation is not permitted.
The following configuration is recommended when using the ROCm Offline Installer Creator:
The host system running the ROCm Offline Installer Creator and the target system should use the same OS image and have the same packages installed.
The host OS should not have ROCm or the AMDGPU driver installed. (This recommendation doesn’t apply to any AMDGPU drivers included with the default distribution packages.)
Supported Linux distributions#
The ROCm Offline Installer Creator tool supports the following Linux distributions and versions:
Ubuntu: 20.04, 22.04, 24.04
RHEL: 8.10, 9.4
SLES: 15.5, 15.6
Getting started#
The ROCm Offline Installer Creator is distributed as a self-extracting .run
package. Launch the tool from
any directory on the host system to create an offline installer.
Download the Offline Installer Creator from repo.radeon.com
using the following command:
wget https://repo.radeon.com/rocm/installer/rocm-linux-install-offline/rocm-rel-<rocm-version>/<distro>/<distro-version>/<creator-package>
Substitute your values for the following placeholders:
<rocm-version>
: ROCm version number for the ROCm Offline Installer Creator tool.<distro>
: Linux distribution for the tool.<distro-version>
: Linux distribution version for the tool.<creator-package>
: The ROCm Offline Installer Creator package name.
For example, use this command to download ROCm version 6.2 of the Offline Installer Creator for Ubuntu release 22.04:
wget https://repo.radeon.com/rocm/installer/rocm-linux-install-offline/rocm-rel-6.2/ubuntu/22.04/rocm-offline-creator_1.0.0.60200-3~22.04.run
Installer Creation#
On the host system, run the ROCm Offline Installer Creator from the terminal command line as follows:
./rocm-offline-creator_1.0.0-local.run <options>
The <options>
parameter can either be left empty or set to these options:
help
: displays information on how to use the Offline Installer Creatorversion
: displays the current version of the Offline Installer Creatorprompt
: enables user prompts during offline installer creationconfig=
: specifies the full path to a.config
file that contains a configuration for creating an offline installer. This parameter is used for testing purposes. See the Testing section for more information.wconfig=
: specifies the full path to a.config
file that is created using the current configuration settings when the user exits the user interface. When this option is specified, the ROCm Offline Installer Creator does not create an installer package. This option is used for testing purposes.
Note
The prompt
and config
options can be combined in the same command.
This example demonstrates how to use the prompt
option when running the Offline Installer Creator:
./rocm-offline-creator_1.0.0-local.run prompt
The optional prompt
parameter stops the Offline Installer Creator
at critical checkpoints in the creation process and prompts the user. At these checkpoints,
the user can either continue or end the program. Without the prompt
parameter, installer creation continues
without interruption, unless a failure occurs during the process.
After extracting the .run
package, the Offline Installer Creator displays
the Main menu. From here, you can customize the offline installer using the Create Configuration
menu and options in the ROCm, driver, and extra packages menus.
After configuring all the options, select Create Offline Installer to review the settings
and start the offline installer creation process. After the installer is created, the offline installer .run
package
is saved to the configured location. Copy this package to any matching target system for ROCm
and driver installation.
Offline Installer Creator interface#
Use the Offline Installer Creator user interface to configure the contents of the ROCm and driver installation package for later use on the target system.
Starting from the Main menu, the Offline Installer Creator user interface contains multiple menus and sub-menus used to configure and create the offline installer. The following section describes the menu items:
Using the ROCm Offline Installer Creator#
After starting the Offline Installer Creator, the user interface appears in the terminal. At the top of the Main menu, the Target Installer field indicates the Linux distribution, version, and Linux kernel version currently running on the host system. The target system must match the host system because the target installer is based on the current host distribution and kernel version. When navigating through the menus, you can use the Done option to return to the previous menu. Some menus have a Help option to display more information about the current menu.
Follow these steps to create an offline installer:
Fill out the configuration creation details:
Enter the Create Configuration menu.
Set the Dependency Download Type to either
full
, which is the default, orminimum
.Set the Installer Name field or use the default name that is provided. The Offline Installer Creator appends the
.run
extension to the installer name when it creates the installer.Use the Installer Path field to configure the output directory for the installer. The default value is the
$USER
home directory.
Set the ROCm options:
In the ROCm Options menu, enable or disable the installation of ROCm components. If ROCm installation is enabled, the ROCm Version and ROCm Components fields are also required.
Enter the ROCm Options menu.
Set Install ROCm to
yes
to include ROCm components in the offline installer.For the ROCm Version field, select the ROCm release version from the sub-menu.
For the ROCm Components field, select one or more ROCm components from the sub-menu.
Set the driver options:
In the Driver Options menu, enable or disable the installation of the amdgpu driver. To enable driver installation, you must also configure the amdgpu Driver ROCm version field.
Enter the Driver Options menu.
Set Install amdgpu Driver to
yes
to include the amdgpu driver in the offline installer.If the amdgpu Driver ROCm Version field is not already populated, select the ROCm release version from the sub-menu.
Configure the post-installation driver options, including Set Video,Render Group, Blacklist amdgpu driver, and Start amdgpu driver on install.
Note
Enabling the Set Video,Render Group option is recommended. However, the post-installation options aren’t required to create or use the installer.
The amdgpu Driver ROCm Version field is the same field as the ROCm Version field in the ROCm Options menu. You can set the ROCm release version from either menu.
Set the extra packages:
In the Extra Packages menu, optionally include rocminfo, rocm-smi, and rocm-validation-suite in the offline installer.
Note
Some ROCm components already include the rocminfo and rocm-smi packages, which are automatically added to the offline installer by default. If so, the user interface sets the rocminfo and rocm-smi fields to
yes
and ensures they can’t be edited.Create the installer:
After completing the previous steps, you can create the offline installer.
Enter the Create Offline Installer menu.
Review the current installer configuration by using the review summary interface, clicking <Next Page> to cycle through the pages.
If there are any errors or missing requirements in the configuration, press <RETURN> to display the main menu and make any required changes. Any errors or missing requirements are indicated in red.
If there are no errors in the configuration, select <ACCEPT> to create the offline installer, which is saved to the designated location.
At this point, the user interface closes and the offline install creation script starts running.
Note
You can only select <ACCEPT> if all configuration requirements are met and no errors are detected.
Offline Installation:
After the offline installer has been created and saved to the designated output directory on the host system, copy the installer to any matching target system and run it. The target doesn’t need to have a network or internet connection.
Copy the offline installer, for example
rocm-offline-install.run
, to a target system that matches the host.Run the installer from the terminal command line:
./rocm-offline-install.run <option>
The
option
parameter can be omitted or optionally set toprompt
,dryrun
, oruninstall
. (See the section below for more information on theuninstall
option.) Theprompt
option enables user prompts during the offline installation process. If theprompt
parameter is appended, the installer halts at critical points during the installation process, prompting the user to continue or stop the installation. Without theprompt
parameter, the offline installation runs until completion, unless a failure occurs during the process.To simulate the offline installation process, set the
option
parameter todryrun
. Withdryrun
, the installer outputs any errors it detects but does not install any packages../rocm-offline-install.run prompt
or
./rocm-offline-install.run dryrun
Note
You can run the installer with both the
dryrun
andprompt
options. This simulates the offline installation and prompts you during the process.
Offline Uninstall:
If ROCm is already installed on your system, you must first uninstall it before running the installation package. If you try to install ROCm when another version is installed on the system, the new installation will fail. If you are using the Ubuntu distribution, you can use the installation package you created to uninstall ROCm.
To uninstall ROCm, run the installer from the terminal command line with the
uninstall
parameter:./rocm-offline-install.run uninstall
After the installation is complete, reboot your system. You can then run the offline installer to install the new version.
Note
The uninstall feature is only enabled for the Ubuntu distribution.
Log files#
By default, the ROCm Offline Installer Creator records its output in log files
in the /var/log/offline_creator
directory. The output of both creation and installation
processes is logged to this directory.
Building#
Build the ROCm Offline Installer Creator from source using the files located at ROCm/rocm-install-on-linux.
To build the Offline Installer Creator:
Install the prerequisites
You must install the following packages prior to building the Offline Installer Creator from source.
sudo apt install cmake sudo apt install build-essential sudo apt install libncurses5-dev sudo apt install makeself sudo apt install wget
First, install the RHEL version-specific prerequisites:
Install the following for RHEL 8.x:
sudo dnf install wget wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm sudo rpm -ivh epel-release-latest-8.noarch.rpm sudo crb enable
Install the following for RHEL 9.x:
sudo dnf install wget wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm sudo rpm -ivh epel-release-latest-9.noarch.rpm sudo crb enable
Then install the generic RHEL x.x prerequisites
sudo dnf install cmake sudo dnf install gcc gcc-c++ sudo dnf install ncurses-devel sudo dnf install makeself
Install the following for SLES 15.5:
SUSEConnect -p PackageHub/15.5/x86_64 sudo zypper install cmake sudo zypper install gcc gcc-c++ sudo zypper install ncurses-devel sudo zypper install makeself
Install the following for SLES 15.6:
SUSEConnect -p PackageHub/15.6/x86_64 sudo zypper install cmake sudo zypper install gcc gcc-c++ sudo zypper install ncurses-devel sudo zypper install makeself
Clone the tool source
git clone https://github.com/ROCm/rocm-install-on-linux
Build the configuration
cd rocm-install-on-linux/src/offline-installer mkdir build cd build cmake ..
Build the Offline Installer Creator
The Offline Installer Creator is built for both standard and test use. The output is placed in the CMake build directory.
To build the tool, run the following command:
make
This command generates the file
rocm-offline-creator_1.0.0-local.run
.
Testing#
The Offline Installer Creator test suite includes a set of tests for validating common installer configurations. These tests simulate and validate the creation of the target offline installer and the installer’s behavior.
The tests are based on the ROCm version and on the components being installed.
Tests are available for these ROCm versions:
5.7.3
6.0.2
6.1.x
6.2.x
6.3.x
Tests are available for the following component combinations:
ROCm only: Creates an installer for the
rocm
component only.Driver only: Creates an installer for the amdgpu driver only.
ROCm and driver: Creates an installer for both the
rocm
component and the amdgpu driver.ROCm and graphics: Creates an installer for the
rocm,graphics
component.hip
andhiplibsdk
: Creates an installer for thehip,hiplibsdk
component.
Building the tests#
Tests are built using CMake and make
. See the Building section above.
Running the tests#
Run the preconfigured tests using the CMake and CTest utilities.
Note
Run any of the tests below with the -V
argument to enable verbose logging and output for the offline
installer tool creator or installer scripts.
There are two test types:
Full test
ROCm version test
For each type of test, installer creation is validated using one of the preset .config
files
located in the tests
directory.
These files contain the settings required to create the offline installer. They
run through the create-offline.sh
script for the relevant Linux distribution. This
is followed by a dry run of the resulting offline installer .run
file, which performs a simulated
installation for the distribution under test.
Full test#
From the build location of the offline tool, run the following command:
ctest
This suite runs 111 tests.
The following tests are available, depending on the ROCm version:
ROCm version |
Test Suite Support |
---|---|
5.7.3 |
ROCm only, Driver only, ROCm + Driver, ROCm + graphics, hip + hiplibsdk |
6.0.2 |
ROCm only, Driver only, ROCm + Driver, ROCm + graphics, hip + hiplibsdk |
6.1.x |
ROCm only, Driver only, ROCm + Driver, ROCm + graphics, hip + hiplibsdk |
6.2.x |
ROCm only, Driver only, ROCm + Driver, ROCm + graphics, hip + hiplibsdk |
6.3.x |
ROCm only, Driver only, ROCm + Driver, ROCm + graphics, hip + hiplibsdk |
Note
Test suites for a ROCm version only run if the version is supported on the Linux Distribution Version under test.
ROCm version test#
Select subsets of the “Full” test for a specific version of ROCm and run them using CTest.
From the build location of the offline tool, run the following command:
ctest -L <rocm-version>
where <rocm-version>
is one of 5.7.3
, 6.0.2
, 6.1.x
, 6.2.x
, or 6.3.x
.
Running manual tests#
In addition to the preconfigured CTest utilities, you can manually configure your own Offline Installer
Creator tests. This configuration option bypasses the user interface and runs
the create-offline.sh
script as described in the Running the tests section above.
To manually test the creation of an offline installer without the user interface, run the
Offline Installer Creator with the config
parameter.
Caution
For normal Offline Installer Creator usage, the user interface is recommended. The user interface validates the various configuration file inputs and guides you through the configuration process.
./rocm-offline-creator_1.0.0-local.run config=[path-to-config-file]
Set the config
parameter to the absolute path to a configuration file. The file name must include
the .config
file extension. The file follows the format defined by the Offline Installer Creator
user interface. Example configuration files, which are used for running the CTest utilities,
are available in the tests
directory of the offline-installer
repository.