Databases Azure

ClickHouse 26 LTS on Oracle Linux 9 on Azure User Guide

Last updated: 2026-04-13 | Product: ClickHouse 26 LTS on Oracle Linux 9 on Azure

Overview

This guide walks you through deploying and using the ClickHouse 26 LTS on Oracle Linux 9 image from cloudimg on Microsoft Azure. ClickHouse is a high performance open source column oriented analytical database, and the 26.3 Long Term Support release is the recommended choice for production analytics workloads.

The image ships ClickHouse 26.3 preinstalled on a fully patched Oracle Linux 9 base. The clickhouse-server systemd service is enabled and running at first boot, the server listens on all interfaces for both the HTTP and native protocols, and a cryptographically random password is generated for the built in default user on first boot.

Typical use cases include:

Real time analytics over billions of rows
Log and event store for observability pipelines
Materialized views and rollups over streaming data
Aggregation backend for business intelligence dashboards

Prerequisites

Before you begin you will need:

An active Microsoft Azure subscription
Sufficient vCPU quota in your target region (4 vCPUs minimum is recommended for ClickHouse)
An SSH key pair on your local machine
Basic familiarity with the Azure Portal or Azure CLI
Inbound network rules that allow TCP 22 (SSH), TCP 8123 (HTTP interface), and TCP 9000 (native protocol) from your client IP

Step 1: Deploy the Virtual Machine

Option A: Deploy via the Azure Portal

Sign in to the Azure Portal.
Click Create a resource and search for ClickHouse 26 LTS on Oracle Linux 9 (published by cloudimg).
Click Create on the product listing.
Complete the Basics tab:
Subscription: choose your subscription
Resource group: create a new resource group or pick an existing one
Virtual machine name: for example clickhouse-lts
Region: your preferred Azure region
Image: leave at the default (ClickHouse 26 LTS on Oracle Linux 9)
Size: Standard_D4s_v3 or larger (ClickHouse benefits from additional cores and memory)
Authentication type: SSH public key
Username: azureuser
SSH public key source: paste your public key
On the Disks tab, choose Premium SSD and size the OS disk to 128 GB or larger depending on expected data volume.
On the Networking tab, create or select a virtual network and subnet. Open the following inbound ports on the NIC security group:
22 (SSH)
8123 (ClickHouse HTTP)
9000 (ClickHouse native protocol)
Review and create the VM. Deployment typically completes in under five minutes.

Option B: Deploy via the Azure CLI

az group create --name clickhouse-rg --location eastus

az vm create \
  --resource-group clickhouse-rg \
  --name clickhouse-lts \
  --image cloudimg:clickhouse-26:clickhouse-26-oel9:latest \
  --size Standard_D4s_v3 \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_rsa.pub \
  --public-ip-sku Standard

az vm open-port --resource-group clickhouse-rg --name clickhouse-lts --port 22 --priority 1001
az vm open-port --resource-group clickhouse-rg --name clickhouse-lts --port 8123 --priority 1002
az vm open-port --resource-group clickhouse-rg --name clickhouse-lts --port 9000 --priority 1003

Step 2: Connect via SSH

Once the VM is running, retrieve its public IP and connect:

az vm show --resource-group clickhouse-rg --name clickhouse-lts --show-details --query publicIps -o tsv

ssh azureuser@<public-ip>

On first login you will see the standard Oracle Linux 9 welcome banner. All commands below assume you are connected as azureuser.

Step 3: Retrieve the Default User Password

On first boot a cloud-init hook regenerates the default user password and writes it to /stage/scripts/clickhouse-credentials.log. Read it once and store it securely:

sudo cat /stage/scripts/clickhouse-credentials.log

Example output:

===============================================================================
ClickHouse 26 LTS — Default Credentials (regenerated on first boot)
===============================================================================
First boot:       Mon Apr 13 23:10:21 UTC 2026
ClickHouse user:  default
ClickHouse pass:  aBcD1234efGh5678ijKlMnOp
Native port:      9000
HTTP port:        8123
===============================================================================

Save the password immediately. For production deployments we recommend creating a new user, granting it the required privileges, and disabling the built in default user.

Step 4: Connect with the ClickHouse Client

ClickHouse ships with a command line client that speaks the native protocol on port 9000. From the VM shell:

clickhouse-client --password

Paste the password when prompted. On success you will see the interactive prompt:

clickhouse-lts :) SELECT version();

SELECT version()

Query id: 4d2e8c1a-91f6-4d6f-8c8e-1e7f2c3d4b5a

┌─version()─┐
│ 26.3.1.1  │
└───────────┘

Useful first queries:

SELECT version();
SELECT hostName();
SHOW DATABASES;
SELECT count() FROM system.tables;

Exit with Ctrl-D or \q.

Step 5: Connect over HTTP (Port 8123)

ClickHouse also exposes an HTTP interface which is widely used by BI tools and HTTP clients:

curl -u "default:<your-password>" 'http://127.0.0.1:8123/?query=SELECT%20version()'

Expected output:

26.3.1.1

The HTTP interface supports both GET and POST, returns results in a wide range of formats (JSON, CSV, TabSeparated, and more), and is the recommended entry point for third party tools.

Step 6: Create Your First Database and Table

