Beszel 0.18.7 on AWS User Guide

Overview

This guide covers launching and using the Beszel 0.18.7 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg Hardened Zabbix & Infrastructure Monitoring AMIs listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Beszel is an open source, lightweight server and container monitoring hub. A clean web dashboard shows CPU, memory, disk, disk I/O, network, load, temperatures, systemd services and Docker container usage for every server you add, keeps their history, and sends alerts by email or through webhooks to Slack, Discord, Teams, Telegram, ntfy and many more. Small Beszel agents run on the servers you monitor; the hub collects from them.

The cloudimg image adds:

• HTTPS from the first boot. nginx serves Beszel on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS.
• No first visitor admin. Out of the box, Beszel offers a "create an admin account" form to whoever opens it first. This image never shows it: first boot creates the administrator with a password unique to your instance while the hub is reachable only from the instance itself. The login is written to /root/beszel-credentials.txt; no password is baked into the image.
• Already monitoring itself. A Beszel agent on the instance is paired at first boot with your hub's own key (generated on your instance), so the dashboard shows This hub with live metrics the first time you sign in.
• Fail closed. The hub refuses to start until first boot has created the administrator, nginx refuses to start until first boot has finished, and the local agent stays off until it has your hub's key.
• Loopback only. The hub listens on 127.0.0.1:8090 and the local agent on 127.0.0.1:45876. The only open ports are 22, 80 and 443.
• Hardened defaults. The hub and the agent run as their own unprivileged users in systemd sandboxes. The hub, the agent and nginx are blocked from the instance metadata service, so a webhook URL or a system address cannot be pointed at it; the AMI requires IMDSv2. Requests for a host name the instance does not serve are dropped, cross site requests that would change your data are refused, sign in attempts are rate limited per client address, and the PocketBase superuser console is not exposed to the network.
• A dedicated data volume. The hub's database (users, systems, metrics history, alerts) and its key pair live on a separate 30 GiB EBS volume at /var/lib/beszel that you can resize on its own.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: the Beszel hub and agent 0.18.7 (the official release binaries, checksum verified), nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 22 (SSH), TCP 443 (the dashboard) and TCP 80 (redirects to HTTPS) from your own networks only. The hub needs no other inbound port: it connects out to the agents on the servers you monitor (Step 7).

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Beszel 0.18.7 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large (Beszel is light; a smaller instance is fine for a handful of servers), your key pair and a security group as above. The AMI brings two volumes: the root volume and a 30 GiB data volume for the hub's database. Keep both.

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=beszel}]'

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

First boot takes a few seconds. Then the four units are active:

systemctl is-active beszel beszel-agent nginx beszel-firstboot

active
active
active
active

The hub and the local agent listen on loopback only; nginx serves ports 80 and 443:

sudo ss -tlnp | awk 'NR==1 || /beszel|nginx|sshd/' | awk '{print $1, $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g'

State Local Peer
LISTEN 0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"))
LISTEN 0.0.0.0:80 users:(("nginx"),("nginx"),("nginx"))
LISTEN 127.0.0.1:8090 users:(("beszel"))
LISTEN 0.0.0.0:22 users:(("sshd"),("systemd"))
LISTEN 127.0.0.1:45876 users:(("beszel-agent"))
LISTEN [::]:443 users:(("nginx"),("nginx"),("nginx"))
LISTEN [::]:80 users:(("nginx"),("nginx"),("nginx"))
LISTEN [::]:22 users:(("sshd"),("systemd"))

beszel --version
beszel-agent --version
df -h /var/lib/beszel | tail -1

beszel version 0.18.7
beszel-agent 0.18.7
/dev/nvme1n1     30G  1.3M   28G   1% /var/lib/beszel

Step 4: Get your URL and password

sudo cat /root/beszel-credentials.txt

