---
title: Operating System Configuration
slug: LXzLcOYhmpzvBuETqg1eG
description: Learn about configuring your operating system to optimize performance and compatibility with Ocient.
docTags: 
createdAt: Mon Jul 03 2023 21:41:51 GMT+0000 (Coordinated Universal Time)
updatedAt: Mon Mar 30 2026 18:52:28 GMT+0000 (Coordinated Universal Time)
---

The Ocient® System Configuration procedure assumes that these steps have been performed on the Foundation Nodes and Loader Nodes in the database cluster. Some of these steps require root user permissions.&#x20;

Use `sudo` when performing these steps in your command-line interface.&#x20;

:::::WorkflowBlock
:::WorkflowBlockItem
## Prepare the Operating System Configuration

You must prepare the operating system with this configuration to run Ocient software:

- Configure Network interface controllers (NICs) and firewall for use by Ocient.
- Set the timezone to UTC.
- If OPAL drives are installed, unlock or revert them to factory state.
- Optional: Mount points `/opt/ocient` and `/var/opt/ocient` are mounted on separate storage devices.
:::

:::WorkflowBlockItem
## Confirm the Ocient Installation

To check the installation, run this command on each node to show the software version.

```shell
/opt/ocient/current/rolehostd --build-info
```

If the software is not installed or is the wrong version, see the [Ocient Application Installation](<././Ocient Application Installation.md>) instructions.&#x20;
:::

::::WorkflowBlockItem
## Apply Required Kernel Settings

In order to achieve high-performance levels, you must set specific kernel settings. You cannot set these settings at runtime. Therefore, the system must pass these parameters to the kernel at boot time.

### **Automatically Apply Kernel Settings**

You can automatically configure the kernel settings and apply them by running the `ockernelparams` script in the Ocient software package. This script detects the current system hardware and adjusts the `grub` bootloader kernel parameters. Then, the script updates the `grub` configuration with `grub2-mkconfig` or `update-grub` (depending on the Linux® distribution).

Run this command and specify the appropriate node role.

```shell
/opt/ocient/scripts/ockernelparams --node-role {sql,loader,foundation,metadata}
```

:::hint{type="info"}
You can also manually configure kernel settings. See [Manual Kernel Settings]() for more information.&#x20;
:::

### **Check Current Kernel Settings**

Run this command to show the current settings for the kernel that is running.

:::hint{type="info"}
You need to reboot after any changes are made to kernel parameters in the bootloader configuration.
:::

```shell
cat /proc/cmdline
```

```none
BOOT_IMAGE=(hd0,gpt2)/boot/vmlinuz-4.18.0-305.19.1.el8_4.x86_64 root=UUID=165df3b2-9221-43be-967d-d91483c07219 ro crashkernel=auto rhgb quiet transparent_hugepage=never isolcpus=0-23,26-49,52-75,78-101 hugepagesz=1G hugepages=1024 hugepagesz=2M hugepages=16384
```

The exact values can vary depending on the DRAM of the machine and the intended role for the node.

Check that the number of free 1G huge pages matches the number specified at the command line. You can check this number using this command.

```shell
cat /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages
```

*Output*

```bash
 1024
```

The returned value should match your configuration.

### Manual Kernel Settings

This section describes the optional kernel settings that you can manually configure. To automatically configure these settings, see [Automatically Apply Kernel Settings]().

You must add these settings that follow the `grub` bootloader kernel parameters for the listed applicable node types.&#x20;

**Setting:&#x20;**`transparent_hugepages`

Ocient requires that `transparent_hugepages` be disabled because Ocient software needs strict control over which huge pages it allocates.

**Applicable Node Types:&#x20;**

- Foundation Nodes
- Loader Nodes
- SQL Nodes

**Kernel Setting:**

```shell
transparent_hugepage=never
```

**Setting:&#x20;**`isolcpus`

