Skip to content

cluster-availability-group-create-prereq.md

Latest commit

 

History

History
191 lines (135 loc) · 8.55 KB

cluster-availability-group-create-prereq.md

File metadata and controls

191 lines (135 loc) · 8.55 KB
author rwestMSFT
ms.author randolphwest
ms.date 01/02/2026
ms.service sql
ms.subservice linux
ms.topic include
ms.custom
linux-related-content

Prerequisites

Before you create the availability group, complete the following steps:

  • Set up your environment so that all the servers that host availability replicas can communicate.
  • Install [!INCLUDE ssnoversion-md].

On Linux, you must create an availability group before you add it as a cluster resource for the cluster to manage. This article provides an example that creates the availability group.

  1. Update the computer name for each host.

    Each [!INCLUDE ssnoversion-md] instance name must be:

    • 15 characters or fewer.
    • Unique within the network.

    To set the computer name, edit /etc/hostname. The following example shows how to edit /etc/hostname with vi:

    sudo vi /etc/hostname

  2. Configure the hosts file.

    [!NOTE]
    If the DNS server registers hostnames with their IP addresses, you don't need to complete the following steps. Validate that all the nodes intended to be part of the availability group configuration can communicate with each other. (A ping to the hostname should reply with the corresponding IP address.) Also, make sure that the /etc/hosts file doesn't contain a record that maps the localhost IP address 127.0.0.1 with the hostname of the node.

    The hosts file on every server contains the IP addresses and names of all servers that participate in the availability group.

    The following command returns the IP address of the current server:

    sudo ip addr show

    Update /etc/hosts. The following example shows how to edit /etc/hosts with vi:

    sudo vi /etc/hosts

    The following example shows /etc/hosts on node1 with additions for node1, node2, and node3. In this sample, node1 refers to the server that hosts the primary replica, and node2 and node3 refer to servers that host the secondary replicas.

    127.0.0.1    localhost localhost4 localhost4.localdomain4
::1          localhost localhost6 localhost6.localdomain6
10.128.18.12 node1
10.128.16.77 node2
10.128.15.33 node3

Install SQL Server

Install [!INCLUDE ssnoversion-md]. The following links point to [!INCLUDE ssnoversion-md] installation instructions for various distributions:

Note

Starting in [!INCLUDE sssql25-md], SUSE Linux Enterprise Server (SLES) isn't supported.

Enable Always On availability groups

Enable Always On availability groups for each node that hosts a [!INCLUDE ssnoversion-md] instance, and then restart mssql-server. Run the following script:

sudo /opt/mssql/bin/mssql-conf set hadr.hadrenabled 1
sudo systemctl restart mssql-server

Enable an AlwaysOn_health Event session

You can optionally enable Extended Events (XE) to help with root-cause diagnosis when you troubleshoot an availability group. Run the following command on each instance of [!INCLUDE ssnoversion-md]:

ALTER EVENT SESSION AlwaysOn_health ON SERVER
WITH (STARTUP_STATE = ON);
GO

For more information about this XE session, see Configure Extended Events for availability groups.

Create a certificate

The [!INCLUDE ssnoversion-md] service on Linux uses certificates to authenticate communication between the mirroring endpoints.

The following Transact-SQL script creates a master key and a certificate. It then backs up the certificate and secures the file with a private key. Update the script with strong passwords. Connect to the primary [!INCLUDE ssnoversion-md] instance. To create the certificate, run the following Transact-SQL script:

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<master-key-password>';

CREATE CERTIFICATE dbm_certificate
WITH SUBJECT = 'dbm';

BACKUP CERTIFICATE dbm_certificate
TO FILE = '/var/opt/mssql/data/dbm_certificate.cer'
WITH PRIVATE KEY (
    FILE = '/var/opt/mssql/data/dbm_certificate.pvk',
    ENCRYPTION BY PASSWORD = '<private-key-password>'
);

At this point, your primary [!INCLUDE ssnoversion-md] replica has a certificate at /var/opt/mssql/data/dbm_certificate.cer and a private key at /var/opt/mssql/data/dbm_certificate.pvk. Copy these two files to the same location on all servers that host availability replicas. Use the mssql user, or give permission to the mssql user to access these files.

For example, on the source server, the following command copies the files to the target machine. Replace the <node2> values with the names of the [!INCLUDE ssnoversion-md] instances that host the replicas.

cd /var/opt/mssql/data
scp dbm_certificate.* root@<node2>:/var/opt/mssql/data/

On each target server, give permission to the mssql user to access the certificate.

cd /var/opt/mssql/data
chown mssql:mssql dbm_certificate.*

Create the certificate on secondary servers

The following Transact-SQL script creates a master key and a certificate from the backup that you created on the primary [!INCLUDE ssnoversion-md] replica. Update the script with strong passwords. The decryption password is the same password that you used to create the .pvk file in a previous step. To create the certificate, run the following script on all secondary servers:

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<master-key-password>';

CREATE CERTIFICATE dbm_certificate
FROM FILE = '/var/opt/mssql/data/dbm_certificate.cer'
WITH PRIVATE KEY (
    FILE = '/var/opt/mssql/data/dbm_certificate.pvk',
    DECRYPTION BY PASSWORD = '<private-key-password>'
);

In the previous example, replace <private-key-password> with the same password you used when creating the certificate on the primary replica.

Create the database mirroring endpoints on all replicas

Database mirroring endpoints use the Transmission Control Protocol (TCP) to send and receive messages between the server instances that participate in database mirroring sessions, or host availability replicas. The database mirroring endpoint listens on a unique TCP port number.

The following Transact-SQL script creates a listening endpoint named Hadr_endpoint for the availability group. It starts the endpoint and gives connection permission to the certificate that you created. Before you run the script, replace the values between < ... >. Optionally, you can include an IP address LISTENER_IP = (0.0.0.0). The listener IP address must be an IPv4 address. You can also use 0.0.0.0.

Update the following Transact-SQL script for your environment on all [!INCLUDE ssnoversion-md] instances:

CREATE ENDPOINT [Hadr_endpoint]
AS TCP (LISTENER_PORT = 5022)
FOR DATABASE_MIRRORING
(
    ROLE = ALL,
    AUTHENTICATION = CERTIFICATE dbm_certificate,
    ENCRYPTION = REQUIRED ALGORITHM AES
);

ALTER ENDPOINT [Hadr_endpoint]
STATE = STARTED;

Note

If you use [!INCLUDE ssnoversion-md] Express edition on one node to host a configuration-only replica, the only valid value for ROLE is WITNESS. Run the following script on [!INCLUDE ssnoversion-md] Express edition:

CREATE ENDPOINT [Hadr_endpoint]
AS TCP (LISTENER_PORT = 5022)
FOR DATABASE_MIRRORING
(
    ROLE = WITNESS,
    AUTHENTICATION = CERTIFICATE dbm_certificate,
    ENCRYPTION = REQUIRED ALGORITHM AES
);

ALTER ENDPOINT [Hadr_endpoint]
STATE = STARTED;

You must open the TCP port on the firewall for the listener port.

Important

The only authentication method supported for the database mirroring endpoint is CERTIFICATE. The WINDOWS option isn't available.

For more information, see The database mirroring endpoint (SQL Server).