🍺Full service node setup guide
This guide will walk you through the complete process of setting up, staking, and running an Oxen Service Node. The guide targets non-experts, so even if you're new to Linux or the command line, you should be able to follow the text without any difficulty.
You can run the Oxen Service Node software on any device running a supported operating system, but for the purposes of this guide, we'll assume you will be setting up a Service Node on a remote Ubuntu or Debian server. If you're new to Linux or running servers in general, this is the most straightforward approach. If you're more experienced and would prefer to run your Service Node on a different operating system, you'll need to modify the syntax of some commands to suit your system of choice.
Running an Oxen Service Node: Requirements
These are the current basic requirements for running a Service Node as of October 2021. They will almost certainly increase in the future as the technologies powered by the Oxen network grow in popularity, so keep an eye on the Oxen blog and join either our Telegram community or Session open group for all the latest updates.
Latest Oxen Service Node software
Server operating system
Ubuntu 20.04+ (latest LTS recommended) or Debian 11+ (latest stable recommended)
Storage
40GB or more
RAM
4-8GB (4GB absolute minimum)
Connectivity
100Mb or faster
Traffic
1TB per month or more
Power
Redundant with remote cycling ability, as found in most data centres
Note: It is possible for an experienced system administrator to run a Service Node on a server running an operating system other than Ubuntu or Debian. However, this requires additional work to start up and manage the required services, and is beyond the scope of this guide.
Table of Contents
Oxen Service Nodes in a nutshell
A Service Node starts as a full node on the Oxen network.
The full node becomes a Service Node when the owner locks the required amount of $OXEN (see below) and submits a registration transaction.
Once accepted by the network, the Service Node starts performing node operations and becomes eligible to receive periodic block rewards in the form of $OXEN.
Multiple participants can stake into one Service Node and can have the reward automatically distributed among them.
Service Node functionality
Service Nodes:
Receive, store, and forward encrypted Session messages
Route Lokinet traffic
Monitor other Service Nodes and vote on their performance
Are called into quorums that give them authority over Blink transactions
Produce new blocks for the network via Pulse PoS
Service Node set-up for new users
Step 1: Obtaining a server
Choosing where to set up your Service Node is the first and most critical decision you will face in setting up and running your node. There are a number of factors to consider. Because you will be locking up funds as part of operating your Service Node, you will want to ensure, at a minimum, that your server meets the technical requirements given above.
Your aim is to provide a stable, reliable server with good network connectivity, so that data can be efficiently routed to and from your node. An underpowered or poorly connected node will have a poor response time and add latency to the network for all users whose traffic passes through it, resulting in a less than optimal experience.
Additionally, you should consider the following factors. The more weight you attach to these factors when deciding where to run your node, the more value you will provide to the network.
Firstly, please consult the node distribution panel of the Oxen Dashboard, where you will find a breakdown of the current Service Node network by country and network owner.
Here, you will see that some countries and network operators are currently overrepresented on the Service Node network. In other words, a relatively small number of countries and network operators account for the majority of the network. This is bad for decentralisation.
To be robust against disparate forms of attack, a distributed network must pursue diversity at multiple levels:
Geographical diversity: distribution across multiple, disparate regions to minimise the effect of natural disasters
Sociopolitical diversity: distribution across multiple countries and legal jurisdictions to minimise the effects of unrest, legislation, coercion and espionage
Software diversity: multiple operating systems, distributions and release variants to minimise the effects of events that target or otherwise afflict a particular system, such as a zero-day vulnerability or the push of a buggy package.
You can make a significant contribution to decentralisation and provide greater value to the network by taking the above factors into account when choosing where to run your node. Take care, however, not to compromise on the core requirements of a node when trying to satisfy these goals.
If your server goes down while staked, your Service Node could be deregistered from the network and your funds locked for 30 days (without receiving rewards).
For this reason, we strongly recommend against running a Service Node from home. Most consumer internet connections have poor upstream bandwidth (Service Nodes require a high speed connection for both uploading and downloading data) and typically don't provide a static IP address, which is essential for a Service Node. Connection speed and support aside, transient power and network outages are a relatively common occurrence with consumer-grade connections and can easily disrupt home servers.
Typically, the simplest and cheapest way to host a server such as an Oxen Service Node is to lease a Virtual Private Server (VPS). There are literally hundreds of options when it comes to VPS providers, but some of the more commonly chosen companies and products are listed below.
Netcup
VPS 1000 G8
10.50
Evolution Host
STARTER
5.50
Online.net
Start-2-S-SSD
13.99
Scaleway
START1-M
9.33
OVH
VPS SSD 2
7.61
Leaseweb
Virtual Server XL
34.45
Digital Ocean
4 GB, 2 vCPUs
20 (24 from 22-07-0
Linode
4 GB, 2 vCPUs
20
Feral Hosting
Neon Capability
19.68
Trabia
VDS-8G
38.54
Hetzner
EX41-SSD (30 TB)
39.71
Note: We do not endorse any of these providers. The above list is merely a selection of some of the popular options at the time of writing. Of course, this popularity comes at the expense of decentralisation. To provide even greater value to the network, please consider running a node in a country and/or on a network with few or even no nodes according to the OXEN Dashboard. A useful resource in choosing a less common VPS provider is ExoticVM. Another good one is Server Hunter.
In any case, do not just settle on the first provider you encounter. No two are alike. Do your own research and choose a provider that seems professional, reputable and fits your budget.
The better ones will utilise KVM virtualisation technology. In particular, you should steer clear of VPSes that use OpenVZ. This is an incomplete form of virtualisation that allows VPS capacity to be oversold, and is usually incompatible with the service node software. Virtual machines created with it often lack a /dev/tun device, and even those that have this can still cause insurmountable problems for Lokinet.
A good VPS provider will also allow you to monitor your machine's resource consumption, seamlessly upgrade to a more powerful server at a later date, remotely reboot the host if it becomes unresponsive, and even recover or rebuild the system using out-of-band access if, for example, a bad configuration change results in lost network access.
When selecting your VPS’ operating system, please choose the latest Ubuntu LTS release or latest Debian stable release (currently 22.04 and 12, respectively) if you want to be able to follow the steps below verbatim. If you feel more confident and/or wish to run your server on another Linux distribution, the commands in this guide will still apply, but may need to be modified to suit your chosen operating system. In most cases, beginners and experts alike will be best served by sticking closely to this guide.
Step 2: Preparing your server
Every provider has a slightly different way of issuing you access to your new VPS. Most will send an email with the IP address, root username, and a root password to the VPS.
To access your server, you will need an SSH client for your operating system. Because we’re on Windows today, we’ll download PuTTY. Mac users can also use PuTTY. If you’re a Linux user, you probably don’t need us to tell you where to get an SSH client.
To connect to your VPS, you'll need to paste the provided IP address into the SSH client’s “Host Name (or IP address)” input box and click the “Open” button. The Port number can usually just be left as 22.
A terminal window will now appear, prompting you for your log-in details, username (root) and password, as provided by your VPS provider. When entering your password, characters will not appear in the terminal. This is normal. Hit enter after typing or pasting your password, and you should be logged in to your VPS.
Note: After logging in for the first time, the VPS may prompt you for a new password for the root account. The terminal will require you to enter the new password twice before you can start running commands. If you aren't prompted for a new
rootpassword but want to change it anyway, typesudo passwd. Choose something very secure!
2.1: Hot tips for using the console on Windows
Consoles don't quite work like the rest of your computer. Here are some basic tips for navigating your way around the command line!
Don't try copying something by using the usual
Ctrl + Chotkey! If you want to copy something, do so by highlighting text and then right clicking it and selecting Copy. Pasting works by right clicking a blank area in the console and selecting Paste.If you want to kill a process or stop something from running, press
Ctrl + C. (This is why you shouldn't try copying something with this hotkey!)You can always check the directory you are in by typing
pwd,and you can list its contents by typingls.You can always return to your home directory by typing
cdand pressing Enter.You can move into a given directory by typing
cd <name>or move back up one level by typingcd ...PuTTY allows you to easily duplicate or restart a session by right clicking the top of the window. Handy if you’re trying to do a few things at once.
2.2: Server preparation continued
Next, update your package lists (the lists that tell your server which software is available for install or upgrade). The following command downloads package lists from their respective package repositories and "updates" them to get information on the newest versions of packages and their dependencies. It will do this for all repositories and PPAs.
You'll notice a bunch of package lists were downloaded. Once this is complete run the below command to fetch new versions of any packages that came preinstalled on the system.
You'll be prompted to authorise the use of disk space. Type y and Enter to authorise.
If you are prompted during the upgrade that a new version of any file is available then click the up and down arrows until you are hovering over install the package maintainer’s version and click enter.
Alright, good to go. Our server is now set up, up to date, and is not running as root. On to the fun part!
2.3: Firewall Configuration
If you are using a firewall then ensure that the following ports are open/reachable
Port 22020 (storage server connectivity; requires both TCP and UDP)
Port 22021 (client to storage server)
Port 22022 (blockchain syncing)
Port 22025 (Service Node to Service Node)
Port 1090 (Lokinet router data; UDP only)
Step 3: Initial repository setup
You only need to do this step the first time you want to set up the Oxen repository; when you've done it once, the repository will automatically update whenever you fetch new system updates.
To add the apt repository, run the following commands.
This first command installs the public key used to sign the Oxen Service Node packages:
The second command tells apt where to find the packages. Note: Replace <DISTRO>with the appropriate value to match your operating system. If your VPS is running Ubuntu 22.04 as recommended for this guide, replace <DISTRO> with jammy.
Otherwise, to check your <DISTRO> , run the following command: lsb_release -sc
Alternatively, your <DISTRO> can be found by using the following list:
bookworm (Debian 12)
bullseye (Debian 11)
buster (Debian 10)
jammy (Ubuntu 22.04)
focal (Ubuntu 20.04)
bionic (Ubuntu 18.04)
We also have repositories for Debian testing (trixie or testing) and unstable (sid or unstable), and typically support the latest or upcoming Ubuntu non-LTS release (mantic, as of writing). Note, however, that none of these distribution versions are recommended for production service nodes.
Then resync your package repositories with:
Step 4: Oxen Service Node installation and operation
To install the software needed to run a Service Node, simply install the oxen-service-node package:
This will detect your public IP (or allow you to enter it yourself) and automatically update the /etc/oxen/oxen.conf configuration file with the necessary additional settings to run a Service Node.
Note: This process can take up to 6 hours for the blockchain to fully sync.
If you encounter an error during the syncing process due to a 15000 millisecond ping, you can run this command to fix it:
Alternatively, the blockchain can be typically be downloaded in a fraction of the time required to sync it via the network, using the following command:
4.1: Interacting with the running oxend
oxendIf you run the oxend command with an appended oxend command (note that sudo is not required!), the oxend command forwards this instruction to the running oxend. So, for example, to get the current oxend status you can run you would run:
To see the output log of your node you can run the following command:
This is useful to see if your node is syncing with the blockchain and to see other diagnostic messages that may come up from time to time. (Press Ctrl-C to stop watching the log).
For a full list of supported commands run:
You can also get basic statistics (such as uptime proof and ping times) on the running daemons from the systemctl status commands:
Step 5: Service Node registration
This section of the guide is split into two parts:
If you are an individual staker and do not require any other contributors to run your Service Node, jump into the Individual staking section.
If you want to run a pooled Service Node, jump into Setting up a pooled Service Node.
5.0.1: Retrieving your wallet address
You'll need your wallet address to register your Service Node. Copy your primary address from the Oxen GUI wallet, or run the address command from within the Oxen CLI wallet, and copy the output.
Note: Do not use subaddresses for staking. Subaddresses are currently unsupported for staking in the Oxen wallet.
5.1: Individual staking
To run a Service Node as the sole contributor, you'll need:
A fully synchronized, up-to-date Oxen daemon running on your Service Node
An Oxen wallet with at least 15,000 $OXEN in it (to meet the staking requirement to register your Service Node)
5.1.1: Preparing your node for registration
Log in (if not already logged in) to the VPS running the Service Node, then run the following command:
The daemon will output the current staking requirement and prompt you with an input to clarify whether you are an individual staker or you will be running a pool. Type y and click enter, as you will be the sole staker.
The daemon will now prompt you for the operator's (your) Oxen address — this is the address saved in Step 5. Retrieve this address, copy it, then paste it into the terminal and press Enter.
The daemon will now ask for a final confirmation. If you agree with the information provided, type y and click enter.
The daemon will output a command which looks similar to:
NOTE: You must run the command which your daemon outputs, and not the command shown above.
5.1.2: Registering your Service Node
To stake and register your Service Node, open your Oxen GUI wallet (with a balance of at least 15,000 $OXEN). Navigate to the Service Nodes tab, then the Registration subsection. Paste the register_service_node command from Step 5.1.1 above, and click Register Service Node.
If you're using the Oxen CLI wallet, simply paste the registration command directly into the CLI wallet prompt and hit Enter.
Well done! Continue to Step 6: Service Node check to make sure your Service Node is running properly.
5.2: Setting up a pooled Service Node
Minimum contribution rules
The Service Node staking requirement is fixed at 15,000 $OXEN. Service Nodes accept at most 10 contributions, meaning the minimum contribution to a Service Node is <Remaining Staking Requirement> ➗ <Number of Remaining Contributors>.
When setting up reserved spots in a pooled Service Node, the node administrator (you) must ensure the reserved stake amounts each meet the minimum staking requirement; contributors then simply stake their reserved amounts.
5.2.1: Pool operator
The operator (you) is the individual who will be hosting the pool and running the server hosting the Service Node, thus incurring the operating expenses involved in running a node.
To be an operator, you'll need to have:
A server running a fully synchronized, up-to-date
oxendAn Oxen wallet with at least 3750 $OXEN (to meet the minimum Service Node operator staking requirement)
1-3 other contributors who also have an Oxen wallet (either the CLI or GUI wallet) with enough $OXEN to meet their portion of the total stake
If the operator wants to reserve contribution spots for specific contributors, the operator will need the addresses of the contributors and the amounts the 1-3 contributors will stake.
If you have the above ready, we can now prepare the Service Node.
Log in (if not already logged in) to the VPS running the Service Node, then run the following command:
oxend will prompt you to specify if you will contribute the entire stake. Because you're running a pooled Service Node, type n and press Enter.
Next, oxend will request input for your desired operator fee. This value, which can be between 0-100, represents the percentage of the reward the operator will receive before the reward is distributed to all shareholders (including you!). For example, if you want to set up a 10% operator cut, you would type 10 and press Enter.
For example, imagine a Service Node with 4 contributors, including the operator, all staking equal amounts (25%). If the operator specified a 10% fee at this step, they would automatically receive 10% of the Service Node rewards, and the remaining 90% would then be split equally between the operator and the other 3 contributors.
The terminal will now display the minimum reserve the operator can contribute, and request input for the amount (in Oxen) you, as the operator, wish to contribute. Type your desired <operator contribution> and click return.
Once you've set your desired stake amount, you'll be prompted to either reserve spots for individuals that have already agreed to stake into the Service Node, or leave the pool open for anyone to contribute.
Option one: Reserved pool
If you want to reserve spots for specific contributors, type y at this prompt and click return.
The terminal will now prompt you for the number of additional contributors you've organised to stake into this Service Node. Type in the number of reserved contributors, not including yourself, and press Enter.
The daemon will now prompt you for the operator's (your) Oxen address — this is the address saved in Step 5. Retrieve this address, copy it, then paste it into the terminal and press Enter.
Next, you need to input the amount of Oxen each contributor will stake, and the Oxen Walled Address of the specific contributor(s).
NOTE: It is possible to reserve only some of the required total stake for specific contributors, while leaving the remaining staking amount open for other contributors.
The daemon will display a summary of the information you've entered. This is your chance for a final check over to make sure the correct information has been entered. To confirm the information is correct, type y and press Enter.
Option two: Open pool
If the operator wishes to leave their pool complete open to contributions they should type n at the reservation prompt and type Enter. The terminal will prompt you to input your address. Once your address has been entered, the terminal will display the remaining portion that needs to be contributed by others. If you agree, click y and hit return.
The daemon will display a summary of the information you've entered. This is your chance for a final check over to make sure the correct information has been entered. To confirm the information is correct, type y and press Enter.
Step 5.2.2: Registering your shared Service Node
Regardless of which option (closed or open) you've gone with, the daemon will output a command which looks similar to:
NOTE: You must run the command which your daemon outputs, and not the command shown above.
Copy the whole line of text in your daemon and paste it into your notepad, as you'll need to run this command from within your Oxen GUI (or CLI) wallet.
You have 2 weeks from the moment of registering the Service Node to run the register_service_node command, however it is advised to do it as soon as possible.
Before you disconnect from your VPS, run the following command:
This will output a bunch of information about your Service Node, but there's one part we're interested in at this stage: the long string of random letters and numbers after the characters SN: . This string is your Service Node's public key, used to identify your Service Node on the list of registered and operational Service Nodes. Select and copy the public key (do not copy any of the surrounding information).
On your local machine, open your Oxen GUI or CLI wallet and make sure your wallet contains at least 3750 $OXEN to meet the Service Node staking requirement. Once you're in your wallet and have checked the balance, run the command which was provided above when you ran the prepare_registration command. The wallet will prompt you to confirm your password, then the amount of $OXEN to stake. Confirm this by typing y and clicking enter.
Once this command completes, your staking transaction will be sent to be included on the blockchain. It may take a few minutes for the transaction to be mined into a block; you can check the status using the following command:
You can also check your node's status by looking for your <Service Node Public Key> in the "Service Nodes Awaiting Contributions" section on the Oxen block explorer.
Once the Service Node registration is received, you can send the <Service Node Public Key> to your contributors, along with the amount of $OXEN they are required to stake.
At this point, you'll need to wait until all contributors have staked before the Service Node activates and becomes eligible to begin receiving rewards.
Staking to a shared node as a contributor
For a guide on staking to a shared Oxen Service Node as a contributor, see here.
Step 6: Service Node status check
After you've staked to your Service Node (or after all contributors have staked, if you're running a shared node), you'll need to check if your Service Node's public key is on the list of Service Nodes which are operational on the network. This will prove that your Service Node is running, recognised, and eligible to receive rewards.
Connect to the VPS where the Service Node is running and run the following command to retrieve your Service Node's public key:
This will output a long string of letters and numbers: your Service Node's public key. This public key is used to identify your Service Node on the list of registered and operational Service Nodes. Select and copy the public key.
You can now jump onto oxen.observer, open the full list of active Service Nodes, and use Cmd+F/Ctrl+F to check if your Service Node's public key appears in the list.
Step 7: Unlocking your stake
Service Nodes will continually receive block rewards indefinitely until a stake is unlocked or the Service Node becomes deregistered. To unlock your stake, simply open the Oxen GUI Wallet and navigate to the Service Nodes > My Stakes tab. You can then click Unlock for any stake you wish to unlock:
You can also unlock your stake by running the following command from the Oxen Command Line Interface (CLI) Wallet:
The Service Node will expire 15 days (10800 blocks) after the unlock is requested, and your staked $OXEN will then become unlocked after expiry.
For pooled nodes, any contributor can submit an unlock request. This will schedule the Service Node for expiration. All locked stakes in that Service Node will be unlocked 15 days (10800 blocks) after the unlock is requested. Once an unlock is requested, this process can not be undone or prolonged. Service Node participants will continue receiving rewards until the node expires.
Deregistrations can be issued at any point during the active lifecycle of a Service Node, including during the period after requesting an unlock. Deregistration removes your Service Node from the network, and your stake(s) become locked and unspendable for 30 days (21600 blocks) from the block in which the Service Node was deregistered.
Receiving a deregistration after participant(s) have already requested an unlock overrides the 15-day (10800-block) stake unlock time, and sets the unlock time to 30 days (21600 blocks).
Keeping your binaries up to date
When a new release is available, upgrading is as simple as syncing with the repository:
Then installing updates using:
Note that this will install both updated
oxendpackages and any available system updates (this is generally a good thing!).
During the upgrade, all instances of oxend will be restarted if they are currently running in order to switch to the updated oxend.
If for some reason you want to install only Oxen package upgrades but not other system package updates, then instead of the sudo apt upgrade you can use:
Monitoring
We highly recommend setting up monitoring for your Service Node. This is as simple as calling on the services of our Telegram or Discord bot. Contact @OxenSNBot on Telegram or OxenSNBot#5812 on Discord and type /start or $help respectively to get started.
Another helpful tool is Konstantin Ullrich's Oxen Service Node Operator app for Android.
Back-ups
You should immediately make a back-up of your Service Node's secret key. This will allow you to recover from a disaster or to migrate your node to a different network service provider, should that prove necessary in the future.
The command to reveal the secret key is:
And the command to restore it is:
Alternatively, you can use a tool like scp to copy the file off-host for safekeeping.
Note that for older service nodes (installed before Oxen 8.x) the server will have two keys: the above, plus a legacy
/var/lib/oxen/key. You must additionally back up and restore this legacy key to restore such a service node, using:to show the key, and if you need to restore it (note the "legacy" added to the command):
If you are planning on unlocking and re-registering an older node with two keys, it is recommended to remove the legacy
/var/lib/oxen/keyafter the registration expires, restart the oxen/lokinet/storage server services, and then register using the new, single key: this will leave you with just one key to back up and restore. IMPORTANT: Never remove any keys on an active, registered service node!
Conclusion
Well done! Your Service Node is configured, operational, and will now begin receiving rewards.
For tips and tricks to maintain your Service Node, check out Service Node tools and upkeep.
Having trouble? Just head to our Support section.
Last updated
