Upgrading Malcolm

At this time there is not an “official” version upgrade procedure for Malcolm, as such procedures vary from platform to platform. However, the process is fairly simple and can be done by following these steps:

Update the underlying system

Users may wish to apply official updates for the underlying system’s software packages before proceededing. Consult operating system documentation for instructions on applying system updates.

If upgrading a Malcolm instance installed from Malcolm installation ISO, follow Scenario 2 below. Due to the Malcolm base operating system’s hardened configuration, users updating the underlying system must temporarily set the umask value to Debian default (umask 0022 in the root shell in which updates are being performed) instead of the more restrictive Malcolm default. This will allow updates to be applied with the correct permissions.

Scenario 1: Malcolm is a GitHub clone

Here are the basic steps to perform an upgrade if Malcolm was checked with a git clone command:

stop Malcolm
- ./scripts/stop
stash changes to docker-compose.yml and other files
- git stash save "pre-upgrade Malcolm configuration changes"
save a backup of the environment variable files in the Malcolm ./config/ directory
pull changes from GitHub repository
- git pull --rebase
pull new Docker images (this will take a while)
- docker compose --profile malcolm pull
apply saved configuration change stashed earlier
- git stash pop
if Merge conflict messages appear, resolve the conflicts with a text editor
re-run ./scripts/configure as described in Malcolm Configuration in case there are any new configuration parameters for Malcolm that need to be set up
start Malcolm
- ./scripts/start
users may be prompted to configure authentication if there are new authentication-related files that need to be generated
- users probably do not need to re-generate self-signed certificates

Scenario 2: Malcolm was installed from a packaged tarball

If Malcolm was installed from pre-packaged installation files, here are the basic steps to perform an upgrade:

stop Malcolm
- ./scripts/stop
uncompress the new pre-packaged installation files (using malcolm_YYYYMMDD_HHNNSS_xxxxxxx.tar.gz as an example, the file and/or directory names will be different depending on the release)
- tar xf malcolm_YYYYMMDD_HHNNSS_xxxxxxx.tar.gz
backup current Malcolm scripts, configuration files and certificates
- mkdir -p ./upgrade_backup_$(date +%Y-%m-%d)
- cp -r filebeat/ htadmin/ logstash/ nginx/ config/ docker-compose*.yml ./scripts ./README.md ./upgrade_backup_$(date +%Y-%m-%d)/
replace scripts and local documentation in the existing installation with the new ones
- rm -rf ./scripts ./README.md
- cp -r ./malcolm_YYYYMMDD_HHNNSS_xxxxxxx/scripts ./malcolm_YYYYMMDD_HHNNSS_xxxxxxx/README.md ./
replace (overwrite) docker-compose*.yml file with new versions
- cp ./malcolm_YYYYMMDD_HHNNSS_xxxxxxx/docker-compose*.yml ./
re-run ./scripts/configure as described in Malcolm Configuration
- to do an in-depth comparison of the previous version’s settings with the new setings:
  - using a file comparison tool (e.g., diff, meld, Beyond Compare, etc.), compare docker-compose.yml and the docker-compose.yml files backed up in Step 3, and manually migrate over any customizations in file
  - compare the contents of each .env file Malcolm’s ./config/ directory with its corresponding .env.example file. the author uses this command which uses difftastic, bat, unbuffer, and cmp.
    for FILE in *.env; do \ cmp -s ../config/"$FILE.example" "$FILE" || \ unbuffer difft --display side-by-side-show-both \ --tab-width 4 --strip-cr \ --syntax-highlight on --ignore-comments \ ../config/"$FILE.example" "$FILE"; \ done | bat --color=always
pull the new docker images (this will take a while)
- docker compose --profile malcolm pull to pull them from GitHub or docker compose load -i malcolm_YYYYMMDD_HHNNSS_xxxxxxx_images.tar.xz if an offline tarball of the Malcolm docker images is available
start Malcolm
- ./scripts/start
users may be prompted to configure authentication if there are new authentication-related files that need to be generated
- users probably do not need to re-generate self-signed certificates

Post-upgrade

Monitoring Malcolm

Technically minded users may wish to follow the debug output provided by ./scripts/start (use ./scripts/logs to re-open the log stream after it’s been closed), although there is a lot there and it may be hard to distinguish whether or not something is okay.

Running docker compose ps -a should provide a good indication that all Malcolm’s Docker containers started up and, in some cases, may be able to indicate if the containers are “healthy” or not.

After upgrading following one of the previous outlines, give Malcolm several minutes to get started. Once things are up and running, open one of Malcolm’s web interfaces to verify that things are working.

Loading new OpenSearch Dashboards visualizations

Once the upgraded instance Malcolm has started up, users will want to import the new dashboards and visualizations for OpenSearch Dashboards. Users can signal Malcolm to load the new visualizations by opening OpenSearch Dashboards, clicking Management → Index Patterns, then selecting the arkime_sessions3-* index pattern and clicking the delete 🗑 button near the upper-right of the window. Confirm the Delete index pattern? prompt by clicking Delete. Close the OpenSearch Dashboards browser window. After a few minutes the missing index pattern will be detected and OpenSearch Dashboards will be signalled to load its new dashboards and visualizations.

Major releases

The Malcolm project uses semantic versioning when choosing version numbers. When moving between major releases (e.g., from v4.0.1 to v5.0.0), users are likely to find there are enough major backwards compatibility-breaking changes that upgrading may not be worth the time and trouble. A fresh install is strongly recommended between major releases.