This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Altinity Stable Builds

ClickHouse tested and verified for production use with 3 years of support.

ClickHouse, as an open source project, has multiple methods of installation. Altinity recommends either using Altinity Stable builds for ClickHouse, or community builds.

The Altinity Stable builds are releases with extended service of ClickHouse that undergo rigorous testing to verify they are secure and ready for production use. Altinity Stable Builds provide a secure, pre-compiled binary release of ClickHouse server and client with the following features:

  • The ClickHouse version release is ready for production use.
  • 100% open source and 100% compatible with ClickHouse community builds.
  • Provides Up to 3 years of support.
  • Validated against client libraries and visualization tools.
  • Tested for cloud use including Kubernetes.

For more information regarding the Altinity Stable builds, see Altinity Stable Builds for ClickHouse.

Altinity Stable Builds Life-Cycle Table

The following table lists Altinity Stable builds and their current status. Community builds of ClickHouse are no longer available after Community Support EOL (shown in red). Contact us for build support beyond the Altinity Extend Support EOL.

Release Notes Build Status Latest Version Release Date Latest Update Support Duration Community Support End-of-Life* Altinity Extended Support End-of-Life**
23.3 Available, FIPS-Compatible 23.3.13.7 14 Jul 2023 06 Oct 2023 3 years 31 Mar 2024 14 Jul 2026
22.8 Available, FIPS-Compatible 22.8.20.12 13 Feb 2023 24 Aug 2023 3 years
31 Aug 2023
13 Feb 2026
22.3 Available 22.3.15.33 15 Jul 2022 22 Dec 2022 3 years
15 Mar 2023
15 Jul 2025
21.8 Available 21.8.15.7 11 Oct 2021 15 Apr 2022 3 years
31 Aug 2022
30 Aug 2024
21.3 Available 21.3.20.2 29 Jun 2021 10 Feb 2022 3 years
30 Mar 2022
31 Mar 2024
21.1 Available 21.1.11.3 24 Mar 2021 01 Jun 2022 2 years
30 Apr 2021
31 Jan 2023
20.8 Available Upon Request 20.8.12.2 02 Dec 2020 03 Feb 2021 2 years
31 Aug 2021
02 Dec 2022
20.3 Available Upon Request 20.3.19.4 24 Jun 2020 23 Sep 2020 2 years
31 Mar 2021
24 Jun 2022
  • *During Community Support bug fixes are automatically backported to community builds and picked up in refreshes of Altinity Stable builds.
  • **Altinity Extended Support covers P0-P1 bugs encountered by customers and critical security issues regardless of audience. Fixes are best effort and may not be possible in every circumstance. Altinity makes every effort to ensure a fix, workaround, or upgrade path for covered issues.

1 - Altinity Stable Builds Install Guide

How to install the Altinity Stable Builds for ClickHouse

Installing ClickHouse from the Altinity Stable Builds, available from https://builds.altinity.cloud, takes just a few minutes.

General Installation Instructions

When installing or upgrading from a previous version of ClickHouse from the Altinity Stable Builds, review the Release Notes for the ClickHouse version to install and upgrade to before starting. This will inform you of additional steps or requirements of moving from one version to the next.

Part of the installation procedures recommends you specify the version to install. The Release Notes lists the version numbers available for installation.

There are three main methods for installing Altinity Stable Builds:

  • Deb Packages
  • RPM Packages
  • Docker images

The package sources come from two sources:

  • Altinity Stable Builds: These are built from a secure, internal build pipeline and available from https://builds.altinity.cloud. Altinity Stable Builds are distinguishable from community builds when displaying version information:

    select version()
    
    ┌─version()─────────────────┐
     21.8.11.1.altinitystable  
    └───────────────────────────┘
    
  • Community Builds: These are made by ClickHouse community members, and are available at repo.clickhouse.tech.

1.1 - Altinity Stable Builds Deb Install Guide

How to install the Altinity Stable Builds for ClickHouse on Debian based systems.

