Linux server tuning for ClickHouse

Linux server tuning for ClickHouse: what your platform team must set before go-live

Linux server tuning for ClickHouse covers the CPU governor, transparent huge pages, memory overcommit, swap, the kernel version and, on OpenStack or libvirt virtual machines, hypervisor CPU passthrough. Your platform team needs this work when it builds new ClickHouse hosts, moves an existing cluster onto virtual machines, or chases a performance or stability incident that traces back to the operating system rather than the database. Each setting changes how memory, CPU scheduling and disk I/O behave under analytical load, so a default image that is fine for a web tier can produce uneven query latency here.

The exact values depend on the ClickHouse version, the Linux distribution and the hardware underneath it. Confirm each setting against the official ClickHouse documentation for the version you plan to run, and check that the kernel and distribution combination is one the vendor supports. Then test the settings on representative data and representative queries in a pre-production cluster before you change anything in production. Record the values you chose and the reason for each, so a later upgrade or image rebuild does not silently revert them.

Treat the operating system as part of the database's configuration, not as a one-time preparation step. Ask your infrastructure team who owns each setting, how a new host gets the same values, and how drift is detected after provisioning. Your sizing and storage choices feed into this work, so review them together. The sections that follow cover each setting in turn, the virtual machine specifics and how to verify the result.

Which operating system settings ClickHouse expects, and when each one fits

This table compares the operating system settings that affect ClickHouse, what each one controls, and how the default or a change plays out on bare metal, KVM guests, OpenStack instances and libvirt domains. Read each row as a checklist item: confirm the current ClickHouse guidance and your own host configuration before you change anything.

Setting	What it controls and why ClickHouse cares	When the default or a change matters	What to confirm before you change it
CPU frequency governor	Sets how aggressively the kernel scales core clock speed. Query latency and merge throughput both depend on how quickly cores reach full speed under bursty analytical load.	Bare metal hosts usually expose the governor directly. In KVM guests and OpenStack instances the host controls frequency, so the guest governor has little effect.	The governor value your distribution ships, whether the hypervisor manages frequency, and the ClickHouse production guidance on hardware and host settings.
Transparent huge pages	Controls whether the kernel automatically backs memory with large pages. Large, long-lived allocations and memory fragmentation can interact with this setting under ClickHouse's memory usage pattern.	Matters most on dedicated database hosts with large resident memory. Shared hypervisor hosts and small guests may show little difference.	The ClickHouse documentation's current recommendation for this mode, and a load test on a host that matches production memory size.
Memory overcommit	Determines whether the kernel allows allocations beyond physical memory plus swap. Overcommit decisions affect whether a heavy query or merge is refused or whether the out-of-memory killer ends the process.	Relevant on any host running large merges or many concurrent queries. Guests with ballooning or memory limits in OpenStack or libvirt can behave differently from bare metal.	Your intended memory limits in ClickHouse settings, the current kernel default on each distribution, and how the hypervisor reports and reclaims guest memory.
Swap	Decides whether the kernel can move idle pages to disk. Swapping active ClickHouse memory can add latency that is hard to diagnose during query spikes.	Changes the failure mode more than the steady state. Teams often keep a small swap partition for crash dumps and consider how it interacts with memory limits.	Whether your environment or a container runtime allows swap at all, and the swap guidance in the ClickHouse production documentation.
Kernel version and distribution	Defines the filesystem, I/O scheduler, networking and cgroup behavior that ClickHouse relies on. Supported operating systems and kernel features determine what you can tune.	Changes with every OS upgrade. Older enterprise kernels and minimal guest images can lack features or defaults assumed in current documentation.	The ClickHouse release notes for your target version, the supported platforms listed in the ClickHouse repository, and your distribution's kernel support window.
Hypervisor CPU passthrough or CPU model exposure	Controls which instruction set extensions the guest sees. ClickHouse uses vectorized code paths that depend on CPU features, and a generic CPU model can hide them from the guest.	Matters on KVM guests, libvirt domains and OpenStack instances. A generic or masked CPU model can lower performance or change which code paths run, and live migration across hosts with different CPUs needs a common model.	The CPU flags the guest reports, the OpenStack or libvirt CPU mode for each compute pool, and whether your migration plan requires a common baseline model.
Virtual versus bare metal placement	Determines who controls CPU scheduling, memory reclaim and storage caching between ClickHouse and the physical hardware.	Noisy neighbors and overcommitted hosts affect replicas unevenly. Replicas placed on the same hypervisor share one failure domain.	Whether the hypervisor overcommits CPU or memory, and whether replicas and Keeper nodes run on separate physical hosts.

