Add clients

This page describes how to add clients to a bare-metal cluster.

Clients are used to run applications that need to access the WEKA filesystems. They do not contribute CPUs or drives to the cluster and only connect to the cluster to use its filesystems.

A default WEKA installation uses the cgroups functionality to limit or isolate resources for WEKA sole usage. For example, using specific CPUs.

WEKA backends and clients that serve protocols can run on a supported OS with cgroups V1 (legacy).

Customers using a supported OS with cgroups V2 (hierarchy) or want to modify the cgroups usage can either set it during the agent installation or edit the service configuration file (see Modify the cgroups usage).

If the OS is configured with cgroups hybrid mode, which operates with cgroups V1 and V2, WEKA uses V1 by default.

What is the cgroups feature?

cgroups, short for control groups, is a feature in the Linux kernel that allows for fine-grained resource allocation and management of system resources such as CPU, memory, and I/O. It enables administrators to create hierarchies of processes and allocate system resources based on defined rules.

With cgroups, processes can be organized into groups, and each group can be allocated specific amounts of resources such as CPU time, memory, or network bandwidth. This allows for more efficient use of system resources and can help prevent individual processes from monopolizing system resources.

Add stateless clients

To use the WEKA filesystems from a client, just call the mount command. The mount command automatically installs the software version, and there is no need to join the client to the cluster.

To mount a filesystem in this method, first, install the WEKA agent from one of the backend instances and then mount the filesystem.


# Agent Installation (one time)
curl http://Backend-1:14000/dist/v1/install | sh

# Creating a mount point (one time)
mkdir -p /mnt/weka

# Mounting a filesystem
mount -t wekafs -o net=eth0 backend-1/my_fs /mnt/weka

For the first mount, this installs the WEKA software and automatically configures the client. For more information on mount and configuration options, refer to Mount a filesystem using the stateless clients feature.

Configuring the client OS to mount the filesystem at boot time automatically is possible. For more information, refer to Mount a filesystem using the traditional method or Mount filesystems using autofs.

Clients can be deployed on diskless servers. They can use RAM for the WEKA client software and NFS mount for the traces. For more information, contact the Customer Success Team.

Each client must have a unique IP and FQDN.

Modify the cgroups usage

Customers using a supported OS with cgroups V2 (hierarchy ) or want to modify the cgroups usage can set the cgroups usage during the agent installation or edit the service configuration file.

The cgroups setting includes the following modes:

  • auto: WEKA tries using cgroups V1 (default). If it fails, the cgroups is set to none automatically.

  • force: WEKA always uses cgroups V1. If the OS does not support it, WEKA fails.

  • none: WEKA never uses cgroups. Even if it runs on OS with cgroups V1.

Set the cgroups usage during the agent installation

In the agent installation command line, specify the required cgroups mode.


curl http://Backend-1:14000/dist/v1/install | WEKA_CGROUPS_MODE=none sh

Edit the service configuration file

  1. Open the service configuration file /etc/wekaio/service.conf and add one of the following:

    • cgroups=auto

    • cgroups=force

    • cgroups=none

  2. Restart the WEKA agent service.

  3. Verify the cgroups setting by running the weka local status command.


[root@weka-cluster] #weka local status
Weka v4.2.0 (CLI build 4.2.0)
Cgroups: mode=auto, enabled=true

Containers: 1/1 running (1 weka)
Nodes: 2/2 running (2 READY)
Mounts: 1

Add stateful clients, which are always part of the cluster

Adding instances that do not contribute resources to the cluster but are used for mounting filesystems is possible. It is recommended to use the previously described method for adding client instances for mounting purposes. However, in some cases, adding them to the cluster permanently is helpful. For example, use these instances as NFS/SMB servers, which are always expected to be up.

1. Install the WEKA software

Install the WEKA software.

  • Once the WEKA software tarball is downloaded from, run the untar command.

  • Run the command on each server, according to the instructions in the Install tab.

All clients in a WEKA system cluster must use the same software version as the backends or a maximum of one version back. The backend containers must run the same WEKA software version except during upgrades (as managed by the upgrade process).

2. Join the cluster

Command: weka cluster container add

Once the client is in the stem mode (this is the mode defined immediately after running the command), use the following command line on the client to add it to the cluster:

weka -H <backend-hostname> cluster container add <client-hostname>

Parameters in the command line



An existing hostname (IP or FQDN) of one of the existing backend instances in the cluster.


A unique hostname (IP or FQDN) of the client to add.

On completion of this stage, the container-id of the newly added container will be received. Make a note of it for the next steps.

3. Configure the container as a client

Command: weka cluster container cores

To configure the new container as a client, run the following command:

weka cluster container cores <container-id> <cores> --frontend-dedicated-cores=<frontend-dedicated-cores>

Parameters in the command line




A valid identifier of the container to add to the cluster.


The number of physical cores to allocate to the WEKA client.


The number of physical cores to be dedicated to frontend processes. Mandatory to configure a container as a client. Maximum 19 cores. For clients, the number of total cores and frontend-dedicated-cores must be equal.

4. Configure client networking

Command: weka cluster container net add

If the new client is to communicate with the WEKA cluster over the kernel UDP stack, running this command is unnecessary.

If a high-performance client is required and the appropriate network NIC is available, use the following command to configure the networking interface used by the client to communicate with the WEKA cluster:

weka cluster container net add <container-id> <device> --ips=<ips> --netmask=<netmask> --gateway=<gateway>




A valid identifier of the container to add to the cluster.


A valid network interface device name (for example, eth1).


A valid IP address of the new interface.


The IP address of the default routing gateway. The gateway must reside within the same IP network of ips (as described by netmask).

Not relevant for IB / L2 non-routable networks.


The number of bits that identify a network ID (also known as CIDR). For example, the netmask of has 16 netmask bits.

When configuring an InfiniBand client, do not pass the --ips, --netmask and --gateway parameters.

InfiniBand/Ethernet clients can only join a cluster with the same network technology connectivity. It is possible to mix InfiniBand and Ethernet clients in the same cluster as long as the cluster backends are connected to both network technologies.

5. Apply the container configuration

Command: weka cluster container apply

After successfully configuring the container and its network device, run the following command to finalize the configuration by activating the container:

weka cluster container apply <container-id> [--force]




A comma-separated string of valid identifiers of the containers to add to the cluster.


A boolean indicates not to prompt for confirmation. The default is not to force a prompt.