Install UTMStack

This guide installs UTMStack v12 on a Linux server with the installer program, then walks you through the first sign-in and the first settings. Read System Requirements and Network Ports and Firewall before you start.

Before you begin

Go through Prepare the Server and make sure every pre-flight check at the end of that page passes. In short:

• The server runs Ubuntu, Debian or Red Hat Enterprise Linux, and nothing else runs on it.

• It has at least 2 CPU cores, 13,360 MB of memory and 30 GB free on /. For production, size it as described in Sizing and Capacity Planning.

• /utmstack is on its own disk, if you planned one, and is mounted.

• The server has a fixed IP address, a host name and, ideally, a DNS name.

• Its clock is synchronised.

• You can work as the root user, for example with sudo.

• The server can reach the internet, including github.com, ghcr.io, Docker Hub, download.docker.com, your distribution's package mirrors and cm.utmstack.com. For a server without internet access, see Air-gapped installation below.

• You can reach the server over IPv4. The installer turns IPv6 off.

On a cloud virtual machine, also see Install on AWS, Azure or Google Cloud.

Step 1: Download the installer

# Update the package list and install wget
sudo apt update
sudo apt install wget

# Download the installer of the latest UTMStack release
wget https://github.com/utmstack/UTMStack/releases/latest/download/installer

# Switch to the root user
sudo su

# Make the installer executable
chmod +x installer

# Install wget
sudo dnf install wget

# Download the installer of the latest UTMStack release
wget https://github.com/utmstack/UTMStack/releases/latest/download/installer

# Switch to the root user
sudo su

# Make the installer executable
chmod +x installer

The latest link always downloads the installer of the newest release that GitHub marks as Latest. To install a specific version, put its tag in the link, for example:

wget https://github.com/utmstack/UTMStack/releases/download/v12.0.2/installer

Step 2: Run the installer

Run the installer without arguments:

./installer

Running it without arguments is the same as ./installer --install. Do not interrupt it. It takes a while, mostly to download the container images, and it waits for the UTMStack services to start. Run it in a terminal multiplexer such as tmux or screen, so that a dropped SSH connection does not stop it: the network change in step 5 can interrupt SSH for a moment.

The installer prints each step as it goes:

1. Generating the stack configuration. This is also where it checks memory: below 13,360 MB it stops with insufficient memory: Available ...MB < Total Minimum Required 12360MB. (System requires 13360MB).

2. Checking the system requirements.

3. Generating certificates.

4. Preparing the system and the kernel.

5. Configuring the VLAN interface.

6. Configuring Docker and initialising Docker Swarm.

7. Downloading the images and deploying the services.

8. Installing the reverse proxy (nginx).

9. Installing the administration tools (Cockpit).

10. Initialising the UTMStack and AgentManager databases.

11. Waiting for the backend to be ready.

12. Generating the Base URL.

13. Installing the update service.

14. Running the post-installation clean-up, which deletes unused Docker images.

When it finishes, the installer prints:

• the location of the configuration file, /root/utmstack.yml;

• the web interface address, https://<your-server-ip>, with the user name admin and the generated password;

• the Cockpit address, https://<your-server-ip>:9090, where you sign in with your Linux user;

• the location of the detailed log, /var/log/utmstack-installer.log.

Step 3: Check the installation

Run these commands on the server as root:

# All 10 services of the utmstack stack should show 1/1 replicas
docker service ls --filter name=utmstack_

# The health check answers {"status":"ok"}
curl -k https://localhost/api/ping; echo

# The update service should be active (running)
systemctl status UTMStackComponentsUpdater

# Installed version and edition
/usr/local/bin/utmstack_installer --version

On Red Hat Enterprise Linux, also make sure nginx starts again after a server restart. The installer starts nginx but may not enable it at boot:

systemctl is-enabled nginx || systemctl enable nginx

If something is not as expected, see Health Checks and Troubleshooting.

Step 4: Sign in for the first time

Do this soon after the installer finishes.