The file holds the address the hub is served as (your instance's public DNS name by default), the administrator email and the password generated on this instance, and your hub's public key, which you give to the agents on other servers (Step 7):

beszel.url=https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/
beszel.admin.user=admin@cloudimg.local
beszel.admin.pass=<24 letters and digits>
beszel.hub.public_key=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA<generated on your instance>

Step 5: Sign in from your browser

Open beszel.url in your browser. The certificate is self signed (generated on your instance), so accept the browser warning once, or install your own certificate (Step 11). Sign in with the email and password from Step 4.

The All Systems dashboard opens. This hub, the instance itself, is already listed and up, with its CPU, memory, disk, load, network, systemd service count and uptime.

Step 6: Look at a system's history

Click This hub. The system page shows its details (address, host name, uptime, operating system, CPU model, memory) and charts for CPU usage, memory, disk usage, disk I/O, network traffic, load and more. Choose the time range at the top right, from one hour to 30 days.

Step 7: Monitor your other servers

Each server you want to monitor runs the Beszel agent. The hub connects to the agent on TCP port 45876 and the agent only accepts a hub that holds the private key matching the public key it was given, so nothing else can read its metrics.

1. In the dashboard click Add System. Enter a name and the server's private IP address (or DNS name), and keep port 45876. The dialog shows your hub's public key and a one time token.
2. Choose the Binary tab (or Docker for a container) and copy the install command. Run it on the server you want to monitor; it installs the agent as a service with your hub's key.
3. On that server's security group, allow TCP 45876 inbound from the hub instance only (its security group or private IP).
4. Back in the dialog click Add System. The new system turns green within a minute.

Your hub's public key is also in /root/beszel-credentials.txt as beszel.hub.public_key, for configuration management. Agents can instead connect to the hub over HTTPS (the dialog's universal token option); for that, give the hub a DNS name and a certificate the agents trust first (Step 11).

Step 8: Alerts and notifications

Click the bell icon on any system row to set alerts: status (system down), CPU, memory, disk, bandwidth, temperature and load average, each with a threshold and duration. Under Settings, Notifications choose where alerts go: email addresses (configure an SMTP server first in the superuser console, Step 10) and webhook or push URLs for Slack, Discord, Teams, Telegram, ntfy, Gotify, Pushover and other services Beszel supports through Shoutrrr. The test button next to a URL sends a test message.

The hub cannot reach the instance metadata service, so a notification URL pointed at it fails instead of leaking the instance's credentials.

Step 9: Security checks

Port 80 sends browsers to HTTPS, the health endpoints answer without a password (for load balancer checks), Beszel's first run form is closed, and the superuser console, the superuser sign in API and the account creation endpoint are refused from the network:

H=$(sudo sed -n 's#^beszel.url=https://\([^/]*\)/#\1#p' /root/beszel-credentials.txt)
curl -s -o /dev/null -w 'port 80: %{http_code} -> %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/"
curl -sk -w '\n' --resolve "$H:443:127.0.0.1" "https://$H/api/health"
curl -sk -w '\n' --resolve "$H:443:127.0.0.1" "https://$H/api/beszel/first-run"
for p in /_/ /api/collections/_superusers/auth-with-password /api/beszel/create-user; do
  curl -sk -o /dev/null -w "$p: %{http_code}\n" --resolve "$H:443:127.0.0.1" -X POST -H "Origin: https://$H" "https://$H$p"
done

port 80: 301 -> https://ec2-<public-ip-dashed>.<region>.compute.amazonaws.com/
{"message":"API is healthy.","code":200,"data":{}}
{"firstRun":false}
/_/: 403
/api/collections/_superusers/auth-with-password: 403
/api/beszel/create-user: 403

A wrong password is refused and yours signs you in as an administrator. The password is read from the credentials file and passed to curl on stdin, so it never appears on a command line:

sleep 4
H=$(sudo sed -n 's#^beszel.url=https://\([^/]*\)/#\1#p' /root/beszel-credentials.txt)
login() { curl -sk -o /dev/null -w "$1: %{http_code}\n" --resolve "$H:443:127.0.0.1" -H "Origin: https://$H" \
  -H 'Content-Type: application/json' --data-binary @- "https://$H/api/collections/users/auth-with-password"; }
printf '{"identity":"admin@cloudimg.local","password":"wrong-password-123"}' | login 'wrong password'
sudo sed -n 's/^beszel.admin.pass=\(.*\)$/{"identity":"admin@cloudimg.local","password":"\1"}/p' /root/beszel-credentials.txt | login 'your password'
sleep 4

wrong password: 400
your password: 200

The certificate was generated on this instance and names its own addresses:

H=$(sudo sed -n 's#^beszel.url=https://\([^/]*\)/#\1#p' /root/beszel-credentials.txt)
echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, O = cloudimg
X509v3 Subject Alternative Name:
    DNS:ec2-<public-ip-dashed>.<region>.compute.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost

The hub and the agent run unprivileged in sandboxes, and neither they nor nginx can reach the instance metadata service:

systemctl show beszel -p User -p ProtectSystem -p NoNewPrivileges -p IPAddressDeny
systemctl show beszel-agent -p User -p IPAddressDeny
systemctl show nginx -p IPAddressDeny

IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32
User=beszel
ProtectSystem=strict
NoNewPrivileges=yes
IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32
User=beszel-agent
IPAddressDeny=169.254.169.254/32 fd00:ec2::254/128 168.63.129.16/32