Installation Instructions: Deb packages

ClickHouse can be installed from the Altinity Stable builds, located at https://builds.altinity.cloud, or from the ClickHouse community repository.

Deb Prerequisites

The following prerequisites must be installed before installing an Altinity Stable build of ClickHouse:

  • curl
  • gnupg2
  • apt-transport-https
  • ca-certificates

These can be installed prior to installing ClickHouse with the following command:

sudo apt-get update
sudo apt-get install curl gnupg2 apt-transport-https ca-certificates

Deb Packages for Altinity Stable Build

To install ClickHouse Altinity Stable build via Deb based packages from the Altinity Stable build repository:

  1. Update the apt-get local repository:

    sudo apt-get update
    
  2. Install the Altinity package signing keys:

    sudo sh -c 'mkdir -p /usr/share/keyrings && curl -s https://builds.altinity.cloud/apt-repo/pubkey.gpg | gpg --dearmor > /usr/share/keyrings/altinity-archive-keyring.gpg'
    
  3. Update the apt-get repository to include the Altinity Stable build repository with the following commands:

    sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/altinity-archive-keyring.gpg] https://builds.altinity.cloud/apt-repo stable main" > /etc/apt/sources.list.d/altinity.list'
    
    sudo apt-get update
    
  4. Install either a specific version of ClickHouse, or the most current version.

    1. To install a specific version, include the version in the apt-get install command. The example below specifies the version 21.8.10.1.altinitystable:
    version=21.8.10.1.altinitystable
    
    sudo apt-get install clickhouse-common-static=$version clickhouse-client=$version clickhouse-server=$version
    
    1. To install the most current version of the ClickHouse Altinity Stable build without specifying a specific version, leave out the version= command.
    sudo apt-get install clickhouse-client clickhouse-server
    
  5. When prompted, provide the password for the default clickhouse user.

  6. Restart server.

    Installed packages are not applied to an already running server. It makes it convenient to install the packages first and restart later when convenient.

    sudo systemctl restart clickhouse-server
    

Remove Community Package Repository

For users upgrading to Altinity Stable builds from the community ClickHouse builds, we recommend removing the community builds from the local repository. See the instructions for your distribution of Linux for instructions on modifying your local package repository.

Community Builds

For instructions on how to install ClickHouse community, see the ClickHouse Documentation site.

1.2 - Altinity Stable Builds RPM Install Guide

How to install the Altinity Stable Builds for ClickHouse on RPM based systems.

Installation Instructions: RPM packages

ClickHouse can be installed from the Altinity Stable builds, located at https://builds.altinity.cloud, or from the ClickHouse commuinity repository.

Depending on your Linux distribution, either dnf or yum will be used. See your particular distribution of Linux for specifics.

The instructions below uses the command $(type -p dnf || type -p yum) to provide the correct command based on the distribution to be used.

RPM Prerequisites

The following prerequisites must be installed before installing an Altinity Stable build:

  • curl
  • gnupg2

These can be installed prior to installing ClickHouse with the following:

sudo $(type -p dnf || type -p yum) install curl gnupg2

RPM Packages for Altinity Stable Build

To install ClickHouse from an Altinity Stable build via RPM based packages from the Altinity Stable build repository:

  1. Update the local RPM repository to include the Altinity Stable build repository with the following command:

    sudo curl https://builds.altinity.cloud/yum-repo/altinity.repo -o /etc/yum.repos.d/altinity.repo    
    
  2. Install ClickHouse server and client with either yum or dnf. It is recommended to specify a version to maximize compatibly with other applications and clients.

    1. To specify the version of ClickHouse to install, create a variable for the version and pass it to the installation instructions. The example below specifies the version 21.8.10.1.altinitystable:
    version=21.8.10.1.altinitystable
    sudo $(type -p dnf || type -p yum) install clickhouse-common-static-$version clickhouse-server-$version clickhouse-client-$version
    
    1. To install the most recent version of ClickHouse, leave off the version- command and variable:
    sudo $(type -p dnf || type -p yum) install clickhouse-common-static clickhouse-server clickhouse-client
    