To give Ocient software exclusive use of the majority of the cores on the system, the kernel is isolated from the cores using the `isolcpus` parameter. This isolation ensures that the system executes the kernel code only on a small number of cores where Ocient is not running logic that is critical for performance.

The pattern is to isolate all but the last two physical cores of each CPU from the kernel for CPUs with 26 or more cores. This means that two cores (4 threads) per CPU are available to the kernel.

For CPUs with fewer than 26 cores, all but the last physical core of each CPU is isolated.

**Applicable Node Types:&#x20;**

- Foundation Nodes

**Kernel Setting:**

- Dual 28-core CPUs (Intel® 6348)

```shell
isolcpus=0-25,28-53,56-81,84-109
```

- Dual 32-core CPUs (Intel 6338)

```shell
isolcpus=0-29,32-61,64-93,96-125
```

- Dual 96-core CPUs (AMD® 9654)

```shell
isolcpus=0-93,96-189,192-285,288-381
```

**Setting: Huge Pages**

Ocient utilizes huge pages to streamline the management of large amounts of memory in the system. The system uses 2MB and 1GB huge pages, depending on the node type. These huge pages must be reserved at boot time because otherwise, the system memory quickly becomes too fragmented to allocate the number of huge pages needed at runtime. These settings are the expected huge page settings.

:::hint{type="info"}
Metadata Nodes do not use huge pages.&#x20;
:::

| **Node Type**                       | **Installed DRAM** | **Huge Page Kernel Parameters**                                                                   |
| ----------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
| Foundation or SQL                   | 768 GB             | `hugepagesz=1G hugepages=384 hugepagesz=2M hugepages=16384`                                       |
| Foundation or SQL                   | 1024 GB            | `hugepagesz=1G hugepages=680 hugepagesz=2M hugepages=16384`                                       |
| Foundation or SQL                   | 1152 GB            | `hugepagesz=1G hugepages=768 hugepagesz=2M hugepages=16384`                                       |
| Foundation or SQL                   | 1536 GB            | `hugepagesz=1G hugepages=1024 hugepagesz=2M hugepages=16384`                                      |
| Foundation or SQL                   | 2048 GB            | `hugepagesz=1G hugepages=1364 hugepagesz=2M hugepages=16384`                                      |
| Foundation or SQL                   | 2304 GB            | `hugepagesz=1G hugepages=1536 hugepagesz=2M hugepages=16384`                                      |
| Loader                              | 768 GB             | `hugepagesz=1G hugepages=384 hugepagesz=2M hugepages=16384`                                       |
| Loader                              | 1024 GB            | `hugepagesz=1G hugepages=512 hugepagesz=2M hugepages=16384`                                       |
| Loader                              | 1152 GB            | `hugepagesz=1G hugepages=576 hugepagesz=2M hugepages=16384`                                       |
| Loader                              | 1536 GB            | `hugepagesz=1G hugepages=768 hugepagesz=2M hugepages=16384`                                       |
| Loader                              | 2048 GB            | `hugepagesz=1G hugepages=1024 hugepagesz=2M hugepages=16384`                                      |
| Loader                              | 2304 GB            | `hugepagesz=1G hugepages=1152 hugepagesz=2M hugepages=16384`                                      |
| Metadata (standalone administrator) | N/A                | No huge pages. Use the `noHugePages` parameter when bootstrapping node: <br />`noHugePages: true` |


::::

::::WorkflowBlockItem
## Prepare NVMe Drives

:::hint{type="info"}
These steps are for Foundation Nodes, Loader Nodes, and SQL Nodes only.
:::

To prepare NVMe drives on Foundation Nodes, Loader Nodes, and SQL Nodes, these nodes must be in a state where they are connected to the uio\_pci\_generic or vfio-pci driver and not contain a partition table. To initialize the drives for use by Ocient that have been previously partitioned, you must perform these steps.

1\. Identify the OS drives. The OS drives have partitions that are mounted to mount points such as `/`. In this example, `nvme0n1` is the OS drive.

