Air-Gapped Installation

Follow the process below to install AxonOps within air-gapped systems.

Select the OS Family

Download Packages on Online Machine

Setup Dependencies

Prior to downloading the AxonOps packages, we must first install any missing packages on our online machine and setup the AxonOps package repository using the following steps:

#!/usr/bin/env /bin/bash

# install dependencies
sudo apt-get update
sudo apt-get install -y \
  apt-rdepends \
  dpkg-dev \
  curl \
  gnupg

# install AxonOps key
curl -L https://packages.axonops.com/apt/repo-signing-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/axonops.gpg

# setup AxonOps repository
echo "deb [arch=arm64,amd64 signed-by=/usr/share/keyrings/axonops.gpg]\
  https://packages.axonops.com/apt axonops-apt main" \
  | sudo tee /etc/apt/sources.list.d/axonops-apt.list
sudo apt-get update

#!/usr/bin/env /bin/bash

# install dependency needed for creating repomd repository
sudo dnf install -y createrepo_c

# setup AxonOps repository
cat >/etc/yum.repos.d/axonops-yum.repo <<EOF
[axonops-yum]
name=axonops-yum
baseurl=https://packages.axonops.com/yum/
enabled=1
repo_gpgcheck=0
gpgcheck=0
EOF

Download Packages

Follow the instructions below to download the necessary packages to the online machine's /tmp directory. The bundled tarball(s) can then be easily transferred to the air-gapped machine.

Since axon-dash-pdf2 relies on virtual Debian packages, we must first download these packages separately and by name:

#!/usr/bin/env /bin/bash

# create temporary location for downloading packages
mkdir -p "/tmp/downloads/axon-dash-pdf2-predependencies"
cd "/tmp/downloads/axon-dash-pdf2-predependencies"

# install predependencies for axon-dash-pdf2
services=(
  dbus-user-session
  libayatana-appindicator1
  libayatana-appindicator3-1
  libdbusmenu-glib4
  libayatana-indicator3-7
  libdbusmenu-gtk3-4
  python3
  libappindicator1
)
for service in "${services[@]}"; do
  # download axon-dash-pdf2 virtual package predependencies
  sudo apt-get download $(\
    sudo apt-rdepends "${service}" \
      | grep -v "^ " \
      | sed 's|debconf-2.0|debconf|' \
      | sed 's|libappindicator1|libayatana-appindicator3-1|' \
      | sed 's|libgcc1|libgcc-s1|' \
      | sed 's|default-dbus-session-bus|dbus-user-session|' \
      | sed 's|dbus-session-bus|dbus|' \
      | sed 's|^gsettings-backend$||' \
    )
done

# create Packages index files
dpkg-scanpackages . /dev/null | gzip -9c > Packages.gz

# create tarball with downloaded packages
mkdir -p "/tmp/bundles"
tar -czf "/tmp/bundles/axon-dash-pdf2-predependencies.deb.tgz" .

Download all additional AxonOps packages and dependencies:

#!/usr/bin/env /bin/bash

# download axonops packages and dependencies
services=(
  axon-dash-pdf2
  axon-dash
  axon-server
  axon-agent
  axon-cassandra3.0-agent
  axon-cassandra3.11-agent
  axon-cassandra4.0-agent
  axon-cassandra4.0-agent-jdk8
  axon-cassandra4.1-agent
  axon-cassandra4.1-agent-jdk8
  axon-cassandra5.0-agent-jdk11
  axon-cassandra5.0-agent-jdk17
  axon-kafka2-agent
  axon-kafka3-agent
)
for service in "${services[@]}"; do
  # create temporary location for downloading packages
  mkdir -p "/tmp/downloads/${service}"
  cd "/tmp/downloads/${service}"

  # download dependencies
  sudo apt-get download $(\
    sudo apt-rdepends "${service}" \
      | grep -v "^ " \
      | sed 's|debconf-2.0|debconf|' \
      | sed 's|libappindicator1|libayatana-appindicator3-1|' \
      | sed 's|libgcc1|libgcc-s1|' \
      | sed 's|default-dbus-session-bus|dbus-user-session|' \
      | sed 's|dbus-session-bus|dbus|' \
      | sed 's|^gsettings-backend$||' \
    )
  # create Packages index files
  dpkg-scanpackages $(pwd) /dev/null | gzip -9c > Packages.gz

  # create tarball with downloaded packages
  mkdir -p "/tmp/bundles"
  tar -czf "/tmp/bundles/${service}.deb.tgz" .
done

#!/usr/bin/env /bin/bash