nginx passes the hub a fixed host name and the real client address from the connection, never values a client sends (the hub's sign in rate limit uses that address), and closes the connection for any host name the instance does not serve:

grep -E 'proxy_set_header (Host|X-Forwarded-For|X-Real-IP)' /etc/nginx/sites-available/cloudimg-beszel | sort -u
curl -s -o /dev/null -w 'unknown host name: %{http_code}\n' -H 'Host: example.com' http://127.0.0.1/ || true

        proxy_set_header Host 127.0.0.1:8090;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Real-IP $remote_addr;
unknown host name: 000

(000 means nginx closed the connection without an answer.) nginx also refuses a change whose Origin is another web site (HTTP 403), including a cross site WebSocket connection.

The local agent holds your hub's public key, generated on this instance, and listens on loopback only:

sudo grep -E '^(LISTEN|KEY)=' /etc/beszel-agent/agent.env | sed -E 's/(AAAA[A-Za-z0-9+/]{4})[A-Za-z0-9+/=]+/\1.../'

LISTEN=127.0.0.1:45876
KEY="ssh-ed25519 AAAAC3Nz..."

Step 10: The PocketBase superuser console

Beszel is built on PocketBase. Its superuser console (/_/) manages users, SMTP email settings, backups and logs. The image does not serve it to the network; reach it through an SSH tunnel to the hub's loopback port. From your own computer:

ssh -i <your-key.pem> -L 8090:127.0.0.1:8090 ubuntu@<public-ip>

Then open http://localhost:8090/_/ in your browser and sign in with the same email and password (Step 4); the administrator is also the PocketBase superuser. The links in Beszel's user menu that open the console (Users, Logs, Backups, Auth providers, SMTP settings) only work through this tunnel, at http://localhost:8090/.

To let colleagues sign in, add them in the console under Collections, users (role user or readonly), then add them to the users field of each record in the systems collection they may see.

Step 11: Your own DNS name and certificate

Point a DNS record at the instance, then set the name Beszel is served as. This mints a new self signed certificate for the name, updates nginx, the hub's application URL (used in alert links and emails) and the URL in /root/beszel-credentials.txt, and keeps the name across reboots:

sudo beszel-set-hostname <your-domain>

To use a certificate from your own certificate authority instead, copy it over the generated pair and reload nginx (running beszel-set-hostname again replaces it with a self signed one):

sudo install -m 0644 <your-domain>.crt /etc/nginx/ssl/beszel.crt
sudo install -m 0600 <your-domain>.key /etc/nginx/ssl/beszel.key
sudo nginx -t && sudo systemctl reload nginx

Step 12: Password, data and upgrades

beszel-set-password sets a new password for the administrator (both the Beszel sign in and the PocketBase superuser) and records it in /root/beszel-credentials.txt. Run it without arguments for a new random password, or pass your own (24 to 64 letters and digits) on stdin:

sudo beszel-set-password
printf '%s\n' '<your-new-password>' | sudo beszel-set-password --stdin

The hub's data directory on the data volume holds the database (data.db), the logs database (auxiliary.db) and the hub's key pair (id_ed25519, which the agents trust):

sudo ls /var/lib/beszel/pb_data

auxiliary.db
auxiliary.db-shm
auxiliary.db-wal
data.db
data.db-shm
data.db-wal
id_ed25519

Back it up with EBS snapshots of the data volume, or with the backups page of the superuser console (Step 10). Keep id_ed25519 with the database: a new key means re-pairing every agent. To grow the volume, modify it in the EC2 console, then run sudo resize2fs on its device (findmnt -no SOURCE /var/lib/beszel).

The hub and the agent are single binaries in /usr/local/bin. To move to a newer release later, snapshot the instance, replace the binaries with the matching release's beszel and beszel-agent from the Beszel GitHub releases, and run sudo systemctl restart beszel beszel-agent. The image ships the version named in the listing.

Step 13: Server components

Step 14: Security recommendations

• Allow ports 22, 80 and 443 in the security group from your own networks only, and port 45876 on monitored servers from the hub only.
• Keep the administrator password secret, and rotate it if it may have been shared (Step 12).
• Use your own DNS name and a certificate your browsers trust (Step 11).
• Keep the operating system patched; unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.
• Snapshot the data volume regularly (Step 12).

Support and licensing

Beszel is open source under the MIT licence (a copy is at /usr/share/doc/beszel/LICENSE); there is no per server or per CPU licence fee. The AMI price covers cloudimg's hardening, first boot setup and support.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA