Configure a SUSE host

This guide explains how to prepare a SUSE Linux Enterprise Server (SLES) host for an Elastic Cloud Enterprise (ECE) installation. It covers the operating system configuration required before you install ECE, including Docker installation, XFS quota configuration, and other host-specific settings. The steps on this page target SLES 15 SP4.

Important

Make sure to use a supported combination of Linux distribution and container engine version as defined in our official Support matrix. Unsupported combinations can lead to various issues in your ECE environment, including failures when creating system deployments, upgrading workload deployments, proxy timeouts, and more.

FIPS (Federal Information Processing Standards) compliance is not officially supported in ECE. While ECE may function on FIPS-enabled systems, this configuration has not been validated through our testing processes and is not recommended for production environments.

Warning

SLES 12 SP5 reached general support end of life on October 31, 2024. Use SLES 15 or later for new Elastic Cloud Enterprise installations, and migrate existing SLES 12 SP5 hosts.

Prerequisites

Before you begin:

Identify a supported SLES and Docker version combination in the Support matrix. Substitute the example versions in this guide with the versions listed there.
Verify that required traffic is allowed. Check the Networking prerequisites for a list of ports that need to be open. The technical configuration depends on the underlying infrastructure.
Review the Users and permissions prerequisites for ECE. The commands in this guide assume that you are logged in as the non-root user that will install and run ECE, referred to throughout this guide as the ECE user. We recommend using a dedicated elastic user account. If it does not already exist, you can create it in the next section.
If you use one user to prepare the host and another to install ECE, replace $USER with the name of the ECE user in the applicable commands throughout this guide.

Prepare the user account for ECE

Follow these steps to configure the user account according to the Users and permissions prerequisites for ECE hosts.

Set up the OS groups and add your user.
1. Create the elastic and docker groups if they don't already exist:
```
sudo groupadd elastic
sudo groupadd docker
		
```
2. Add the user that will install and run ECE to both groups. Use one of the following options:
  - Create a dedicated user (recommended). If the user you are currently logged in as is not the user that will install and run ECE, create a dedicated user. The following example creates the recommended elastic user and adds it to both groups:
    sudo useradd -m -g elastic -G docker elastic
    Note
    
    If you create a dedicated ECE user, we recommend granting it sudo privileges and then logging in or switching to that user before continuing. This allows $USER to automatically resolve to the ECE user in the remaining commands.
    
    Alternatively, you can continue using a different account with sudo privileges and replace $USER with the name of the ECE user in commands throughout the rest of this guide.
  - Use the current user. If your current user will be the ECE user, add it to both groups:
    sudo usermod -aG elastic,docker $USER
Verify that the ECE user has a UID and GID of at least 1000:
```
id $USER
		
```
The output should show a uid and gid value of 1000 or higher.
Verify that the user's primary group is elastic:
```
id -gn $USER
		
```
If the command doesn't return elastic, find the elastic group GID:
```
grep elastic /etc/group
		
```
Then set the user's primary group to elastic:
```
sudo usermod -g <elastic_group_gid> $USER
		
```

Install Docker on SLES

ECE runs its services in containers, following a service-oriented architecture. These steps install Docker on SLES using zypper and leave the service stopped so it can be configured later.

Remove Docker and any previously installed Podman packages:

sudo zypper remove -y docker docker-ce podman podman-remote

Update packages to the latest available versions:
```
sudo zypper refresh
sudo zypper update -y
		
```
List the available Docker versions:
```
sudo zypper search -s -t package --match-exact docker
		
```
Note the version you want to install. Check the Support matrix for supported Docker versions for your OS. If the latest available version is compatible, you don't need to specify an explicit version in the next step.
Install Docker and other required packages on SLES 15. For example, to install Docker 25:
```
sudo zypper install -y curl device-mapper lvm2 net-tools docker=25.0.6_ce-150000.207.1
		
```
1. Replace 25.0.6_ce-150000.207.1 with the exact package version from the repository listing. Note that zypper does not support wildcards (for example, docker=25.*). To install the latest available version, specify docker without a version number.
Tip

If zypper reports that the requested Docker version isn't available, make sure the SUSE Containers Module is enabled. Refer to the SUSE documentation for instructions on adding the upstream Docker repository.
Ensure Docker is stopped before continuing. Docker is started later after the daemon configuration is updated:
```
sudo systemctl stop docker
		
```

Set up XFS quotas

ECE relies on XFS project quotas to manage disk space for Elasticsearch data directories. These quotas limit the amount of disk space available to each Elasticsearch cluster node based on the RAM-to-disk ratio defined by its instance configuration. For example, the default data.default instance configuration uses a 1:32 ratio, allowing 32 GB of disk space for every 1 GB of RAM assigned to a cluster node.

To use disk quotas, the file system mounted at /mnt/data must be an XFS file system with project quotas enabled. This guide creates a dedicated XFS file system for /mnt/data, which is the recommended configuration. If /mnt/data already resides on an XFS file system with project quotas enabled, you can skip the file system creation steps.

Note

You can use LVM, mdadm, or a combination of the two for block device management. However, their configuration is outside the scope of this guide and is not covered by ECE support.

Important

You must use XFS and have quotas enabled on all allocators. Otherwise, disk usage won't display correctly.

In the following example, XFS is set up on a single, pre-partitioned block device named /dev/xvdg1. Replace /dev/xvdg1 with the corresponding device on your host.

Format the partition:
```
sudo mkfs.xfs /dev/xvdg1
		
```
Add an entry to the /etc/fstab file for the new XFS volume. The default filesystem path used by ECE is /mnt/data:
```
/dev/xvdg1	/mnt/data	xfs	defaults,pquota,prjquota,x-systemd.automount  0 0
		
```

Prepare the data directories

Prepare the data directories used by Elastic Cloud Enterprise and Docker. These steps create the /mnt/data and /mnt/data/docker directories, mount an XFS file system if applicable, and apply the required ownership and permissions.

Create the /mnt/data directory if it doesn't already exist. It must be owned by the ECE user and the elastic group, and use 700 permissions:
```
sudo install -o $USER -g elastic -d -m 700 /mnt/data
		
```
If you configured a dedicated XFS file system in Set up XFS quotas:
1. Mount the file system configured in /etc/fstab:
```
sudo mount -a
		
```
2. Set the ownership and permissions for /mnt/data:
  
  Mounting the XFS file system for the first time replaces the original mount point. Reapply the required ownership and permissions to the mounted file system.
```
sudo chown $USER:elastic /mnt/data
sudo chmod 700 /mnt/data
		
```

Create the /mnt/data/docker directory for Docker storage:

sudo install -o $USER -g elastic -d -m 700 /mnt/data/docker

Configure system settings

Adjust the host settings required by ECE, including cgroup accounting, kernel parameters, and system limits.

Stop the nscd service and prevent it from starting automatically. This service can interfere with Elastic services:
```
sudo systemctl stop nscd
sudo systemctl disable nscd
		
```
Enable cgroup accounting for memory and swap space:
1. In the /etc/default/grub file, ensure the GRUB_CMDLINE_LINUX= variable includes these values:
```
cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem
		
```
2. Update your Grub configuration:
```
sudo update-bootloader
		
```
Configure kernel parameters:
```
cat <<EOF | sudo tee -a /etc/sysctl.conf
vm.max_map_count=1048576
net.ipv4.ip_forward=1
net.ipv4.tcp_retries2=5
vm.swappiness=1
EOF
		
```
1. Required by Elasticsearch
2. Enable IP forwarding so the Docker networking works as expected
3. Decrease the maximum number of TCP retransmissions to 5 as recommended for Elasticsearch TCP retransmission timeout
4. Make sure the host doesn't swap too early
Important

The net.ipv4.tcp_retries2 setting applies to all TCP connections and also affects the reliability of communication with systems other than Elasticsearch clusters. If your clusters communicate with external systems over a low quality network, you might need to select a higher value for net.ipv4.tcp_retries2.
1. Apply the settings:
```
sudo sysctl -p
		
```

Adjust the system limits by adding the following configuration values to the /etc/security/limits.conf file. If needed, make sure to replace elastic with your user name:

		*                soft    nofile         1024000
*                hard    nofile         1024000
*                soft    memlock        unlimited
*                hard    memlock        unlimited
elastic          soft    nofile         1024000
elastic          hard    nofile         1024000
elastic          soft    memlock        unlimited
elastic          hard    memlock        unlimited
elastic          soft    nproc          unlimited
elastic          hard    nproc          unlimited
root             soft    nofile         1024000
root             hard    nofile         1024000
root             soft    memlock        unlimited
		
	

Optional: Tune additional network kernel parameters for production workloads. Create a 70-cloudenterprise.conf file in /etc/sysctl.d/ and include these settings:
```
cat <<EOF | sudo tee /etc/sysctl.d/70-cloudenterprise.conf
net.ipv4.tcp_max_syn_backlog=65536
net.core.somaxconn=32768
net.core.netdev_max_backlog=32768
net.ipv4.tcp_keepalive_time=1800
net.netfilter.nf_conntrack_tcp_timeout_established=7200
net.netfilter.nf_conntrack_max=262140
EOF
		
```
Apply the settings:
```
sudo sysctl --system
		
```
Note
According to the Elasticsearch networking settings, Elasticsearch overrides TCP keepalive settings at the socket level for its own connections:
- If system-level values exceed 300 seconds, Elasticsearch automatically lowers them to 300 seconds.
- Values below 300 seconds are used as is.
For non-Elasticsearch connections such as the proxy layer, consider reducing the following TCP keepalive parameters to detect stale network sessions and prevent firewalls from dropping silent connections:
- net.ipv4.tcp_keepalive_time
- net.ipv4.tcp_keepalive_intvl
- net.ipv4.tcp_keepalive_probes

Configure the Docker daemon

After you install Docker and prepare the data directories, set the Docker daemon options required by ECE, then enable and restart the service to apply them. This configuration points Docker storage to the /mnt/data/docker directory created earlier.

Edit /etc/docker/daemon.json to make sure the following configuration values are present:

		{
  "storage-driver": "overlay2",
  "bip":"172.17.42.1/16",
  "icc": false,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "500m",
    "max-file": "10"
  },
  "data-root": "/mnt/data/docker",
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 1024000,
      "Soft": 1024000
    },
    "memlock": {
      "Name": "memlock",
      "Hard": -1,
      "Soft": -1
    },
    "nproc": {
      "Name": "nproc",
      "Hard": -1,
      "Soft": -1
    }
  }
}
		
	

The max-size and max-file options configure rotation for the json-file logs created by each container. Adjust these values to match your logging requirements.
The default-ulimits setting increases the maximum number of open file descriptors available to Docker containers.

Optional: If the Docker registry requires authentication, authenticate the elastic user to pull images from it by creating the file /home/elastic/.docker/config.json. This file needs to be owned by the elastic user. If you are using a user name other than elastic, adjust the path accordingly.

For example, if you use docker.elastic.co, the file content looks like this:
```
{
 "auths": {
   "docker.elastic.co": {
     "auth": "<auth-token>"
   }
 }
}
		
```
Enable Docker to start on boot:
```
sudo systemctl enable docker
		
```
Apply the updated Docker daemon configuration:
- Reload the Docker daemon configuration:
```
sudo systemctl daemon-reload
		
```
- Restart the Docker service:
```
sudo systemctl restart docker
		
```

Verify the host configuration

After completing the configuration steps in the previous sections, reboot the host and verify that the required system, storage, and Docker configuration has been applied successfully.

Reboot your system to ensure that all configuration changes take effect, then log back in as your ECE user:
```
sudo reboot
		
```
Verify that the Docker daemon started automatically:
```
sudo systemctl status docker
		
```
If Docker is not running, review your Docker installation and daemon configuration.
After rebooting, verify your Docker settings:
```
docker info | grep Root
		
```
If the command returns Docker Root Dir: /mnt/data/docker, your changes were applied successfully and persist as expected.

If the command returns Docker Root Dir: /var/lib/docker, review Configure the Docker daemon to make sure the Docker settings are applied correctly. For more information, check Custom Docker daemon options in the Docker documentation.

If the command returns a permission denied error, make sure your user is a member of the docker group.

Verify that the required kernel parameters are applied:

		sudo sysctl vm.max_map_count net.ipv4.ip_forward net.ipv4.tcp_retries2 vm.swappiness
		
	

The output should include the following values:

		vm.max_map_count = 1048576
net.ipv4.ip_forward = 1
net.ipv4.tcp_retries2 = 5
vm.swappiness = 1
		
	

Verify that memory cgroup accounting is enabled:
```
cat /proc/cmdline
		
```
Verify that the output includes the following kernel parameters:
```
cgroup_enable=memory swapaccount=1 cgroup.memory=nokmem
		
```
Verify the limits configured for the ECE user:
```
sudo su - elastic -c 'ulimit -n && ulimit -l && ulimit -u'
		
```
1. Replace elastic with your ECE user if you are using a different user name.
The output should show:
```
1024000
unlimited
unlimited
		
```

Verify default limits applied to Docker containers:

docker run --rm alpine sh -c 'ulimit -n && ulimit -l && ulimit -u'

The output should show:

		1024000
unlimited
unlimited
		
	

Verify that /mnt/data is mounted with XFS:
```
findmnt -no TARGET,FSTYPE,OPTIONS /mnt/data
		
```
The output should show /mnt/data as an xfs file system with project quotas enabled. For example:
```
/mnt/data xfs    rw,relatime,attr2,inode64,logbufs=8,logbsize=32k,prjquota
		
```
Verify the ownership and permissions of the data directory:
```
stat -c "%U:%G %a %n" /mnt/data
		
```
The output should show that the directory is owned by the ECE user and the elastic group, and use 700 permissions:
```
elastic:elastic 700 /mnt/data
		
```
Note

The /mnt/data/docker subdirectory is owned by root rather than by the ECE user, because it is managed by the Docker daemon. This is normal and does not indicate a misconfiguration.

Next steps

Repeat these host preparation steps for every host that you want to use with Elastic Cloud Enterprise. After preparing and verifying all hosts, continue to Installation procedures to install Elastic Cloud Enterprise.