How virtual machine CPU passthrough changes ClickHouse tuning

On a bare metal server there is no hypervisor between ClickHouse and the processor, so the instruction sets the kernel reports are the ones the database uses. The operating system, the installed microcode and the BIOS or UEFI settings decide what is visible. Your team controls all three directly, which makes this environment the simplest to verify, but it also means that any BIOS change, microcode update or kernel upgrade can alter the feature set after go-live.

Host controls everything: the CPU model, microcode package and firmware settings are the only layer, so there is no passthrough choice to get wrong.
Feature flags come from the kernel: check /proc/cpuinfo and lscpu after each kernel or microcode change, since these are the values ClickHouse reads at startup.
Mixed hardware breaks uniformity: replicas bought in different batches can expose different vector extensions, which matters if you rely on the same binary behavior across a shard.
Power and frequency settings interact with tuning: the CPU governor and frequency scaling are set in the operating system, so they belong in the same change record as firmware updates.
Record the baseline: store the flag list per host in your configuration management so drift is visible.

Before sign-off, confirm the flags on every production host match the baseline recorded in your build pipeline.

With libvirt or KVM, the domain XML defines the CPU the guest is allowed to see. A host-passthrough mode exposes the host processor closely, while a named model or custom model hides features the named model does not include. Your virtualization team controls the domain definition and the host, while you control the guest kernel and ClickHouse configuration. The guest sees only what the domain definition allows, so a host capability can be present on the hypervisor and still be absent inside the VM.

Passthrough mode: host-passthrough shows most host features but ties the guest to that hardware, which complicates live migration between hosts with different processors.
Named models: a named CPU model trades some features for migration portability, and features outside the model are hidden even when the host supports them.
Check inside the guest: run lscpu and inspect /proc/cpuinfo in the VM, not only the domain XML or the host.
Migration constraints: ask whether the cluster uses live migration, because a feature that is visible on one host may disappear after a move.
Guest kernel version: the guest kernel must recognize the exposed features, so confirm the guest distribution and kernel before tuning.

Ask the virtualization team to confirm the CPU mode and migration policy for each ClickHouse VM, then verify the flags from inside each guest.

In OpenStack, the CPU view a ClickHouse instance receives is shaped by the compute service configuration, the flavor and the image metadata, on top of the host processor. Several of these layers can set or override the CPU model, so the effective result is not obvious from any single setting. Your cloud team controls the compute configuration and the flavor catalog, and you control the image and the guest tuning. Confirm the effective guest view on a running instance rather than relying on the flavor name or the compute configuration file.

Compute configuration sets the default: the cloud team decides the CPU mode for the hypervisor driver and whether host passthrough is allowed at all.
Flavors and image properties can narrow or change it: extra specs and image metadata can request a specific CPU model, so check both before you accept a flavor for ClickHouse.
Scheduling depends on the model: if an instance requests a CPU model, only compute hosts that support it are eligible, which can limit placement during a capacity event.
Hosts differ across availability zones: ask whether all hosts offering the ClickHouse flavor expose the same features.
Verify on the instance: run lscpu and check the flag list inside the guest after boot and after any resize or migration.

Before production use, ask the cloud team to confirm the CPU mode, the flavor and image properties, the placement constraints, and the behavior after resize or evacuation.

How to apply and verify Linux tuning on ClickHouse servers

This sequence takes a ClickHouse server from version selection to documented, verified kernel settings, so each node runs the same tuned configuration and the team can roll back if a change causes trouble.

