Installing Hybrid DNS Update - Adaptive Applications - BlueCat Gateway - 22.1

Hybrid DNS Update Administration Guide

Locale
English (United States)
Product name
BlueCat Gateway
Version
22.1
Before you begin, you must download the latest BlueCat Gateway image that contains Hybrid DNS Update.

Before you begin:

When you first install the Hybrid DNS Update Adaptive Application, BlueCat recommends performing the following:
  • Define a workspace:
    • A workspace is the logical location for you to place your workflows and associated data, including configurations, libraries, requirements, permissions, and customizations; a workspace can be a Docker volume (recommended) or a volume on your local machine. For more information, refer to the Workspace section in the BlueCat Gateway Administration Guide.
  • Define a logs directory:
    • A logs directory can be a Docker volume (recommended) or a volume on your local machine
Tip: BlueCat advises all customers to map Docker volumes for their respective workspace and logs directory to save data from the Hybrid DNS Update Adaptive Application. Volumes are completely managed by Docker and you do not need to set permissions manually when using Docker volumes. This is also the recommended practice for Docker containers. However, if you prefer to mount data and log volumes to your local machine, you must manually set rwx (read, write, execute) permissions to those directories before running the container. If you do not map data or log volumes to your local machine during installation, the Hybrid DNS Update Adaptive Application will write all the data to the container by default. If you then stop or restart the container, all this data will be lost.
To set permissions to external volumes, run the following command:
chmod -R o=rwx <mapped volume>
Note:
  • You can name the workspace and logs directory to anything.
  • The Hybrid DNS Update Adaptive Application saves configuration and workflow data to the workspace, and all execution and session logs to the mapped logs directory. If you do not map a workspace or a logs directory, all the configuration and logging data is written to anonymous volumes by default.
To install Hybrid DNS Update:
  1. From the host machine, run the following command:
    docker login quay.io
  2. At the prompt, enter your Quay user name and password obtained when generating the encrypted password.
  3. Download the Hybrid DNS Update Adaptive Application from Quay using the following command:
    docker pull quay.io/bluecat/hybrid_dns_update:22.1
  4. Start the custom Gateway image using the following command:
    docker run -d \
    -p 80:8000 \
    -p 443:44300 \
    -v <path_to_workspace>:/bluecat_gateway/ \
    -v <path_to_mapped_log_directory>:/logs/ \
    -e BAM_IP=<your_bam_ip_address> \
    --name <gateway_container_name> \
    quay.io/bluecat/hybrid_dns_update:22.1
    Where:
    • <path_to_workspace> represents the directory where the Hybrid DNS Update configuration files will be stored.
    • <path_to_mapped_log_directory> represents the directory where the BlueCat Gateway logs are stored.
    Note: Using Hybrid DNS Update with BlueCat Overlay for Microsoft
    If you are using Hybrid DNS Update with BlueCat Overlay for Microsoft, Hybrid DNS Update includes APIs that can also make updates to Microsoft DNS and Microsoft DHCP. By default, the DHCP APIs are not available using the standard docker run command. To enable the additional network and IP addresses APIs that are available in this configuration, specify the following additional environment variable in the docker run command:
    • SERVICE=ALL
    Note: If you are using RHEL with SELinux controls enabled, you must add a :Z option to the end of the path of any mapped volume. This modifies the SELinux label of the directory that is mounted to the container and should not be used with the system directories that are used with other applications, such as the /home directory.
Hybrid DNS Update contains a configuration file within /bluecat_gateway/customizations/gss.ini that is updated by the Hybrid DNS Update installation workflow. In managed environments where the Hybrid DNS Update container is deployed automatically and must be stateless, the following configuration parameters can be passed in as environment variables in the docker run command:
  • SERVICE_USERNAME—name of the BlueCat Gateway user that will be used to provide privilege elevation.
  • SERVICE_PASSWORD—encrypted password for the BlueCat Gateway user that will be used to provide privilege elevation.

When the configuration parameters are passed in as environment variables, the corresponding values in the configuration file are ignored. To update the configuration provided in the environment variables, you must delete and redeploy the Hybrid DNS Update container.

Configuring Hybrid DNS Update with persistent storage

Starting in Hybrid DNS Update v21.3.1, you can configure visibility jobs to use a persistent volume to ensure that in the instance of a container shutdown, the visibility jobs are not lost and can be restarted once the container is restarted.

To configure the Hybrid DNS Update image with a persistent volume:
  1. Create a docker volume using the following command:
    docker volume create <volume-name>
    Note: The persistent volume can only be used when starting a new container.
  2. Run a new container with the volume created using the following command:
    docker run -d \
    -p 80:8000 \
    -p 443:44300 \
    -v <path_to_workspace>:/bluecat_gateway/ \
    -v <path_to_mapped_log_directory>:/logs/ \
    -v <volume-name>:/var/lib/postgresql/ \
    -e BAM_IP=<your_bam_ip_address> \
    --name <gateway_container_name> \
    quay.io/bluecat/hybrid_dns_update:22.1
    Where:
    • <path_to_workspace> represents the directory where the Hybrid DNS Update configuration files will be stored.
    • <path_to_mapped_log_directory> represents the directory where the BlueCat Gateway logs are stored.
    • <volume-name> represents the name of the docker volume created for persistent storage.
    Note: Using Hybrid DNS Update with BlueCat Overlay for Microsoft
    If you are using Hybrid DNS Update with BlueCat Overlay for Microsoft, Hybrid DNS Update includes APIs that can also make updates to Microsoft DNS and Microsoft DHCP. By default, the DHCP APIs are not available using the standard docker run command. To enable the additional network and IP addresses APIs that are available in this configuration, specify the following additional environment variable in the docker run command:
    • SERVICE=ALL
    Note: If you are using RHEL with SELinux controls enabled, you must add a :Z option to the end of the path of any mapped volume. This modifies the SELinux label of the directory that is mounted to the container and should not be used with the system directories that are used with other applications, such as the /home directory.
Hybrid DNS Update contains a configuration file within /bluecat_gateway/customizations/gss.ini that is updated by the Hybrid DNS Update installation workflow. In managed environments where the Hybrid DNS Update container is deployed automatically and must be stateless, the following configuration parameters can be passed in as environment variables in the docker run command:
  • SERVICE_USERNAME—name of the BlueCat Gateway user that will be used to provide privilege elevation.
  • SERVICE_PASSWORD—encrypted password for the BlueCat Gateway user that will be used to provide privilege elevation.

When the configuration parameters are passed in as environment variables, the corresponding values in the configuration file are ignored. To update the configuration provided in the environment variables, you must delete and redeploy the Hybrid DNS Update container.