We have been discussing the running of nodes on Oasis and going through the prerequisites in detail. So far, we have covered hardware and cloud providers, as well as stake requirements and node installation steps. In this part, I will walk you through the system configuration prerequisites.
Before you run a node on Oasis, you need to make a few modifications to the system. This comprises creating a dedicated user account, increasing the file descriptor limit, and, optionally, setting up AppArmor profiles.
User creation
Nothing in the Oasis Node requires elevated privileges, so running it as root is not allowed. If you try to run the oasis-node process as the root user, it will terminate immediately on startup. So, the first step of system configuration is to create a dedicated user account to manage the Oasis Node processes.
To create a new user, run this command as root.
adduser oasis
Some of you may have an existing data directory. The next step is essential for them; others do not need to execute it. This involves changing the ownership of the data directory to the oasis user.
chown -R oasis /node/data
Note: You can adjust the user to your setup when you create it. For example, setting the oasis user's shell to /usr/sbin/nologin will prevent accidental logging in as this user. Here is how to create the user this way on different systems.
Ubuntu
Run this as root.
adduser --system oasis --shell /usr/sbin/nologin
Fedora
Run this as root.
useradd -r -s /usr/sbin/nologin
Ansible
Add this task to the playbook.
- name: Create oasis user
ansible.builtin.user:
name: oasis
comment: Oasis Services user
system: yes
shell: /usr/sbin/nologin
File descriptor limit increase
After user creation, the first thing to do is to check that its file descriptor limit is high enough to accommodate running the node. As there is a possibility of the databases having many open files, starting with an increased limit of file descriptors is recommended. Otherwise, the node can stop unexpectedly.
To check the file descriptor limit as the same user that will run the Oasis Node, run this command.
ulimit -n
If this shows anything lower than 102400, you should increase the limit by updating your system configuration. You have the option to configure temporary limits or make the change permanent.
Temporary
ulimit -n 102400
Permanent
The temporary limit only applies to processes that are started from the same shell after the command was executed. So, you can choose to make the change permanent using any of the following options.
systemd
If you are running your Oasis Node via systemd, you will need to add a directive under the [Service] section.
LimitNOFILE=102400
Docker
If you have chosen Docker to run your node, passing this option to docker run will increase the limit.
--ulimit nofile=102400:1048576
limits.conf
For this option, you, as root, will have to create a system-wide resource limits configuration file in /etc/security/limits.d/99-oasis-node.conf. For example:
* soft nofile 102400
* hard nofile 1048576
Notes:
- If you want to change the limit for any particular user running the Oasis Node, you can insert the name of that user in place of
*. - If you keep
*, the limit change applies to all processes in your setup, not only the node-running process. - You may also need to restart the system for the configured changes to take effect.
AppArmor profiles
I mentioned at the start that AppArmor profiles are optional. It is only applicable for you if your system uses AppArmor and restricts unprivileged user namespace creation. In that case, the workaround is to allow Bubblewrap, the designated sandbox used by the Oasis Node to execute runtimes. The steps differ between the following Ubuntu versions.
Ubuntu 24.04
Add this policy in /etc/apparmor.d/bwrap.
abi <abi/4.0>,
include <tunables/global>
profile bwrap /usr/bin/bwrap flags=(unconfined) {
userns,
# Site-specific additions and overrides. See local/README for details.
include if exists <local/bwrap>
}
Ubuntu 24.10+
Run this command to enable the Bubblewrap user namespace restriction policy.
sudo ln -s /usr/share/apparmor/extra-profiles/bwrap-userns-restrict /etc/apparmor.d/
Irrespective of the Ubuntu version, you will need to reload AppArmor policies by running this command.
sudo systemctl reload apparmor.service
Example snippets
Whether you use systemd, Docker, or runit setups to run oasis-node, you may find the following snippets helpful.
systemd
Add this User directive to the Oasis service's systemd unit file.
...
User=oasis
...
Here is an example of a simple systemd unit file for oasis-node that you can use as a starting point.
[Unit]
Description=Oasis Node
After=network.target
[Service]
Type=simple
User=oasis
WorkingDirectory=/node/data
ExecStart=/node/bin/oasis-node --config /node/etc/config.yml
Restart=on-failure
RestartSec=3
LimitNOFILE=1024000
[Install]
WantedBy=multi-user.target
Docker
Add the USER instruction to your Oasis service's Dockerfile.
...
USER oasis
...
runit
Wrap the invocation in a chpst command.
chpst -u oasis oasis-node ...
This concludes the system configuration part of the prerequisites series. In the next part, I will discuss how to set up a Trusted Execution Environment (TEE).
- For technical specs, APIs, architecture, and integration guides, the Oasis documentation is your starting point.
- For direct support on specific issues, the Oasis engineering team and other node operators are available in the node-operators channel on the official Discord.
Top comments (0)