Installing BlueCat Gateway on RHEL with RHEL-compiled Docker or Podman - Platform - BlueCat Gateway - 25.1

Defining the workspace and log directories

When you first install BlueCat Gateway, BlueCat recommends setting up your workspace (bluecat_gateway) and logs directrories right away. You must also make sure certain permissions are available for those directories depending on where you will put your workspace (bluecat_gateway) and logs directories. These directories are used by Gateway to store data and log files.

For details, see the Setting up your workspace (bluecat_gateway) and logs directories section of the Installing BlueCat Gateway page.

Installing the Gateway docker image

Commands in the following procedure show how to set up BlueCat Gateway with BlueCat Address Manager authentication. If you want BlueCat Gateway to authenticate with Micetro instead, wherever it appears, change the BAM_IP environment option to set MICETRO_IP instead:

-e BAM_IP=<BAM IP or URL> \

to this option:

-e MICETRO_IP=<Micetro IP or URL> \

To install the BlueCat Gateway image:

1. Download BlueCat Gateway from Quay, using the following command:

   docker pull quay.io/bluecat/bluecat_gateway:25.1.0

2. If you are running the container with workspace and logs directories on the host machine: Do the following:

   chgrp -R 0 <Path to Gateway workspace>
   chmod -R g=rwx <Path to Gateway workspace>
   chgrp -R 0 <Path to mapped log directory>
   chmod -R g=rwx <Path to mapped log directory>

3. Start the Gateway image. The command you use depends on whether you are using RHEL 7 (with Docker or podman) or RHEL 8.

   If you are running on RHEL 7.x:

   Typically, you can start Gateway with the following command:

   docker run -d \
   -p 80:8000 \
   -p 443:44300 \
   -v <Path to mapped workspace directory>:/bluecat_gateway/:Z \
   -v <Path to mapped logs directory>:/logs/:Z \
   <Authentication platform environment variables> \
   --name bluecat_gateway quay.io/bluecat/bluecat_gateway:25.1.0

   Tip: Commands are identical to those used when running Gateway in a Docker container not on RHEL, except that you must add :Z to the end of file paths for mapped volumes and bind mounts.

   Where each placeholder is the following:

   • <Path to mapped workspace directory>: The path to your desired location for the Gateway folder.

   • <Path to mapped logs directory>: The path to the location where you want to store Gateway log files.

   • <Authentication platform environment variables>: Environment variable settings specific to the platform you're authenticating with (Address Manager, Micetro, or using standalone authentication). Use variables from only one authentication platform. For more details, see Authentication platform environment variables below.

   If you are running on RHEL 8.x or higher: Use the same command as for RHEL 7.x, with the following changes.

   • Docker is no longer available. Instead, RHEL comes with Podman for managing and running containers. To install and run your Gateway image using Podman, use the podman run command instead of docker run, with the same options you would for docker.

   • Podman differs from Docker in that Docker requires root privileges to work, where by default Podman can run containers without root privileges. When running without root privileges, starting a container in Podman with a port of 1024 or lower will not work by default. You must either use ports greater than 1024, or configure RHEL to allow rootless users to use ports starting at a value lower than or equal to 1024.

   If you are using RHEL 8.x (or higher) with Podman with ports greater than 1024:

   Decide what ports you want to use. Those ports cannot be used by any other software running on your system. For example, if you are using port numbers 8010 and 44310 (both higher than 1024), you can install Gateway with the same command as before with the new ports:

   podman run -d \
   -p 8010:8000 \
   -p 44310:44300 \
   -v <Path to mapped workspace directory>:/bluecat_gateway/:Z \
   -v <Path to mapped logs folder>:/logs/:Z \
   <Authentication platform environment variables> \
   --name bluecat_gateway quay.io/bluecat/gateway:25.1.0

   Important: When choosing other ports, make sure the they are not used by any other application on your system.

   If you are using RHEL 8.x (or higher) with Podman and still want to run with ports lower than 1024 (such as ports 80 and 443): If you want to use ports lower than 1024 with Podman, follow these steps:

   1. On the host machine, add the following line to the file /etc/sysctl.conf:

      net.ipv4.ip_unprivileged_port_start=80

   2. Load the settings in /etc/sysctl.conf by running the following command:

      sudo sysctl -p

   3. Set the permissions for the group by running the following command:

      chmod -R g=rwx <Path to Gateway workspace>

   4. Start the Gateway container by using the podman run command with the desired ports, such as ports 80 and 443:

      podman run -d \
      -p 80:8000 \
      -p 443:44300 \
      -v <Path to mapped workspace directory>:/bluecat_gateway/:Z \
      -v <Path to mapped logs folder>:/logs/:Z \
      -e BAM_IP=<BAM IP address or URL> \
      --name bluecat_gateway quay.io/bluecat/gateway:25.1.0

      Where:

      • <Path to mapped workspace directory>: The path to your desired location for the Gateway folder.

      • <Path to mapped logs directory>: The path to the location where you want to store Gateway log files.

      • <Authentication platform environment variables>: Environment variable settings specific to the platform you're authenticating with (Address Manager, Micetro, or using standalone authentication). Use variables from only one authentication platform. For a list of settings specific to each authorization platform, see Authentication platform environment variables below.
      Tip: Ports 80 and 443 are typically used to avoid collisions with ports used by other applications and are often (not always) the only ports allowed due to system firewall settings.

4. After starting the Gateway container, you must perform additional steps depending on what you're authenticating with.

   • If you're authenticating with BlueCat Address Manager: Go to Address Manager to create the BlueCatGateway UDF, set up BlueCat Gateway administrators, and add Gateway users. For more details, see Additional Gateway setup when authenticating with BlueCat Address Manager.

   • If you're authenticating with Micetro: Go to Micetro to set up the users and roles. For more details, see Additional Gateway setup when authenticating with Micetro.

   • If you're using standalone authentication (not connecting to either of Address Manager or Micetro), there is no additional setup. However, you might want to set up Standalone authorization functions if you want to override the default single-user authentication provided by a Standalone authentication installation. For more details, see Custom authentication functions for Standalone authentication in the Gateway Administration Guide.

Authentication platform environment variables

When starting the container, replace <Authentication platform environment variables> with the following settings based on the authentication platform:

-e BAM_IP=<BAM IP address or URL> \

docker run -d \
-p 80:8000 \
-p 443:44300 \
-v <Path to mapped workspace directory>:/bluecat_gateway/:Z \
-v <Path to mapped logs folder>:/logs/:Z \
--name bluecat_gateway quay.io/bluecat/gateway:25.1.0

-e MICETRO_IP=<Micetro IP or URL> \

-e AUTHENTICATION=STANDALONE \
-e STANDALONE_USERNAME=<Standalone account user name> \
-e STANDALONE_PASSWORD=<Standalone account password> \