Confirm the ClickHouse version and release line
The platform team checks which ClickHouse release line the cluster will run against the project's security policy and production FAQ. The policy lists which versions still receive security updates, and the FAQ explains how stable and LTS releases are supported. Done means the target version is written into the change record with its support status, and the tuning plan is tied to that version. Confirm the current status with the security policy on the day of the change, since support windows move.
Check kernel and distribution compatibility
The operations team compares the operating system, distribution release and kernel on each host with the requirements in the ClickHouse documentation for the chosen version. They also confirm the hypervisor or cloud platform, and for OpenStack or libvirt guests, whether CPU passthrough is available to the guest. Done means a short compatibility table exists for each host class. Where the documentation does not settle a question, record it as an item to confirm with the vendor before the pilot.
Record baseline values on a reference host
Before any change, an engineer captures the current effective values of each setting on one representative host: CPU frequency governor, transparent huge pages mode, memory overcommit policy, swap configuration and the CPU model and flags the guest exposes. Store the output with the host name, kernel version and date. Done means the baseline file is committed to the infrastructure repository and reviewed by a second engineer, so later comparisons have a fixed reference.
Apply the settings through configuration management
The platform team writes the target values into the configuration management code, using the same roles that already manage the rest of the host. Changes go through review and are applied to a pilot group first, not by hand over SSH. Kernel parameters and boot options belong in version-controlled files, and hypervisor CPU settings belong in the cloud or hypervisor template that builds the guest. Done means the pilot hosts converge without errors on a dry run and a real run.
Restart or reboot where the setting requires it
Some changes take effect at runtime, while boot parameters and some hypervisor CPU settings need a reboot or a new guest image. The engineer lists which settings require each action, then restarts the ClickHouse service on one replica at a time so the cluster keeps serving queries. Done means every host is back in service, the replica has caught up with its peers, and the service logs show no startup errors related to memory or kernel limits.
Verify effective values on every node
Engineers re-run the same capture commands used for the baseline on every node, not only the pilot, and compare the output with the target values. Checks should confirm the active governor, the active transparent huge pages mode, the overcommit setting, swap state and the CPU features visible to ClickHouse. Done means a diff report shows no unexpected differences, and any host that drifted is fixed and re-checked before the next step.
Load test on a pre-production environment
Before production, the team runs representative data and queries on a pre-production environment that uses the same kernel and hypervisor settings. The vendor's production FAQ recommends this step for any change. Engineers compare query latency, ingestion throughput, memory use and error logs against a run on the baseline configuration. Done means the results are recorded and approved by the data owner, and any regression is explained or fixed.
Document and rehearse the rollback
The team writes a rollback procedure that restores the baseline values through the same configuration management path, lists which steps need a reboot, and states who can authorize it. They rehearse it once on a pre-production host. Done means the runbook is stored with the change record, the rehearsal result is noted, and the on-call team knows where to find it before production work begins.

Which tuning changes create security and operations risk

Kernel and hypervisor settings sit below ClickHouse, so a change that looks minor on one host can alter query behavior, memory handling or availability across a whole cluster. The cards below cover where that risk comes from and the controls that keep host tuning consistent, reviewable and limited to the people who need it.

Inconsistent changes across replicas

A setting applied to one replica but not its peers can make the same query behave differently depending on which node answers it. Replicas that hold the same data may also differ in memory behavior under load, which shows up as intermittent slowness rather than a clear failure. Before and after any change, compare the effective values on every replica of each shard, not only the host where the change was made. Confirm that your configuration management covers all nodes, including Keeper hosts if they share a kernel profile.

Drift between hand-built hosts

When operators tune servers by hand with ad hoc commands, each host gradually accumulates a different set of kernel parameters, service overrides and governor settings. Drift is hard to see until an incident, and by then the cause is buried under months of unrecorded edits. Define the target values in one place, apply them through automation, and run a periodic check that reports any host whose live values differ from that definition. Ask your team how that check is scheduled and who receives its output.

Changes that need a reboot

Some tuning changes take effect only after a reboot or a service restart, and the file on disk can show a value that the running kernel does not use. A host that looks correct in configuration may still run old settings, which makes audits misleading. Record which changes are live, which need a restart and which need a reboot, and schedule them inside a maintenance window. Replica-aware rollouts, one node at a time, keep the cluster available while each host is restarted.

Kernel updates that reset settings

A kernel package upgrade can change default values, drop a boot parameter or alter how a feature such as transparent huge pages is exposed. Settings that were applied only at runtime disappear at the next boot, and the host returns to defaults without any error. After each kernel change, re-read the effective values and compare them with the approved baseline before returning the host to service. Make the baseline check part of the patch procedure, not a separate task that may be skipped.

Access to host and hypervisor settings

Changing host kernel settings, CPU governors or hypervisor CPU passthrough usually requires root access, and on virtual machines it can require access to the hypervisor itself. Grant that access only to named administrators who need it, use privileged access workflows that record who changed what, and review those grants on a schedule. Keep the database service account separate from host administration. Confirm with your security team how sudo rules, bastion access and hypervisor logs are retained and who can read them.

Replication does not stop human error

Replicas copy every change, including a mistaken one, so a bad tuning setting that degrades all nodes will be replicated in effect rather than corrected. ClickHouse documentation is explicit that replication alone does not protect against human error or corruption, so host tuning needs its own recovery path. Track changes to host and cluster settings like any other infrastructure change, with a written reason, a reviewer and a rollback step. Pair this with tested backups so that a faulty change can be recovered from.

Why tuning decisions need a pre-production test on representative data

Every setting covered in this topic, from the CPU governor to transparent huge pages and memory overcommit, should be validated on a pre-production environment with representative data and queries before it reaches production. The ClickHouse production guidance recommends exactly this, and it applies to OS tuning as much as to ClickHouse configuration. A setting that improves ingestion on one dataset can add latency to the merges and queries that matter most on another, and a lab with small or synthetic data will not show that difference.

