Installing BlueCat Server Update Services - Adaptive Applications - BlueCat Gateway - 25.2.2

BlueCat Server Update Services Administration Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
25.2.2
Before you begin, you must download the custom BlueCat Gateway image that contains the BlueCat Server Update Services (BSUS) workflow. The custom BlueCat Gateway image can be downloaded from Quay or BlueCat Customer Care.
Attention: To download and install the offline BlueCat Server Update Services package from BlueCat Customer Care, contact your BlueCat Customer Care representative for additional information.
Prerequisites:

  • You must have an account on Quay with permission to access the BSUS installation image. If your Quay account does not have these permissions, contact your BlueCat sales representative.

  • You must have Docker installed on the host machine that will be running the BlueCat Gateway instance. For more details, see Requirements in the BlueCat Gateway Installation Guide.

  • You must have an Address Manager server configured with the BlueCatGateway UDF and a BlueCat Gateway user. For more information, see Creating the BlueCatGateway UDF.

  • You must have a Docker CLI (Command Line Interface) password.

    You can create one by clicking Generate Encrypted Password under Docker CLI Password on the Account Settings page in Quay.

Configuring ports to allow BSUS to use HTTPS communications

To allow Gateway (and BSUS) to log into Address Manager using HTTPS, you must set up the docker compose file to allow for HTTPS communications. This is useful when system rules restrict the use of port 80 in favor other ports (like port 443).

To set up BSUS to allow Gateway to log into Address Manager through an HTTPS address:

  1. Open the docker-compose.yaml file in a text editor.

  2. Within this file, locate the environment: section.

  3. Within this section, locate the entry for BAM_IP.

  4. Edit this entry to add https:// in front of ${BAM_IP}. The line will look like the following:

          BAM_IP: https://${BAM_IP}

  5. Save the yaml file and run the docker-compose command as usual.

Installing BlueCat Server Update Services from Quay

To install BSUS from Quay:
  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 installer file from BlueCat Customer Care.

    For this release, the file will be named bsus_installer-25.2.2-GA.zip.

  4. Unzip the installer file.

  5. In the same folder as docker-compose.yml, create an environment variable file named .env (with no prefix) that contains Address Manager, BlueCat Gateway, and RabbitMQ credentials.

    Tip: You can use the provided sample environment file example.env as a template.
    The following shows an example of the content of an .env environment variable file:
    BAM_IP=192.168.88.54
BSUS_IP=192.168.88.64
RABBITMQ_DEFAULT_USER=guest
RABBITMQ_DEFAULT_PASS=guest
USE_TLS=true
BSUS_ADMIN_GROUP=admin_group
ELASTIC_PASSWORD=ChangeMe
PATCH_TIMEOUT_MINUTES=15
    Where

    • BAM_IP variable is the IP address of Address Manager.

    • BSUS_IP is the IP address of the BlueCat Gateway instance that will be running BlueCat Server Update Services.

    • RABBITMQ_DEFAULT_USER is the default username of the RabbitMQ service. Do not change this from "guest".

    • RABBITMQ_DEFAULT_PASS is the default password of the RabbitMQ service. Do not change this from "guest".

    • USE_TLS specifies whether or not to use TLS encryption for communications between BSUS containers. For more details, see Configuring BSUS for TLS encryption.

    • BSUS_ADMIN_GROUP specifies the BSUS Administrator group (that is, the main Administrative group for BlueCat Server Update Services). This group will have administrator rights over all BSUS features and functionality.

      Note: The user group assigned as the BSUS Administrator group cannot have a name with a slash (/) character.
      Tip: You can set up non-admin groups for BSUS in the BSUS Access Right Settings page.
    • ELASTIC_PASSWORD is your chosen password for the BSUS database.
      Note: Until you specify ELASTIC_PASSWORD, the BSUS database will be unprotected. If no password is set on the database, BSUS will set the database password the first time it sees the ELASTIC_PASSWORD setting in the .env file.

      If the database is already password-protected, BSUS will attempt to use the password specified in ELASTIC_PASSWORD. Therefore, after adding ELASTIC_PASSWORD to the .env file, do not change it again.

      Note: In previous releases, this setting was DB_PASSWORD. When updating to the new version of BSUS, change DB_PASSWORD to ELASTIC_PASSWORD.

    • PATCH_TIMEOUT_MINUTES specifies the maximum number of minutes a patch can take when applied or scheduled. If this limit is exceeded, the apply/schedule process will be considered a failure. For example, with the default value is 15 minutes, if the upgrade.log file is no longer updated after 15 minutes, it will show a time-out event.

    If you will be using BSUS in environments where you must specify the network range to which the BSUS service containers are assigned, see Configuring a dedicated network range for BSUS.
    Tip: A standard installation includes a sample environment file named example.env. You can copy this file as a template to use for your .env file.
    Important: Do not change RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS from their current values ("guest").
  6. Run the docker container using the following command:
    docker-compose up -d

    The BlueCat Server Update Services Adaptive Application starts up. You can proceed to access the BlueCat Server Update Services Adaptive Application from the browser window once the service has started.

    To verify that the service has started, run the following command:
    docker-compose logs -f | grep "Declaring"
    The following log message indicates that the service has started:
    logstash_1 | [2021-05-17T16:06:42,205][INFO ][logstash.inputs.rabbitmq ]
[main][ab3ce81ccc3d228c9c8d56d7f16bb605c6d35ff5bca7dd75ed83e6ab37dfa86e] 
Declaring exchange 'bsus' with type topic
    Important: You must wait for the BlueCat Server Update Services Adaptive Application to start before attempting to access the UI. If you do not wait for the Declaring exchange 'bsus' with type topic message to appear and attempt to access the UI before the service has started, you will receive the following error:
    Get Batches Error: NotFoundError(404, 'index_not_found_exception', 'no such index [batch], batch, index_or_alias)

    If you receive this error, you must stop the current BlueCat Batch Update Services container, delete the container, and install a new container.

  7. (Optional, but recommended) After the upgrade finishes successfully, you can change the RabbitMQ username and password that BSUS uses. For more details, see Modifying the RabbitMQ password.