Remove Community Package Repository

For users upgrading to Altinity Stable builds from the community ClickHouse builds, we recommend removing the community builds from the local repository. See the instructions for your distribution of Linux for instructions on modifying your local package repository.

RPM Downgrading Altinity ClickHouse Stable to a Previous Release

To downgrade to a previous release, the current version must be installed, and the previous version installed with the --setup=obsoletes=0 option. Review the Release Notes before downgrading for any considerations or issues that may occur when downgrading between versions of ClickHouse.

For more information, see the Altinity Knowledge Base article Altinity packaging compatibility greater than 21.x and earlier.

Community Builds

For instructions on how to install ClickHouse community, see the ClickHouse Documentation site.

1.3 - Altinity Stable Builds Docker Install Guide

How to install the Altinity Stable Builds for ClickHouse with Docker.

Installing with Docker

These included instructions detail how to install a single Altinity Stable build of ClickHouse container through Docker. For details on setting up a cluster of Docker containers, see ClickHouse on Kubernetes.

Docker Images are available for Altinity Stable builds and Community builds. The instructions below focus on using the Altinity Stable builds for ClickHouse.

The Docker repositories are located at:

To install a ClickHouse Altinity Stable build through Docker:

  1. Create the directory for the docker-compose.yml file and the database storage and ClickHouse server storage.

    mkdir clickhouse
    cd clickhouse
    mkdir clickhouse_database
    
  2. Create the file docker-compose.yml and populate it with the following, updating the clickhouse-server to the current altinity/clickhouse-server version:

    version: '3'
    
    services:
      clickhouse_server:
          image: altinity/clickhouse-server:21.8.10.1.altinitystable
          ports:
          - "8123:8123"
          volumes:
          - ./clickhouse_database:/var/lib/clickhouse
          networks:
              - clickhouse_network
    
    networks:
      clickhouse_network:
          driver: bridge
          ipam:
              config:
                  - subnet: 10.222.1.0/24
    
  3. Launch the ClickHouse Server with docker-compose or docker compose depending on your version of Docker:

    docker compose up -d
    
  4. Verify the installation by logging into the database from the Docker image directly, and make any other necessary updates with:

    docker compose exec clickhouse_server clickhouse-client
    root@67c732d8dc6a:/# clickhouse-client
    ClickHouse client version 21.3.15.2.altinity+stable (altinity build).
    Connecting to localhost:9000 as user default.
    Connected to ClickHouse server version 21.1.10 revision 54443.
    
    67c732d8dc6a :)
    

1.4 - Altinity Stable Builds macOS Install Guide

How to install the Altinity Stable Builds for ClickHouse with macOS.

Installing on macOS

Altinity Stable for ClickHouse is available to macOS users through the Homebrew package manager. Users and developers who use macOS as their preferred environment can quickly install a production ready version of ClickHouse within minutes.

The following instructions are targeted for users of Altinity Stable for ClickHouse. For more information on running community or other versions of ClickHouse on macOS, see either the Homebrew Tap for ClickHouse project or the blog post Altinity Introduces macOS Homebrew Tap for ClickHouse.

macOS Prerequisites

Brew Install for Altinity Stable Instructions

By default, installing ClickHouse through brew will install the latest version of the community version of ClickHouse. Extra steps are required to install the Altinity Stable version of ClickHouse. Altinity Stable is installed as a keg-only version, which requires manually setting paths and other commands to run the Altinity Stable for ClickHouse through brew.

