BlueCat periodically releases patches and updates for the BlueCat Server Update Services (BSUS) application itself. If you're using an existing BSUS system, you must download and apply the updated custom BlueCat Gateway image that contains the BlueCat Server Update Services workflow. The custom BlueCat Gateway image can be downloaded from Quay.
During the upgrade process, you'll download the patch, back up your Planned Updates list, then restore those scheduled updates after BSUS is upgraded. The download package includes a script to use to properly back up and download your scheduled updates.
Before you begin the BSUS upgrade
Make sure that there are no DNS/DHCP Server updates currently in progress. Any DNS/DHCP Server updates should be either completed before updating BSUS, or scheduled to take place well after the expected time for the BSUS update to complete.
Applying a BlueCat Server Update Services application update
To acquire and upgrade your BlueCat Server Update Services system:
From the host machine, navigate to the dist directory containing the docker-compose.yml file for the current running version.
Download the bsus_installer-23.1-GA.zip installer file from BlueCat Customer Care.
Unzip the installer file.
Among other files, the zip file contains several files you will need to use during the upgrade:backup_jobs.sh
: Used to back up the list of scheduled updates from your Scheduled Updates page (changed to Planned Updates as of v23.1).After updating BSUS, you will restore the list of updates with the
/job_restoration
REST API endpoint.docker-compose.yml
: Used to configure docker so that it can properly install the docker container that holds BSUS.example.env
: A template environment file. You will use this as a template for the.env
file (no prefix) that contains credentials for the BlueCat software that BSUS integrates with.update_volume.py
: Assists with docker volume mapping between versions.
Within the set of downloaded files, go to the
dist
subfolder and grant executable permission to thebackup_jobs.sh
script.To do so, run the following command from thedist
subfolder:chmod +x ./backup_jobs.sh
Set up docker volume mapping in the
update_volume.py
script as follows:- Make sure that the current version of BSUS is still running. Then, go to
the
dist
subfolder and grant executable permission to theupdate_volume.py
script. To do so, run the following command from thedist
subfolder:chmod +x ./update_volume.py
- Install the
pyyaml
package as follows:pip install pyyaml
- Run the update script as follows:
python3 ./update_volume.py
- Make sure that the current version of BSUS is still running. Then, go to
the
Back up your list of scheduled updates using the
backup_jobs.sh
script (also located within the extracted files).To do so, run thebackup_jobs.sh
script from thedist
subfolder as follows:./backup_jobs.sh
Turn off the Docker container using the following command:
docker-compose down
You can verify that the BlueCat Server Update Services container is turned off by running the
docker ps
command. The BlueCat Server Update Services container names do not appear in the list if the Docker containers were successfully shut down.In the same folder as the extracted file
docker-compose.yml
, create an environment variable file named.env
(with no prefix) that contains Address Manager, BlueCat Gateway, and RabbitMQ credentials.Tip: Use the provided sample environment fileexample.env
as a template.Important: Do not changeRABBITMQ_DEFAULT_USER
andRABBITMQ_DEFAULT_PASS
from their current values ("guest
").For example:WhereBAM_IP=192.168.88.54 BSUS_IP=192.168.88.64 RABBITMQ_DEFAULT_USER=guest RABBITMQ_DEFAULT_PASS=guest USE_TLS=true PATCH_TIMEOUT_MINUTES=15 BSUS_ADMIN_GROUP=admin_group ELASTIC_PASSWORD=ChangeMe
-
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. 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 theupgrade.log
file is no longer updated after 15 minutes, it will show a time-out event.-
BSUS_ADMIN_GROUP
specifies which Address Manager group to use as the BSUS Administrator user group. This group will have access rights to use all features and functionality in BlueCat Server Update Services, and rights to add, modify, or delete all BSUS Server Batches.Note: This setting is new as of BSUS v23.1. If you're upgrading from a version before v23.1, you must decide which Address Manager user group to use as the BSUS Administrator group. For more details on BSUS Access Right Settings, see Managing BSUS Access Rights.Tip: You can set up non-admin groups for BSUS in the BSUS Access Right Settings page. -
ELASTIC_PASSWORD
is the password for the BSUS search database.Note: Until you specifyELASTIC_PASSWORD
, the search database will be unprotected. If no password is set on the database, BSUS will set the database password the first time it sees theELASTIC_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 addingELASTIC_PASSWORD
to the.env
file, do not change it again.Note: In previous releases, this setting wasDB_PASSWORD
. When updating to the new version of BSUS, changeDB_PASSWORD
toELASTIC_PASSWORD
.
Note: If you are installing BlueCat Server Update Services for environments where you must specify the network range to which the BlueCat Server Update Services service containers are assigned. For more details, see Configuring a dedicated network range for BSUS.-
List the BlueCat Server Update Services Docker volume names using the following command:
docker volume ls
By default, BlueCat Server Update Services creates the following five docker volumes:- dist_portal_logs
- dist_portal_medias
- dist_elasticsearch_data
- dist_rabbitmq_logs
- dist_certs
Edit
volumes
section of thedocker-compose.yml
file to include theexternal
andname
properties of the volumes.The following example illustrates thevolumes
section of thedocker-compose.yml
file:# Copyright 2020 BlueCat Networks. All rights reserved. version: '3.8' volumes: rabbitmq_logs: external: true name: dist_rabbitmq_logs elasticsearch_data: external: true name: dist_elasticsearch_data portal_logs: external: true name: dist_portal_logs portal_medias: external: true name: dist_portal_medias
Tip: You do not need to add dist_certs to the file. It will automatically regenerate each time the containers are started.Save the changes to the
docker-compose.yml
file and exit.Run the updated BlueCat Server Update Services 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 theDeclaring 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.
After starting the docker container, call the
POST /job_restoration
REST API endpoint to restore the list of scheduled updates that you backed up:http://<Gateway_hostname_or_IP>/bsus/api/v1/job_restoration
Tip: You can also run this endpoint directly from the BSUS Swagger documentation, the in-product interactive documentation for BSUS's REST API. To access the Swagger documentation, go to:http://<Gateway_hostname_or_IP>/bsus/api/v1/doc