```shell
lsblk
NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
nvme0n1     259:0    0  1.8T  0 disk
├─nvme0n1p1 259:1    0  512M  0 part /boot/efi
└─nvme0n1p2 259:2    0  1.8T  0 part /
```

2\. Ensure all drives are bound to the NVMe driver so the NVMe drives show up as standard NVMe devices. List the NVMe drives to identify the drive identifiers.

```shell
sudo /opt/ocient/scripts/nvme-driver-util.sh bind-nvme

/opt/ocient/scripts/nvme-driver-util.sh

BDF		Numa Node	Driver name		Device name
0000:01:00.0	0		nvme			nvme0n1
0000:3b:00.0	0		nvme    		-
0000:3c:00.0	0		nvme    		-
0000:5e:00.0	0		nvme    		-
0000:5f:00.0	0		nvme    		-
0000:86:00.0	1		nvme    		-
0000:87:00.0	1		nvme    		-
0000:88:00.0	1		nvme    		-
0000:89:00.0	1		nvme    		-
```

3\. For each NVMe drive that you need to erase and prepare for Ocient (not the OS drive), run this command by replacing `X` and `Y` to match the device name.

```shell
sudo nvme format /dev/nvmeXnY format --ses=1
```

:::hint{type="warning"}
This command formats the specified drive and erases all data on the drive. Ensure that the OS drive is not formatted if it is an NVMe drive.&#x20;
:::

Some drives do not support the `nvme format` command. In that case, you can overwrite the partition table by zeroing out the beginning of the drive with this command. This command does not securely erase the whole drive, but does allow it to be used by Ocient.

```shell
sudo dd if=/dev/zero of=/dev/nvmeXnY bs=1024K count=1024
```

4\. Bind the drives to the UIO or VFIO driver by running this command. The script automatically chooses the appropriate driver after detecting if the `IOMMU` setting is enabled. Any NVMe drives with mounted partitions (i.e. the OS drive) remain on the NVMe driver. Show all expected NVMe drives on the node attached to the UIO or VFIO driver.

```shell
sudo /opt/ocient/scripts/nvme-driver-util.sh bind-vfio

/opt/ocient/scripts/nvme-driver-util.sh

BDF		Numa Node	Driver name		Device name
0000:01:00.0	0		nvme			nvme0n1
0000:3b:00.0	0		vfio-pci		-
0000:3c:00.0	0		vfio-pci		-
0000:5e:00.0	0		vfio-pci		-
0000:5f:00.0	0		vfio-pci		-
0000:86:00.0	1		vfio-pci		-
0000:87:00.0	1		vfio-pci		-
0000:88:00.0	1		vfio-pci		-
0000:89:00.0	1		vfio-pci		-
```
::::

::::WorkflowBlockItem
## Clear Files from Any Previous Ocient Setup

To bootstrap a node that was previously part of an Ocient System, you must clear a set of files from any previous setup of Ocient from the `/var/opt/ocient/` directory. These commands remove these files.

```shell
sudo rm -f /var/opt/ocient/rolehostd.conf
sudo rm -f /var/opt/ocient/ocient.key
sudo rm -f /var/opt/ocient/ocient.crt
sudo rm -f /var/opt/ocient/ocient.crt.original
sudo rm -f /var/opt/ocient/*.raft
sudo rm -f /var/opt/ocient/bootstrap.completed
```

:::hint{type="info"}
Do not remove files in the `localKeyStore` directory if OPAL drives are present and encryption is not disabled. If these files are removed, the drive encryption must be reset using an external utility.
:::
::::
:::::

## Related Links

[Ocient Software Upgrade](<./././Ocient Software Upgrade.md>)

[Install an Ocient System](<./././Install an Ocient System.md>)

***

**Linux®*&#x20;is the registered trademark of Linus Torvalds in the U.S. and other countries.*