To install Altinity Stable for ClickHouse in macOS through Brew:

  1. Add the ClickHouse formula via brew tap:

    brew tap altinity/clickhouse
    
  2. Install Altinity Stable for ClickHouse by specifying clickhouse@altinity-stable for the most recent Altinity Stable version, or specify the version with clickhouse@{Altinity Stable Version}. For example, as of this writing the most current version of Altinity Stable is 21.8, therefore the command to install that version of altinity stable is clickhouse@21.8-altinity-stable. To install the most recent version, use the brew install command as follows:

    brew install clickhouse@altinity-stable
    
  3. Because Altinity Stable for ClickHouse is available as a keg only release, the path must be set manually. These instructions will be displayed as part of the installation procedure. Based on your version, executable directory will be different based on the pattern:

    $(brew --prefix)/{clickhouse version}/bin

    For our example, clickhouse@altinity-stable gives us the following path setting:

    export PATH="/opt/homebrew/opt/clickhouse@21.8-altinity-stable/bin:$PATH"

    Using the which command after updating the path reveals the location of the clickhouse-server executable:

    which clickhouse-server
    /opt/homebrew/opt/clickhouse@21.8-altinity-stable/bin/clickhouse-server
    
  4. To start the Altinity Stable for ClickHouse server use the brew services start command. For example:

    brew services start clickhouse@altinity-stable
    
  5. Connect to the new server with clickhouse-client:

    > clickhouse-client
    ClickHouse client version 21.8.13.1.
    Connecting to localhost:9000 as user default.
    Connected to ClickHouse server version 21.11.6 revision 54450.
    
    ClickHouse client version is older than ClickHouse server. It may lack support for new features.
    
    penny.home :) select version()
    
    SELECT version()
    
    Query id: 128a2cae-d0e2-4170-a771-83fb79429260
    
    ┌─version()─┐
    │ 21.11.6.1 │
    └───────────┘
    
    1 rows in set. Elapsed: 0.004 sec.
    
    penny.home :) exit
    Bye.
    
  6. To end the ClickHouse server, use brew services stop command:

    brew services stop clickhouse@altinity-stable
    

1.5 - Altinity Stable Build Guide for ClickHouse

How to build ClickHouse from Altinity Stable manually.

Manual build process for Altinity Stable for ClickHouse

If you’d like to build Altinity Stable for ClickHouse yourself, cloning the repo and building the code is straightforward.

ClickHouse can run on the most minimum hardware to full clusters. The following hardware requirements are recommended for building and running ClickHouse:

  • 16GB of RAM (32 GB recommende)
  • Multiple cores (4+)
  • 20-50 GB disk storage

Clone the repo

To build Altinity Stable for ClickHouse, you’ll need to select a particular version. As of this writing the most recent verified version is v23.3.8.22.altinitystable, so that’s what we’ll build in our examples.

If you’d like to build some other version, there is a list of all supported versions in the repo. Simply replace the tag name of the most recent version with whatever other version you’d like to build.

As of this writing, the most recent verified version is v23.3.8.22.altinitystable. We use the --recursive option of the git clone command to make sure we get all of the code and its dependencies. The --single-branch option tells git not to download the main branch or anything else. The last wrinkle to the clone command is to put the files into the folder AltinityStableClickHouse:

git clone --recursive -b v23.3.8.22.altinitystable --single-branch https://github.com/Altinity/clickhouse.git AltinityStableClickHouse

With the code downloaded (this will take a while, btw), switch to the AltinityStableClickHouse directory.

Direct build instructions for Debian-based Linux

To build Altinity Stable for ClickHouse from the source code:

  1. Install the prerequisites.

    sudo apt-get install cmake python ninja-build clang-13
    
  2. With those packages installed, install clang-12.

    sudo apt install clang-12
    
  3. Make sure you’re in the AltinityStableClickHouse directory, then create and enter the build directory. this doesn’t work, there’s no cmakelists.txt file

    mkdir build && cd build
    
  1. Set the compile variables for clang-13 and start the ninja build.

    CC=clang-13 CXX=clang++-13 cmake .. -GNinja
    
  2. Use the ninja command to build your own Altinity Stable for ClickHouse:

    ninja clickhouse
    
  3. When the build is finished, Altinity Stable for ClickHouse will be in the programs folder, and can be run with the following commands:

    1. ClickHouse Server: clickhouse server
    2. ClickHouse Client: clickhouse client