The snippet below creates a database, defines a MergeTree table, inserts a few rows, and runs a simple aggregation:

CREATE DATABASE demo;

CREATE TABLE demo.events (
    event_time DateTime,
    user_id UInt32,
    event_type LowCardinality(String),
    value Float64
) ENGINE = MergeTree()
ORDER BY (event_time, user_id);

INSERT INTO demo.events VALUES
    (now(), 1, 'click',    1.0),
    (now(), 2, 'purchase', 42.5),
    (now(), 1, 'click',    2.0),
    (now(), 3, 'view',     0.0);

SELECT event_type, count() AS c, sum(value) AS total
FROM demo.events
GROUP BY event_type
ORDER BY c DESC;

Step 7: Connect Remotely with a GUI or BI Tool

Popular tools that connect to ClickHouse include DBeaver, DataGrip, Metabase, Grafana, and Superset. Most use the HTTP interface on port 8123 with HTTP basic authentication.

Connection parameters:

Host: your Azure VM public IP or DNS name
Port: 8123 (HTTP) or 9000 (native)
Username: default
Password: from /stage/scripts/clickhouse-credentials.log
Database: start with default

Make sure the NSG inbound rules for ports 8123 and 9000 allow your client IP.

Server Components

The image includes:

clickhouse-server 26.3 LTS (systemd service, auto started on boot)
clickhouse-client 26.3 LTS (interactive command line)
clickhouse-common-static 26.3 LTS (shared runtime)
Configured listener on 0.0.0.0 for both HTTP and native protocols
Default user with a first boot generated password
Oracle Linux 9 base with latest security patches applied at build time

Filesystem Layout

Path	Purpose
`/etc/clickhouse-server/`	Main server configuration
`/etc/clickhouse-server/config.d/listen.xml`	Listener configuration (binds 0.0.0.0)
`/etc/clickhouse-server/users.d/default-password.xml`	Default user password hash
`/var/lib/clickhouse/`	Data, metadata, store, tmp
`/var/log/clickhouse-server/`	Server logs
`/stage/scripts/clickhouse-credentials.log`	First boot generated credentials
`/var/lib/cloud/scripts/per-instance/clickhouse-first-boot.sh`	First boot password regeneration hook

Managing the ClickHouse Server

Standard systemctl commands apply:

sudo systemctl status clickhouse-server
sudo systemctl restart clickhouse-server
sudo systemctl stop clickhouse-server
sudo systemctl start clickhouse-server

Check recent logs:

sudo tail -n 200 /var/log/clickhouse-server/clickhouse-server.log
sudo tail -n 200 /var/log/clickhouse-server/clickhouse-server.err.log
sudo journalctl -u clickhouse-server -n 200

Scripts and Log Files

Credentials: /stage/scripts/clickhouse-credentials.log (regenerated on first boot)
Main log: /var/log/clickhouse-server/clickhouse-server.log
Error log: /var/log/clickhouse-server/clickhouse-server.err.log
First boot hook: /var/lib/cloud/scripts/per-instance/clickhouse-first-boot.sh

On Startup

clickhouse-server starts automatically on boot via systemd. No manual action is required. On first customer boot only, the cloud-init hook at /var/lib/cloud/scripts/per-instance/clickhouse-first-boot.sh runs once to regenerate the default user password, write the new credentials file, and restart the server.

If you need to prevent the first boot hook from running (for example when cloning the VM), delete the file before shutdown:

# Delete the following line, save and exit:
sudo rm -f /var/lib/cloud/scripts/per-instance/clickhouse-first-boot.sh

Troubleshooting

Server will not start

sudo systemctl status clickhouse-server
sudo tail -n 200 /var/log/clickhouse-server/clickhouse-server.err.log

Common causes: a corrupt config file in /etc/clickhouse-server/config.d/, a full data disk, or a permissions error on /var/lib/clickhouse. Ownership should be clickhouse:clickhouse.

Cannot connect with clickhouse-client

Confirm the service is active, then verify the password in /stage/scripts/clickhouse-credentials.log and try:

clickhouse-client --password '<password>' --query "SELECT 1"

HTTP interface returns 516 Authentication failed

Use HTTP basic auth or the user/password query parameters:

curl 'http://127.0.0.1:8123/?user=default&password=<pwd>&query=SELECT%201'

Remote client cannot reach the server

Check NSG inbound rules allow your client IP on 8123 and 9000
Confirm firewalld on the VM allows the ports: sudo firewall-cmd --list-ports
Confirm the server is bound to 0.0.0.0: ss -lnt | grep -E ':(8123|9000)'

Security Recommendations

Rotate the default user password and restrict it to 127.0.0.1 once you have created per application users
Create dedicated ClickHouse users with the minimum required privileges and disable or scope down the default user
Enable TLS for the HTTP and native interfaces for production workloads
Restrict NSG inbound rules to trusted client IP ranges only
Keep the base OS patched: sudo dnf -y update && sudo reboot
Enable regular managed disk snapshots for the data disk holding /var/lib/clickhouse
Consider using ClickHouse Keeper or replicated tables for high availability

Support

For support, questions, or feedback please visit www.cloudimg.co.uk/support or contact us at support@cloudimg.co.uk.

Additional ClickHouse documentation is available at the official project site: clickhouse.com/docs.