services=(
  axon-dash-pdf2
  axon-dash
  axon-server
  axon-agent
  axon-cassandra3.0-agent
  axon-cassandra3.11-agent
  axon-cassandra4.0-agent
  axon-cassandra4.0-agent-jdk8
  axon-cassandra4.1-agent
  axon-cassandra4.1-agent-jdk8
  axon-cassandra5.0-agent-jdk11
  axon-cassandra5.0-agent-jdk17
  axon-kafka2-agent
  axon-kafka3-agent
)
for service in "${services[@]}"; do
  arch=x86_64
  if [[ $service == axon-cassandra* ]]; then
    arch=noarch
  fi
  # downloads all direct dependencies, including target package
  dnf5 download \
    --arch "${arch}" \
    --resolve \
    --alldeps \
    --refresh \
    --destdir=/tmp/downloads \
    "${service}"

  # downloads all dependencies, recursively
  DEPENDENCIES=$(dnf5 repoquery \
    --arch "${arch}" \
    --recursive \
    --providers-of=requires \
    --qf '%{name}-%{version}-%{release}.%{arch} ' \
    "${service}" | sort -u)
  if [[ -n $DEPENDENCIES ]]; then
    dnf5 download \
      --arch "${arch}" \
      --resolve \
      --alldeps \
      --refresh \
      --destdir=/tmp/downloads \
      $DEPENDENCIES
  fi
done

# create and compress repomd repository
cd /tmp/downloads
createrepo_c .
tar \
  -czf /tmp/axonops-x86_64.rpm.tgz \
  .

Install Packages on Air-Gapped Machine

On the air-gapped machine:

• transfer the intended tarballs produced in the previous step to a temporary directory,
• navigate into that directory,
• and run the following commands to:
  • define the helper function
  • and install the targetted software(s).

On the air-gapped machine:

• transfer the tarball(s) produced in the previous step to a temporary directory,
• navigate into that directory,
• and run the following commands to:
  • setup the offline repo,
  • define the helper function,
  • and install the targetted software(s).

Install the Server and Dashboard

Use the following script to install axon-server and axon-dash on the offline machine. axon-server and axon-dash can be installed on the same machine or be configured to communicate across two machines.

The axon-dash-pdf2 package is optional and provides support for generating PDF reports.

#!/usr/bin/env /bin/bash