1.6 - Legacy ClickHouse Altinity Stable Releases Install Guide

How to install the ClickHouse Altinity Stable Releases from packagecloud.io.

ClickHouse Altinity Stable Releases are specially vetted community builds of ClickHouse that Altinity certifies for production use. We track critical changes and verify against a series of tests to make sure they’re ready for your production environment. We take the steps to verify how to upgrade from previous versions, and what issues you might run into when transitioning your ClickHouse clusters to the next Stable Altinity ClickHouse release.

As of October 12, 2021, Altinity replaced the ClickHouse Altinity Stable Releases with the Altinity Stable Builds, providing longer support and validation. For more information, see Altinity Stable Builds.

Legacy versions of the ClickHouse Altinity Stable Releases are available from the Altinity ClickHouse Stable Release packagecloud.io repository, located at https://packagecloud.io/Altinity/altinity-stable.

The available Altinity ClickHouse Stable Releases from packagecloud.io for ClickHouse server, ClickHouse client and ClickHouse common versions are:

  • Altinity ClickHouse Stable Release 21.1.10.3
  • Altinity ClickHouse Stable Release 21.3.13.9
  • Altinity ClickHouse Stable Release 21.3.15.2
  • Altinity ClickHouse Stable Release 21.3.15.4

General Installation Instructions

When installing or upgrading from a previous version of legacy ClickHouse Altinity Stable Release, review the Release Notes for the version to install and upgrade to before starting. This will inform you of additional steps or requirements of moving from one version to the next.

Part of the installation procedures recommends you specify the version to install. The Release Notes lists the version numbers available for installation.

There are three main methods for installing the legacy ClickHouse Altinity Stable Releases:

Altinity ClickHouse Stable Releases are distinguishable from community builds when displaying version information. The suffix altinitystable will be displayed after the version number:

select version()

┌─version()─────────────────┐
 21.3.15.2.altinitystable 
└───────────────────────────┘

Prerequisites

This guide assumes that the reader is familiar with Linux commands, permissions, and how to install software for their particular Linux distribution. The reader will have to verify they have the correct permissions to install the software in their target systems.

Installation Instructions

Legacy Altinity ClickHouse Stable Release DEB Builds

To install legacy ClickHouse Altinity Stable Release version DEB packages from packagecloud.io:

  1. Update the apt-get repository with the following command:

    curl -s https://packagecloud.io/install/repositories/Altinity/altinity-stable/script.deb.sh | sudo bash
    
  2. ClickHouse can be installed either by specifying a specific version, or automatically going to the most current version. It is recommended to specify a version for maximum compatibility with existing clients.

    1. To install a specific version, create a variable specifying the version to install and including it with the install command:
    version=21.8.8.1.altinitystable
    sudo apt-get install clickhouse-client=$version clickhouse-server=$version clickhouse-common-static=$version
    
    1. To install the most current version of the legacy ClickHouse Altinity Stable release without specifying a specific version, leave out the version= command.
    sudo apt-get install clickhouse-client clickhouse-server clickhouse-server-common
    
  3. Restart server.

    Installed packages are not applied to the already running server. It makes it convenient to install packages first and restart later when convenient.

    sudo systemctl restart clickhouse-server
    

Legacy Altinity ClickHouse Stable Release RPM Builds

To install legacy ClickHouse Altinity Stable Release version RPM packages from packagecloud.io:

  1. Update the yum package repository configuration with the following command:

    curl -s https://packagecloud.io/install/repositories/Altinity/altinity-stable/script.rpm.sh | sudo bash
    
  2. ClickHouse can be installed either by specifying a specific version, or automatically going to the most current version. It is recommended to specify a version for maximum compatibility with existing clients.

    1. To install a specific version, create a variable specifying the version to install and including it with the install command:
    version=version=21.8.8.1.altinitystable
    sudo yum install clickhouse-client-${version} clickhouse-server-${version} clickhouse-server-common-${version}
    
    1. To install the most current version of the legacy ClickHouse Altinity Stable release without specifying a specific version, leave out the version= command.
    sudo yum install clickhouse-client clickhouse-server clickhouse-server-common
    
  3. Restart the ClickHouse server.

    sudo systemctl restart clickhouse-server
    