The result of a tuning decision depends on the kernel version, the Linux distribution and the ClickHouse release running on top of it. A change in the kernel's memory management, its default for transparent huge pages, or the hypervisor's handling of CPU features can shift behavior even when your settings stay the same. The same applies to ClickHouse itself. The production guidance advises reading the changelog before upgrading because minor backward-incompatible changes can occur, so check each release's notes for anything touching memory, threads, or storage before you move. Treat every OS or ClickHouse upgrade as a trigger to rerun your benchmarks and compare them with a recorded baseline.

Keep a written record for each host profile: the kernel build, the distribution release, the hypervisor and its CPU passthrough mode, the ClickHouse version, and the measured results for ingestion rate, merge behavior and p95 query latency. Ask your platform or hardware vendor and your DeployOpen engineers to confirm which of these inputs you will need to freeze for audit and change-control purposes. When a new version arrives, the test should answer one question: does the tuned host still meet the target on the data you actually run, and if not, which setting needs to change?

Questions teams ask before they tune ClickHouse servers themselves or hire help

Can our team tune Linux for ClickHouse without outside help?

Yes, a capable Linux team can apply and verify these settings alone, provided it has a test environment and a clear change record. The difficulty is less in knowing each setting than in proving it under load on your exact kernel, distribution and hypervisor. A value that looks correct in a file can be overridden at boot, or can differ between hosts built at different times. In-house teams usually check the CPU governor, transparent huge pages, memory overcommit and swap on every node, then run ClickHouse-representative inserts and queries before and after each change. If your team lacks spare capacity, hypervisor access or change approval for production hosts, a fixed-scope engagement can cover that work. The right choice depends on how many hosts you run and how much control your organization requires.

What makes the Linux tuning effort larger or smaller?

The effort grows with the number of distinct server builds you run, not only with the number of servers. Each hypervisor layer adds work: bare metal hosts, KVM guests managed through libvirt and OpenStack compute nodes expose CPU and memory settings differently, and CPU passthrough into virtual machines needs its own check. Kernel and distribution diversity multiplies the checks, because the same setting can behave differently across releases. The main drivers are:

Number of hosts and how many build variants they represent
Hypervisor mix and whether guests use host CPU passthrough
Whether a pre-production environment with representative data already exists
How far load tests must reproduce your ingestion and query patterns

Fewer, identical hosts with a current inventory and a test cluster keep the work small. Ask for the inventory and the test scope before comparing quotes.

What does a Linux tuning engagement need from our side?

It needs access, people who own the platforms, a place to test, and a way to approve changes. Typically you provide an inventory of hosts with their distribution, kernel, hypervisor and storage layout, plus administrative access to those hosts for the agreed work. Your hypervisor or cloud team must be available to review OpenStack or libvirt settings, and your platform team must confirm which maintenance windows are acceptable. A test environment that matches production closely enough to reproduce ClickHouse behavior is needed before any production change. Your change approval process also has to be defined in advance, including who signs off, how rollback is handled and what evidence is recorded. Without these inputs, the schedule is set by waiting, not by the technical work.

How long does Linux tuning for ClickHouse take?

The duration depends mainly on how ready your environment is and how much testing the scope requires. Teams with a current inventory, a test cluster and standard hosts can move through the work faster than teams that must first document their hosts, build a test environment or wait for hypervisor changes to be approved. The testing scope also matters: a check of settings on a few hosts takes less time than repeated load tests across several kernel and hypervisor combinations. Because these variables differ for every organization, no general duration applies. A written proposal should show the milestones, the dependencies on your teams and the points where your approval is needed, so you can see which parts depend on you.

Are these Linux settings a one-time change or an ongoing task?

The initial configuration is one-time work, but verification is recurring. Kernel updates, distribution upgrades, hypervisor patches and ClickHouse upgrades can each change how a setting is applied or what the defaults are, so the settings need a fresh check after each of them. ClickHouse publishes which versions receive security updates, and its production guidance recommends reading the changelog before upgrading because minor backward-incompatible changes can occur. A practical routine is to keep a configuration baseline in version control, compare each host against it after patching, and rerun the load checks when the kernel or ClickHouse version changes. Ask the provider whether this recurring check is included in the fixed scope or sold as a retainer.

What should we ask for in a fixed-scope quote for this work?