# define installation helper function
function install_dependency() {
  service=${1}

  mkdir -p "/opt/offline/axonops/${service}"
  tar xf "${service}.deb.tgz" --directory "/opt/offline/axonops/${service}"
  if [[ "$service" == "axon-dash-pdf2-predependencies" ]]; then
    sudo dpkg -i /opt/offline/axonops/${service}/libpython3*-minimal*
    sudo dpkg -i /opt/offline/axonops/${service}/python3*-minimal*
    sudo dpkg -i /opt/offline/axonops/${service}/*.deb || (
      echo "Working through Python dependencies..."
      sudo dpkg -i /opt/offline/axonops/${service}/*.deb
    )
  else
    sudo dpkg -i /opt/offline/axonops/${service}/*.deb
  fi
}

# (optional) install axon-dash dependency to enable pdf generation
install_dependency axon-dash-pdf2-predependencies
install_dependency axon-dash-pdf2

# install axon-dash
install_dependency axon-dash

# install axon-server
install_dependency axon-server

#!/usr/bin/env /bin/bash

# extract packages into the offline repository location
sudo mkdir -p /opt/offline/axonops
sudo tar -C /opt/offline/axonops \
  -xzf ./axonops-x86_64.rpm.tgz \
  --strip-components=1

# setup the offline repository
sudo tee /etc/yum.repos.d/axonops-offline.repo \
  >/dev/null <<'EOF'
[axonops-offline]
name=AxonOps Offline
baseurl=file:///opt/offline/axonops
enabled=1
gpgcheck=0
EOF

# define installation helper function
function install_dependency() {
  service=${1}

  sudo dnf5 \
    --disablerepo='*' \
    --enablerepo="axonops-offline" \
    install \
    -y \
    --nogpgcheck \
    "${service}"
}

# (optional) install axon-dash dependency to enable pdf generation
install_dependency axon-dash-pdf2
install_dependency axon-dash

# install axon-server
install_dependency axon-server

Install the Agent

Use the following script to install the axon-agent as well as a version of axon-cassandra*-agent or axon-kafka*-agent that coincides with the version of Cassandra/Kafka and the Java JDK that is being used.

#!/usr/bin/env /bin/bash

# define installation helper function
function install_dependency() {
  service=${1}

  mkdir -p "/opt/offline/axonops/${service}"
  tar xf "${service}.deb.tgz" --directory "/opt/offline/axonops/${service}"
  if [[ "$service" == "axon-dash-pdf2-predependencies" ]]; then
    sudo dpkg -i /opt/offline/axonops/${service}/libpython3*-minimal*
    sudo dpkg -i /opt/offline/axonops/${service}/python3*-minimal*
    sudo dpkg -i /opt/offline/axonops/${service}/*.deb || (
      echo "Working through Python dependencies..."
      sudo dpkg -i /opt/offline/axonops/${service}/*.deb
    )
  else
    sudo dpkg -i /opt/offline/axonops/${service}/*.deb
  fi
}

# install axon-agent on Cassandra/Kafka nodes
install_dependency axon-agent

## (choose one of the following)
## install matching axon-cassandra/axon-kafka agent on the Cassandra/Kafka nodes
# install_dependency axon-cassandra3.0-agent
# install_dependency axon-cassandra3.11-agent
# install_dependency axon-cassandra4.0-agent
# install_dependency axon-cassandra4.0-agent-jdk8
# install_dependency axon-cassandra4.1-agent
# install_dependency axon-cassandra4.1-agent-jdk8
# install_dependency axon-cassandra5.0-agent-jdk11
# install_dependency axon-cassandra5.0-agent-jdk17
# install_dependency axon-kafka2-agent
# install_dependency axon-kafka3-agent

#!/usr/bin/env /bin/bash

# extract packages into the offline repository location
sudo mkdir -p /opt/offline/axonops
sudo tar -C /opt/offline/axonops \
  -xzf ./axonops-x86_64.rpm.tgz \
  --strip-components=1

# setup the offline repository
sudo tee /etc/yum.repos.d/axonops-offline.repo \
  >/dev/null <<'EOF'
[axonops-offline]
name=AxonOps Offline
baseurl=file:///opt/offline/axonops
enabled=1
gpgcheck=0
EOF

# define installation helper function
function install_dependency() {
  service=${1}

  sudo dnf5 \
    --disablerepo='*' \
    --enablerepo="axonops-offline" \
    install \
    -y \
    --nogpgcheck \
    "${service}"
}

# install axon-agent on Cassandra/Kafka nodes
install_dependency axon-agent

## (choose one of the following)
## install matching axon-cassandra/axon-kafka agent on the Cassandra/Kafka nodes
# install_dependency axon-cassandra3.0-agent
# install_dependency axon-cassandra3.11-agent
# install_dependency axon-cassandra4.0-agent
# install_dependency axon-cassandra4.0-agent-jdk8
# install_dependency axon-cassandra4.1-agent
# install_dependency axon-cassandra4.1-agent-jdk8
# install_dependency axon-cassandra5.0-agent-jdk11
# install_dependency axon-cassandra5.0-agent-jdk17
# install_dependency axon-kafka2-agent
# install_dependency axon-kafka3-agent

Configure Software

Configure Server and Dashboard

Once installed, ensure the axon-server and axon-dash are configured correctly by:

• ensuring the target software is not running,
• configuring the relevant configuration file,
• and restarting the target service.

# configure axon-server
systemctl stop axon-server
vi /etc/axonops/axon-server.yml
systemctl restart axon-server

# configure axon-dash
systemctl stop axon-dash
vi /etc/axonops/axon-dash.yml
systemctl restart axon-dash

Configure and Load Agents

On the Cassandra/Kafka machine, run the following commands to configure axon-agent and ensure Cassandra/Kafka loads the agent. Use the instructions found on the AxonOps Agent Installation page to:

• configure axon-agent,
• configure Cassandra/Kafka to load the agent,
• configure the Cassandra/Kafka user groups,
• and restart the Cassandra/Kafka process.

# ensure the axon-agent is not running
systemctl stop axon-agent

# configure the agent
vi /etc/axonops/axon-agent.yml

## FOR CASSANDRA

# configure Cassandra to load the agent
vi /etc/cassandra/cassandra-env.sh

# configure Cassandra user groups
sudo usermod -aG "$CASSANDRA_GROUP" axonops
sudo usermod -aG axonops "$CASSANDRA_USER"

# restart Cassandra to load the agent
systemctl restart cassandra

## FOR KAFKA

# configure Kafka to load the agent
vi "$KAFKA_HOME/bin/kafka-server-start.sh"

# configure Kafka user groups
sudo usermod -aG "$KAFKA_GROUP" axonops
sudo usermod -aG axonops "$KAFKA_USER"

# restart Kafka to load the agent
"$KAFKA_HOME/bin/kafka-server-stop.sh"
"$KAFKA_HOME/bin/kafka-server-start.sh"

## FOR BOTH

# restart the agent
systemctl restart axon-agent

Upgrading

When upgrading your air-gapped AxonOps installation, simply follow the above instructions to:

• download the target packages and dependencies on an online machine,
• extract the tarball(s) on the offline machine,
• and run the select install_dependency commands.

Feel free to adjust the extracted path to maintain proper versioning accordingly.

After the new versions have been installed, run the following commands to load the new configuration file changes and restart the select service(s):

sudo systemctl daemon-reload
sudo systemctl restart $service