1. Installation

1.1. Requirements

• Halon >= 5.11

• Linux server (LTS version of Ubuntu 20.04 and 22.04, CentOS 7, 8 and Rocky 9)

• MySQL server >= 5.7.8, MariaDB server >= 10.5

• History logging to Elasticsearch (optional but highly recommended)

1.2. Setup

Halon MSUI is provided in our package mirror for Ubuntu and RHEL (CentOS) distributions. In order to install packages from this mirror you first need to add it to the system.

1.2.1. Ubuntu

$ HALON_REPO_USER=<username>
$ HALON_REPO_PASS=<password>
$ wget -qO - https://raw.githubusercontent.com/halon/pgp-keys/master/pgp-keys/7F0A73B5.asc | sudo apt-key add -
$ . /etc/lsb-release && echo "deb [arch=amd64] https://repo.halon.io/ $DISTRIB_CODENAME stable" | sudo tee /etc/apt/sources.list.d/halon.list
$ echo "machine repo.halon.io login $HALON_REPO_USER password $HALON_REPO_PASS" | sudo tee /etc/apt/auth.conf
$ sudo apt-get update
$ sudo apt-get install halon-msui

1.2.2. RHEL

$ HALON_REPO_USER=<username>
$ HALON_REPO_PASS=<password>
$ sudo yum install epel-release
$ REPO="/etc/yum.repos.d/Halon.repo"
$ DIST="rhel$(cat /etc/redhat-release | sed 's/.*release \([0-9]\+\).*/\1/')"
$ echo "[halon]" | sudo tee $REPO
$ echo "name=Halon repository" | sudo tee -a $REPO
$ echo "baseurl=https://$HALON_REPO_USER:$HALON_REPO_PASS@repo.halon.io/dists/$DIST/amd64/stable" | sudo tee -a $REPO
$ echo "gpgcheck=1" | sudo tee -a $REPO
$ echo "gpgkey=https://raw.githubusercontent.com/halon/pgp-keys/master/pgp-keys/7F0A73B5.asc" | sudo tee -a $REPO
$ echo "enabled=1" | sudo tee -a $REPO
$ sudo yum install halon-msui

1.2.3. Initial setup

To get MSUI running after being installed, a few configuration directives need to be added in order for MSUI to know where to connect:

1. Connect to the database using the MySQL Command-Line Client.

   $ mysql -u root -p
   

2. Create a new database and give full permissions to a new (change the password) or existing user.

   CREATE DATABASE msui;
   CREATE USER 'msui'@'localhost' IDENTIFIED WITH mysql_native_password BY 'changeme';
   GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON msui.* TO 'msui'@'localhost';
   

3. Import the database schema.

   USE msui;
   SOURCE /opt/halon/msui/share/msui_database_schema.sql;
   

4. Import a pre-built setup of domain and user settings, and user roles.

   USE msui;
   SOURCE /opt/halon/msui/share/msui_default_transactions_setup.sql;
   

5. Copy the example configuration file for MSUI:

   $ cp /opt/halon/msui/share/examples/msui.yaml /etc/halon/msui.yaml
   

   Note

   The example file only include some of the available settings, please see the msui configurations for more settings.

6. Edit /etc/halon/msui.yaml and follow these steps:

   • Update the servers[].server properties.

   • Update the database connection information, database name and credentials to that you created in step 1.

   • Update the credentials for the local admin user.

   Note

   Any local users (without access levels or permissions set) stored in the configuration file is of type “superuser”, and has no restrictions in MSUI and can be used to create user roles, create new settings, change branding settings, and access the audit log and history page without any domain access filtering.

   The password for the local user needs to be encrypted using bcrypt. Run the following command to generate a encrypted password:

   $ /opt/halon/msui/bin/generatepass
   

7. Start the service by running:

   $ systemctl start halon-msui
   

8. You should now be able to access MSUI over HTTP on port 80.

9. Next configuration steps

   • Set up history logging.

   • Set up configuration export.

1.3. Upgrade

In order to upgrade the package, install the new package over the previous installed one. It is recommended to make a backup of the database before updating in case a rollback is required, when updating MSUI there will be an option to backup the database automatically (recommended):

| Run database backup script (y, N):

Important upgrades notes can be found in the changelog.

Note

The database needs to be available at the time of update, as the database schema may need to be upgraded as well to support new features.

1.3.1. Downgrade

In order to downgrade MSUI the database first needs to be rolled back to a compatible version. When performing an update there is an automatic prompt for backing up the database which will put the backed up .sql file in the /var/opt/halon-msui directory.