Nezha Monitoring on Ubuntu 24.04 on Azure User Guide

Overview

Nezha is an open source, lightweight tool for monitoring your servers and websites: a real time status dashboard, HTTP, TCP and Ping service checks, push notifications and alerting, scheduled tasks and a browser based web terminal. It ships as a single self contained Go binary that keeps all of its state in an embedded SQLite database, so a single node runs the full dashboard, agent gRPC channel and alerting with no external database or object store. The cloudimg image installs the pinned Nezha 2.2.10 dashboard binary and runs it as the nezha-dashboard systemd service. Since version 1, Nezha serves both the browser dashboard and the agent gRPC channel on one port, 8008. Nezha uses native username and password admin accounts, so no external OAuth provider is required. Upstream Nezha seeds a well known default admin login (admin / admin); this image never ships that - on the first boot of every VM the admin password is rotated to a unique, randomly generated value, and the per-VM agent and JWT secrets are generated freshly too, so nothing is shared between deployments. Backed by 24/7 cloudimg support.

What is included:

• Nezha 2.2.10 installed as a single Go binary and running as the nezha-dashboard systemd service
• Real time server and website monitoring with a built in web dashboard on :8008
• The browser dashboard and the agent gRPC channel multiplexed on one port, 8008
• Native username and password admin login - no external OAuth provider required
• The weak upstream default admin / admin password rotated to a unique per-VM value on first boot
• Per-VM agent secret and JWT secret generated freshly on first boot, never shared between VMs
• Embedded SQLite store - no external database to run or maintain
• The admin password stored bcrypt hashed, never in plaintext, with the credentials file 0600 root:root
• nezha-dashboard.service as a systemd unit, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point for evaluation and for monitoring dozens of servers; scale the VM up as your fleet grows. NSG inbound: allow 22/tcp from your management network and 8008/tcp for the dashboard and the agents. Port 8008 carries both the browser dashboard and the agent gRPC channel, so your monitored servers connect to the same host and port you browse to. Nezha serves plain HTTP on 8008; for production, front it with TLS on your own domain and restrict access to trusted IP ranges (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Nezha Monitoring by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22). After deployment, add an inbound rule for 8008/tcp in the Network Security Group so you and your agents can reach the dashboard. Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name nezha \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name nezha --port 8008 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the service is running

systemctl is-active nezha-dashboard.service

It reports active. Nezha serves the browser dashboard and the agent gRPC channel on port 8008, and keeps its state in the embedded SQLite database under /opt/nezha/dashboard/data.

Step 5 - Retrieve your admin login

Nezha uses native admin accounts. On the first boot of your VM the weak upstream default password is rotated to a unique value, written to a root-only file:

sudo cat /root/nezha-credentials.txt

This file contains NEZHA_USERNAME (admin), the rotated NEZHA_PASSWORD, the NEZHA_URL to open in a browser, and NEZHA_AGENT_CONNECT (the host and port your monitoring agents connect to). The per-VM agent and JWT secrets are generated on first boot and stored in the dashboard config, never shipped in the image. Store the password somewhere safe.

Step 6 - Confirm the default login is disabled

Upstream Nezha ships a well known admin / admin login. This image rotates it on first boot, so the default no longer works and only your per-VM password authenticates. The following reads the per-VM password from the credentials file and proves the round-trip against the login API - the correct password authenticates and issues a token, while both the old default and a wrong password are rejected:

PW=$(sudo grep '^NEZHA_PASSWORD=' /root/nezha-credentials.txt | cut -d= -f2-)
L(){ curl -s -m 10 -X POST http://127.0.0.1:8008/api/v1/login -H 'Content-Type: application/json' -d "{\"username\":\"admin\",\"password\":\"$1\"}"; }
echo "per-VM password : $(L "$PW"  | jq -r 'if .success==true then "authenticated (token issued)" else "rejected" end')"
echo "default admin   : $(L admin  | jq -r 'if .success==true then "authenticated" else "rejected (default disabled)" end')"
echo "wrong password  : $(L nope   | jq -r 'if .success==true then "authenticated" else "rejected" end')"

It prints per-VM password : authenticated (token issued), default admin : rejected (default disabled), and wrong password : rejected. The dashboard is only reachable with your unique per-VM credentials.

Step 7 - Sign in to the web dashboard

Browse to http://<vm-public-ip>:8008/dashboard/. Nezha shows its login page: enter the username admin and the password from Step 5, then select Log in.

Step 8 - Explore the server dashboard

After signing in you land on the admin dashboard. The Server view lists every monitored machine with its group, owner, IP, agent version and status, and the top navigation gives you Service (HTTP, TCP and Ping checks), Task, Notification, Dynamic DNS, NAT Traversal, Group and Server Transfers. A fresh VM starts with no servers - you add them in the next step.

Step 9 - Add a server to monitor

Select Installation command on the Server page and pick the target operating system (Linux, macOS or Windows). Nezha generates a one line installer that downloads the agent, registers it with this dashboard at the agent connect address, and starts reporting metrics. Run that command on each server you want to watch; it appears in the Server list within seconds and begins streaming CPU, memory, disk, network and uptime.

Step 10 - Review the settings

Open the Settings page from the profile menu. Under System settings you can set the site name, language and theme, and the tabs across the top give you User management, Online User sessions, a Web Application Firewall and API Tokens for automation. The cloudimg image ships with the site name preset and English selected.

Step 11 - Confirm the embedded SQLite store

Nezha keeps everything - the admin user, your monitored servers, service checks and history - in a single embedded SQLite database, so there is no separate database server to run:

ls -l /opt/nezha/dashboard/data/sqlite.db
sudo sqlite3 /opt/nezha/dashboard/data/sqlite.db "SELECT 'users: '||count(*) FROM users;"

The database file lives under /opt/nezha/dashboard/data, and the admin password inside it is stored bcrypt hashed, never in plaintext.

Maintenance

• Password and users: the admin password is rotated to a unique value on first boot and written to /root/nezha-credentials.txt. Change it any time from the avatar -> Profile menu in the web UI, and manage additional users under Settings -> User.
• Add servers: use Installation command on the Server page to enrol agents; they connect to this host on port 8008 using the per-VM agent secret.
• Restrict access: Nezha serves plain HTTP on port 8008. For production, restrict the port to trusted IP ranges in your Network Security Group and front the dashboard with TLS (for example a reverse proxy with your own domain) terminating on :443.
• One port: since version 1 the browser dashboard and the agent gRPC channel share port 8008 (listen_port in /opt/nezha/dashboard/data/config.yaml); your agents use the same host and port you browse to.
• Secrets: the agent secret and JWT secret are generated per-VM on first boot and kept in config.yaml; they are never shipped in the image, so no two deployments share a secret.
• Storage and backup: all Nezha state lives in the embedded SQLite database under /opt/nezha/dashboard/data; back up that directory to protect your monitoring configuration and history.
• Licensing (Apache-2.0): Nezha is licensed under the Apache License 2.0. The image ships the unmodified upstream 2.2.10 binary.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.