Install Gateway in custom directories

Gateway 5.5.4+

By default, the Gateway RPM package installs files into four fixed directories. You can relocate any of these directories when you install the package. For example, you can place Gateway on a dedicated volume or under a custom application root. You can relocate each directory independently.

This page covers how to install Gateway with relocated directories, and how to upgrade and uninstall a relocated installation. For a standard installation, see Install Gateway RPM/DEB package.

RPM doesn’t remember relocated directories between upgrades. If you relocate any directory, you must repeat the same --relocate flags every time you upgrade. See Upgrade a relocated installation.

Relocatable directories

You can relocate only the following directories:

Default directory	Contents
`/opt/gateway`	The `iagctl` binary
`/etc/gateway`	The `gateway.conf` file, the `certificates/` directory, `gateway.db`, and `known_hosts`
`/var/log/gateway`	Log files
`/var/lib/gateway`	Runtime data and state, including the `venv/` directory

The location of the iagctl systemd unit file is fixed. If you try to relocate any other path, the installation fails with a “not relocatable” error.

Before you begin

Relocation is available for RPM installations only. Before you install with relocated directories, make sure you meet these requirements:

Download the RPM package: Follow Step 1: Download the installation package to get the package and copy it to your server.
Use rpm to install: dnf localinstall doesn’t support the --relocate option.
Install dependencies first: rpm doesn’t resolve dependencies, so systemd and openssl must already be installed on the server.
Use dedicated target directories: Each target directory must be used only by Gateway.

On every install and upgrade, the installer recursively changes the ownership of each Gateway directory to itential:itential and sets its mode to 2770. If a target directory contains other content, that content’s ownership and permissions also change. Don’t relocate Gateway into a directory that other applications or users share.

Install with relocated directories

Run the installation with relocate flags

Run rpm -Uvh with one --relocate <default-directory>=<new-directory> flag for each directory you want to move. Any directory without a --relocate flag stays at its default location.

Update the version and arch to reflect the version you downloaded before running the example installation commands.

Relocate all four directories

This example moves all four directories under /apps:

sudo rpm -Uvh \
    --relocate /opt/gateway=/apps/opt/gateway \
    --relocate /etc/gateway=/apps/etc/gateway \
    --relocate /var/log/gateway=/apps/var/log/gateway \
    --relocate /var/lib/gateway=/apps/var/lib/gateway \
    ./iagctl-<version>-<arch>-server.rpm

Relocate some directories

This example relocates only the binary and configuration directories. The /var/log/gateway and /var/lib/gateway directories stay at their default locations.

sudo rpm -Uvh \
    --relocate /opt/gateway=/apps/opt/gateway \
    --relocate /etc/gateway=/apps/etc/gateway \
    ./iagctl-<version>-<arch>-server.rpm

Finish the installation

Follow Step 3: Configure user permissions and Step 4: Verify installation on the install page.

Relocated paths in your configuration

During installation, the installer updates the following values to point to your relocated directories:

The ExecStart line in the iagctl systemd unit
Path values in gateway.conf, including certificate and private key paths, working_dir, the log directory, and runtime_data_dir

You don’t need to edit these values manually.

Paths shown throughout the Gateway documentation, such as /etc/gateway/gateway.conf and /var/log/gateway/gateway.log, are the default locations. If you relocated a directory, use your relocated path instead. For example, if you relocated /etc/gateway to /apps/etc/gateway, your configuration file is /apps/etc/gateway/gateway.conf.

Upgrade a relocated installation

You must repeat the original --relocate flags on every upgrade. If you run rpm -Uvh without them, RPM silently reinstalls Gateway in the default directories. Gateway then ignores your relocated configuration, certificates, and data, which remain in their relocated directories. If Gateway runs in server mode, it also generates a new certificate authority (CA).

Run the upgrade with your original relocate flags

Run rpm -Uvh with the same --relocate flags you used for the original installation:

sudo rpm -Uvh \
    --relocate /opt/gateway=/apps/opt/gateway \
    --relocate /etc/gateway=/apps/etc/gateway \
    --relocate /var/log/gateway=/apps/var/log/gateway \
    --relocate /var/lib/gateway=/apps/var/lib/gateway \
    ./iagctl-<new-version>-<arch>-server.rpm

The upgrade keeps your existing gateway.conf file. The installer doesn’t update the paths in it again.

Review the relocation warning

When the package detects an existing relocated installation, it prints a warning that lists the relocated directories. The package can’t tell whether you repeated the --relocate flags, so this warning appears on every upgrade of a relocated installation.

If you supplied the same flags: You can ignore the warning.
If you omitted the flags: The upgrade installed Gateway into the default directories. Run the upgrade again with the correct --relocate flags.

Uninstall a relocated installation

Uninstall the package

Remove the Gateway package:

sudo rpm -e iagctl

This command removes the iagctl binary and the venv/ directory. The relocated binary directory (/opt/gateway by default) and runtime data directory (/var/lib/gateway by default) are removed only if they’re empty.

Back up any files you need

The uninstall doesn’t remove your relocated configuration directory, which contains your certificates and the gateway.db local store database. Back up anything you need before you delete it.

Delete the remaining directories

If you no longer need them, manually delete the following:

Any remaining content in the relocated binary and runtime data directories
The relocated configuration directory
The relocated log directory

Next steps

After you install Gateway in custom directories, complete the post-installation tasks to connect it to Gateway Manager and Itential Platform.