1. In your browser, open the address your users will use, preferably the server's DNS name, for example https://siem.example.com. Requests to http:// are redirected to HTTPS.

   On a multi-tenant licence this matters: the first address used to open UTMStack becomes the domain of the default tenant, the operator's own tenant. See Tenants.

2. The server uses a self-signed certificate until you install your own, so the browser shows a security warning. Continue to the site. To remove the warning, see SSL Certificate.

3. On the sign-in page, type admin in Email and the generated password in Password, then select Sign in.

4. The Set your admin email window opens. It cannot be closed: the administrator account still uses the default name, and a real address is needed for password recovery, notifications and alert emails. Type your address in Email address and select Save and continue.

5. UTMStack opens Email configuration.

Step 5: After-installation checklist

Work through this list before you connect production data sources.

1. 1

   Keep the configuration file safe

   Copy /root/utmstack.yml to a safe place, such as your password manager or an encrypted backup. It holds the database password and the internal key that encrypts secrets in the database. Do not change or delete it. See Backups and Recovery.

2. 2

   Configure the mail server

   In Configure > Settings > Email Configuration, fill in the SMTP server, the mail server UTMStack sends email through (Host, Port, Encryption: TLS, SSL or None, Username, Password) and the sender (From address, Organization name). Select Send test to check it, then Save changes. UTMStack needs mail for alert and incident emails, emailed sign-in codes and password emails. See Email Configuration.

3. 3

   Correct the Base URL

   On the same page, set Base URL to the address your users open, for example https://siem.example.com. Links in emails use this address. The installer fills in https://<host name>.utmstack.com, which is right only for servers that UTMStack hosts.

4. 4

   Change the administrator password

   Open the avatar menu, select Profile and change the password in Password. The generated password stays in /root/utmstack.yml as the database password; changing the administrator password does not affect the databases.

5. 5

   Add a second administrator

   In Configure > Team, add a second user with the Administrator role, so that you are not locked out if one password is lost. See Users.

6. 6

   Install your licence

   If you have an Enterprise licence, open Configure > Settings > License and upload it. Servers with internet access also receive their licence from UTMStack automatically. See License and Editions.

7. 7

   Install a trusted certificate

   Replace the self-signed certificate with one for your DNS name, and for every tenant domain on a multi-tenant licence. See SSL Certificate.

8. 8

   Lock down the network

   Allow 443 only from the networks that need it, keep 22 and 9090 for administrators, and block 10001 from outside the server. Test it from another machine. See Network Ports and Firewall.

9. 9

   Set the time zone and date format

   In Configure > Settings > Date Format, choose the time zone in which the console shows dates. Data is always stored in UTC. See Date, Time Zone and Language.

10. 10

    Review data retention

    In Configure > Settings > Data Retention, check how long logs and alerts are kept (730 days by default) against your disk size, and set up cold storage if you need it. See Data Retention and Cold Storage and Sizing and Capacity Planning.

11. 11

    Set up backups

    Schedule a configuration backup and, if you can, disk snapshots. See Backups and Recovery.

12. 12

    Connect a first data source and check it

    Open Configure > Integrations, install one agent or connect one source, then search for its logs in Log Explorer. See How Data Reaches UTMStack.

Air-gapped installation

If the server cannot reach 8.8.8.8, 1.1.1.1 and google.com over HTTPS, the installer assumes it has no internet access and switches to air-gapped mode. It prints AirGap mode detected - some features will be limited.

In air-gapped mode:

• Docker must already be installed and running, and nginx and systemctl must be available. The installer checks this and lists anything missing.

• The container images must be in /utmstack/images as .tar files. The installer loads every .tar file in that folder with docker load instead of downloading images.

• The installer does not install Docker, nginx, the VLAN package or Cockpit.

• The server does not register with the UTMStack update server.

The image files are not published with the UTMStack releases. Contact UTMStack before you plan an air-gapped installation, to get the image files and to agree how the server will be licensed and updated.

Troubleshooting

nproc
free -m
df -h /
cat /etc/os-release

docker service ls
docker service logs --tail 200 utmstack_backend