2 - FIPS-Compatible Altinity Stable Builds

Altinity Stable Builds with FIPS 140-2 support

Altinity offers FIPS-compatible Altinity Stable Builds beginning with ClickHouse version 22.8. These builds offer the same maintenance guarantees as regular Altinity Stable Builds and are covered by Altinity enterprise support.

What are Altinity FIPS-compatible builds?

FIPS 140-2 is a United States standard for cryptography used in high-security government environments. FIPS 140-2 specifies a number of properties for encryption including handling of keys, permitted versions of TLS, allowed cipher suites, and protections against tampering of builds.

ClickHouse uses BoringSSL libraries for encryption of most application and inter-server traffic. Altinity FIPS-compatible builds use the same BoringSSL source code version that has passed FIPS 140-2 certification. Combined with documented procedures this enables ClickHouse to function in a manner that is compatible with the FIPS standard.

FIPS-compatible Altinity Stable Builds are built, tested, and released in the same way as regular Altinity Stable Builds for ClickHouse. FIPS-compatible builds have altinityfips embedded in the release name. They use separate channels for distribution on builds.altinity.cloud and have separate release notes. FIPS-compatible builds are also available as Docker images.

Other than support for FIPS 140-2, FIPS-compatible builds are essentially identical to Altinity Stable Builds. Any differences are highlighted in the release notes.

FIPS-Compatible Network Interfaces

The following network connections of ClickHouse can operate in FIPS-compatible mode in Altinity FIPS builds.

Name Type Description Default Server Port
HTTPS Port Server Accepts HTTPS API connections from clients 8443
Secure Native TCP Port Server Accepts native TCP protocol connections from clients (e.g., clickhouse-client) 9440
Interserver HTTPS Port Server & Client Used for communication between ClickHouse replicas 9010
ZooKeeper Client Connection Client Connection from ClickHouse to ZooKeeper or ClickHouse Keeper
Keeper Server Port Server Accepts ZooKeeper protocol connections from clients 9181
Raft Server Port Server & Client Used for synchronization between ClickHouse Keeper servers 9234

Prerequisites for FIPS-Compatible Operation

The minimal requirements for FIPS-compatible operation are:

  • Install FIPS-compatible Altinity Stable Build.
  • Apply FIPS-compatible configuration settings to set allowed ports, TLS version, and ciphers.

Installation

Yum and Apt Packages

