> This page is for Itential Gateway, version 5 (default). > For other versions, use one of these documentation indexes: > - 5 (default): https://docs.itential.com/itential-gateway/5/llms.txt > - 4: https://docs.itential.com/itential-gateway/4/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Install Gateway in custom directories > Relocate the Gateway RPM install directories at install time, and upgrade or uninstall a relocated installation. 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](/itential-gateway/rpm-deb-install). > **Warning** > > 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](#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](/itential-gateway/rpm-deb-install#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. > **Warning** > > 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 =` flag for each directory you want to move. Any directory without a `--relocate` flag stays at its default location. > **Note** > > 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`: ```bash 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---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. ```bash sudo rpm -Uvh \ --relocate /opt/gateway=/apps/opt/gateway \ --relocate /etc/gateway=/apps/etc/gateway \ ./iagctl---server.rpm ``` #### Finish the installation Follow [Step 3: Configure user permissions](/itential-gateway/5/rpm-deb-install#step-3-configure-user-permissions) and [Step 4: Verify installation](/itential-gateway/5/rpm-deb-install#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 > **Warning** > > 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: ```bash 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---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: ```bash 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](/itential-gateway/rpm-deb-install#post-installation-tasks) to connect it to Gateway Manager and Itential Platform.