Ask for a written scope that names every host group, hypervisor and kernel combination it covers, and for the deliverables expected at the end. A complete quote should state the baseline measurements, the settings to be verified, the test plan, the change rollout method and the evidence recorded for each host. It should also list what is excluded, such as ClickHouse configuration tuning, schema design, storage layout or hardware sizing, which are separate topics. Confirm who performs each task, what you must provide before work starts, how changes are approved and what the handover includes. Finally, ask whether post-upgrade verification is included or offered as an ongoing retainer. Compare quotes on the written scope, not on the total alone.

What to confirm for your kernel, distribution, hypervisor and ClickHouse version

Linux tuning for ClickHouse depends on four moving parts: the ClickHouse release, the operating system underneath it, the hypervisor that hosts it, and the cloud platform's host controls. Each item below is a check to complete with the vendor documentation and your own nodes before you change any setting.

ClickHouse release line in use

Confirm which release line your servers run and whether that line appears in the supported versions list in the ClickHouse security policy. The policy currently lists versions 26.9, 26.8, 26.7 and 26.3 as receiving security updates, and all other versions as unsupported. Also check whether you run a stable release or an LTS line, because the two follow different support windows described in the production FAQ. An unsupported line should be treated as an upgrade item before any tuning work begins.

Recommended OS values per version

Pull the operating system settings that the ClickHouse documentation recommends for the exact version you run, and record them in your build notes. Recommendations can change between releases, so do not reuse values copied from an older runbook. Compare each setting against your golden image and your configuration management code, and note any deliberate deviation with a reason.

Kernel and distribution combinations

List every kernel and distribution pair your ClickHouse hosts run, including the hosts in staging and disaster recovery sites. Ask the vendor or check the release notes to see which combinations the release is tested on, and treat untested combinations as a validation task. Kernel updates applied by patching tools can change behavior, so record the kernel version on each node and plan a test pass after kernel changes.

Hypervisor and exposed CPU model

On OpenStack or libvirt, confirm which CPU model the hypervisor exposes to guests and whether CPU passthrough is enabled for ClickHouse virtual machines. A generic CPU model can hide instruction set features that the server uses, which affects performance and can change behavior between hosts. Check that every compute host in the same cluster presents the same model, so a replica does not land on a host with different capabilities after a migration.

Host-level settings on the cloud platform

Confirm whether your cloud or virtualization platform lets you change the settings that ClickHouse needs at the host level, such as the CPU governor, transparent huge pages and memory overcommit. Managed node images, locked hypervisor profiles and restricted kernel parameters can block these changes. Ask the platform team to document which settings are controllable on each node type, and what happens to them during node replacement or autoscaling.

Monitoring of effective values

Check that your monitoring can show the effective value of each tuned setting on every node, not only the value in the configuration file. A setting can be written correctly and still be overridden at boot, by a tuning service or by a hypervisor profile. Confirm that you can alert on drift, and that the check runs after kernel updates and node rebuilds. Ask your operations team which metrics and collection agents already report these values.

How DeployOpen scopes and delivers ClickHouse host tuning

DeployOpen treats host tuning as part of the ClickHouse build, not a checklist run after launch. We scope the operating system settings against your hypervisor, kernel and hardware, apply them in your own infrastructure, and document each setting with the reason it is there.

How we scope

Inventory the hosts, hypervisors, kernel versions and CPU models that will run ClickHouse nodes and Keeper nodes.
Agree in writing which settings are in scope, including governor, huge pages, overcommit, swap and CPU passthrough.
Confirm the ClickHouse version line you will run, using the supported versions in the security policy as the baseline.
Engagements are fixed-scope, so deliverables and acceptance tests are agreed before work starts. Ongoing support is available as a retainer.

How we build

Apply tuning through configuration management so every node in a replica set or shard carries identical settings.
Test each setting on a pre-production cluster with representative data and queries before it reaches production.
Verify CPU passthrough and virtual CPU flags on OpenStack or libvirt guests against the hardware they will run on.
Measure the effect of each change with benchmarks and system metrics, and record the results alongside the change.

How we hand over

Deliver a written host baseline covering each setting, its value, the reason for it and the file or unit that sets it.
Provide runbooks for kernel and ClickHouse upgrades that re-check tuning after each change of version or kernel.
Document the checks your team runs to detect drift, such as governor state, huge page status and swap usage.
Train your operators on the baseline and walk through the handover checklist before the engagement closes.

How we support

Review the host baseline when you change kernel versions, hypervisors, hardware or ClickHouse release lines.
Confirm your team can reproduce the baseline on a spare node or a restore test cluster before relying on it.
Offer retainer support for ongoing tuning reviews, upgrades and continuous testing if your team wants that capacity.
Ask any partner to confirm how they handle change control, access to your hosts and the evidence they hand over.

Linux server tuning for ClickHouse