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

Gateway Installation Guide

ft:locale
en-US
Product name
BlueCat Gateway
Version
24.3.1

As of v24.3, Gateway supports RedHat Enterprise Linux (RHEL) 9 with Podman. Before you begin, you must download the latest BlueCat Gateway image.

Prerequisites for Gateway on RHEL:

  • You must have at least 2 CPUs and 8GB of RAM allocated to the host machine that will be running the BlueCat Gateway instance.

  • You must have RHEL 7.x installed on the host machine that will be running the BlueCat Gateway instance. For more details, see the Requirements section of the BlueCat Gateway Installation Guide.

  • You must have one of the following already set up, depending on whether you want Gateway to authenticate with BlueCat Address Manager or Micetro. (Gateway cannot authenticate with both at the same time.)

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:24.3.1
  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 Gateway workspace>:/bluecat_gateway/:Z \
    -v <Path to mapped log directory>:/logs/:Z \
    -e BAM_IP=<BAM IP address or URL> \
    --name bluecat_gateway quay.io/bluecat/bluecat_gateway:24.3.1
    Note: 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.

    If you are running on RHEL 8.x or higher: There are three additional considerations.

    • 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.

    • As with RHEL-compiled Docker, you must add :Z (a colon followed by a capital Z) at the end of the file path for any mapped volume in the podman run command.

    • 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 \
    -e BAM_IP=<BAM IP address or URL> \
    --name bluecat_gateway quay.io/bluecat/gateway:24.3.1
    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:24.3.1
      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.