Skip to main content

System Configuration

This page outlines the modifications necessary that should be made to the configuration of the system where you are running an Oasis Node instance. To prepare the system for running an Oasis Node, we will guide you through the process of creating a dedicated user account, increasing the file descriptor limit and optional AppArmor profiles.

Create a user

Nothing in Oasis Node requires elevated privileges, so running the Oasis Node with root privileges is not allowed. Attempting to run the oasis-node process as the root user will terminate immediately on startup. You will need to create a dedicated user account to manage the Oasis Node processes.

To create a new user run as root:

adduser oasis

If you have an existing data directory, change its ownership to the oasis user. If not, you may skip this step.

chown -R oasis /node/data

Adjust the user as appropriate to your setup. For example, setting the oasis user's Shell to /usr/sbin/nologin prevents (accidentally) logging in as this user. See the following examples on how to create a user on different systems.

As root, run:

adduser --system oasis --shell /usr/sbin/nologin

Increase file descriptor limit

Make sure that the user under which you are running your Oasis Node has a high-enough file descriptor limit as the databases can have many opened files. Running out of file descriptors can lead to the node stopping unexpectedly.

You can check the file descriptor limit by running the following as the same user that will run the Oasis Node:

ulimit -n

If this number is lower than 102400 you should consider increasing it by updating your system configuration. You can configure temporary limits by running:

ulimit -n 102400

This limit will only apply to any processes started from the same shell after the command was executed. If you want to make the change permanent, you have the following options:

In case you are running your Oasis Node process via systemd, you can add the following directive under the [Service] section:


AppArmor profiles

In case your system is using AppArmor and is restricting unprivileged user namespace creation, you may need to allow them for Bubblewrap (the sandbox that Oasis Node is using to execute runtimes).

You can use the following policy in /etc/apparmor.d/bwrap:

abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {

# Site-specific additions and overrides. See local/README for details.
include if exists <local/bwrap>

Then reload AppArmor policies by running:

sudo systemctl reload apparmor.service

Example snippets for different setups

You may find the following snippets helpful in case you are running oasis-node process with systemd, Docker or runit.

Add a User directive to the Oasis service's systemd unit file:


Below can be found a simple systemd unit file for oasis-node that can be used as a starting point.

Description=Oasis Node

ExecStart=/node/bin/oasis-node --config /node/etc/config.yml