FIPS-compatible Altinity Stable releases are distributed from a separate repo from standard Altinity Stable Builds. Follow the directions to set the repo for FIPS-compatible builds at (builds.altinity.cloud)[https://builds.altinity.cloud/].

Important note! FIPS builds use a different repo from standard Altinity Stable Builds. Be sure to scroll down the builds.altinity.cloud page to see the FIPS build locations.

Once the repo is set correctly, you can download and install packages using the same commands as for regular Altinity Stable Builds.

Docker

FIPS-compatible Altinity Stable containers have fips in the container tag. For example:

docker pull altinity/clickhouse-server:22.8.15.25.altinityfips

Configuration of Altinity Stable Builds for FIPS-Compatible Operation

To operate in a FIPS-compatible mode, users must update the ClickHouse configuration from the usual defaults. The specific changes include the following.

ClickHouse Server Configuration

Required server configuration changes including the following. These settings are by convention stored in /etc/clickhouse-server/config.xml and /etc/clickhouse-server/config.d/.

Disable all ports not in the FIPS-Compatible Network Protocol list, including the following. Comment them out and ensure they are not present in preprocessed_config.xml.

  • ClickHouse HTTP port
  • ClickHouse TCP port
  • Additional non-FIPS client protocols: MySQL, PostgreSQL, gRPC, etc.
  • Enable HTTPS and TCP secure protocols
  • Configure openSSL sections to restrict TLS to TLSv1.2 and FIPS 140.2-approved ciphers

Place configuration changes in file /etc/clickhouse-server/config.d/fips.xml. This will prevent your settings from being overridden when installing new Altinity Stable Builds. Here is an example of file contents.

<clickhouse>
  <https_port>8443</https_port>
  <tcp_port_secure>9440</tcp_port_secure>
  <openSSL>
    <server>
      <certificateFile>${CERT_PATH}/server.crt</certificateFile>
      <privateKeyFile>${CERT_PATH}/server.key</privateKeyFile>
      <dhParamsFile>${CERT_PATH}/dh_params.pem</dhParamsFile>
      <cipherList>ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:AES128-GCM-SHA256:AES256-GCM-SHA384</cipherList>
      <loadDefaultCAFile>true</loadDefaultCAFile>
      <cacheSessions>true</cacheSessions>
      <preferServerCiphers>true</preferServerCiphers>
      <requireTLSv1_2>true</requireTLSv1_2>
      <disableProtocols>sslv2,sslv3,tlsv1,tlsv1_1,tlsv1_3</disableProtocols>
      <!-- set to `none` for dev-tests with self-signed certificates -->
      <verificationMode>relaxed</verificationMode>
    </server>
    <client>
   	 <!-- in case of private CA, otherwise set `loadDefaultCAFile` to `true` and remove `caConfig` -->
   	 <loadDefaultCAFile>false</loadDefaultCAFile>
   	 <caConfig>${CA_PATH}/CA.crt</caConfig>
   	 <cacheSessions>true</cacheSessions>
   	 <preferServerCiphers>true</preferServerCiphers>
   	 <requireTLSv1_2>true</requireTLSv1_2>
   	 <disableProtocols>sslv2,sslv3,tlsv1,tlsv1_1,tlsv1_3</disableProtocols>
   	 <!-- set to 'none' for dev-tests with self-signed certificates -->
   	 <verificationMode>relaxed</verificationMode>
   	 <invalidCertificateHandler>
   		 <!-- AcceptCertificateHandler may not be used here -->
   		 <name>RejectCertificateHandler</name>
   	 </invalidCertificateHandler>
    </client>
  </openSSL>
</clickhouse>

Please note the following:

  • There is no need to set openSSL/fips value to true in xml above as it is ON by default in the FIPS build and can’t be turned off.
  • ${CERT_PATH} and ${CA_PATH} are placeholders. Replace them with appropriate values for your configuration.

ClickHouse Client Configuration

Clickhouse-client configuration settings are by convention stored in /etc/clickhouse-client/config.xml and /etc/clickhouse-client/config.d/.

To enable FIPS 140-2 operation for clickhouse-client, configure the openSSL section to restrict TLS to TLSv1.2 and FIPS 140.2-approved ciphers. Place values for the changes in /etc/clickhouse-client/config.d/fips.xml.

Verification of FIPS-Compatible Altinity Stable Operation

Verify FIPS library Startup

FIPS-compatible Altinity.Cloud servers will print the following message after a successful start-up test. This ensures that FIPS BoringSSL libraries are present and free from tampering.

$ grep 'FIPS mode' /var/log/clickhouse-server/clickhouse-server.log
2023.05.28 18:19:03.064038 [ 1 ] {} <Information> Application: Starting in FIPS mode, KAT test result: 1

Verify FIPS-Compatible Altinity Stable Version

To verify the software version, run select version() on the running server with any client program. This example confirms the version for both clickhouse-client as well as clickhouse-server.

$ clickhouse-client <options>
ClickHouse client version 22.8.15.25.altinityfips (altinity build).

5f1b329b5fdf :) select version()

SELECT version()

┌─version()───────────────┐
│ 22.8.15.25.altinityfips │
└─────────────────────────┘