ARK Core cheatsheet
A curated list with useful commands, links and answers to common issues / questions for delegates and relay node operators
- Node Configuration
- Common Issues / FAQ
- Useful Links
Install and enable the latest security patches and updates:
sudo apt-get update -y sudo apt-get upgrade -y sudo reboot
Fresh ARK Core 2.2 Install
For a fresh installation of Core 2.2, you can read the instructions in the official ARK docs. In short, it comes down to running the following commands:
adduser ark usermod -aG sudo ark su ark cd ~ bash <(curl -s https://raw.githubusercontent.com/ArkEcosystem/core/master/install.sh)
Depending on your server provider, you can often configure an SSH key in their web portal. That is the most convenient way, as your SSH key will then be available on any server you create with them. If you don't have this option, or want to set it up manually anyway, read on.
Make your life easier by whitelisting your ssh key so you can login without a password
- Copy the ssh key from your local machine to your clipboard, this differs per OS.
- On your server, go into the
~/.sshfolder (create it if it doesn't exist)
nano authorized_keys(this will create the file if it didn't exist yet)
- Paste the key you copied in step 1. in this file
- Exit the editor by pressing
ctrl + xfollowed by
yto save your changes
- Important: keep your current commandline session open and try connecting to your server in a new screen. You should be able to login by simply typing
ssh <username>@<server ip>and it should no longer prompt for a password.
You can add aliases to your
~/.bashrc file for commands you often run. In order to do this, simply run
nano ~/.bashrc and add an alias. Afterwards, save and exit the file and enable the changes by running
source ~/.bashrc, or by logging out and logging in to your server.
alias pm2rl="pm2 restart all && pm2 logs" # Restart the core processes and open the logs afterward alias editpl="nano ~/.config/ark-core/mainnet/plugins.js" # Open the `plugins.js` file where you can find and add plugins alias editdel="nano ~/.config/ark-core/mainnet/delegates.json" # Open the `delegates.json` file where you can find your delegate passphrase alias cdsnaps="cd ~/.local/share/ark-core/mainnet/snapshots/" # Navigates to the snapshot folder
Note that the above location commands use
mainnet by default. If you are on
testnet instead, you need to replace
mainnet with the network you use.
It's recommended that you setup additional security measurements for your node. Some options are explained in the official ark docs, which include:
- Changing SSH port and other config tweaks
- Installing Fail2ban
- Port Knocking
- Cloudflare DDOS protection
This is a good basis to have on your server, but you are free to look for other ways to secure it too.
Plugins / Scripts
Some useful core plugins / scripts that you can install on your server:
- Vanir - an easy way to self-forge your delegate payout transactions
- Hermod - a monitoring and automatic snapshot tool to keep track of your server and to easily keep snapshots
- Core Control - an alternative to the official ARK Cli, with additional features
There are also a couple options for TBW scripts:
You can find a
.env file in
$HOME/.config/ark-core/$network/.env in which you can make changes regarding the default core plugins.
Alternatively, you can run
ark env:list to show what is currently set in the
The most interesting environment options will be highlighted here:
CORE_LOG_LEVEL=<level>, you can change this to your preferred log level (e.g.
info, etc.). This can also be achieved through the CLI by running
ark env:set CORE_LOG_LEVEL <level>
CORE_DB_PASSWORD, these values are used by core to log in to your local database. If you are having issues with accessing the database, you can change those entries as they default to user
password, which might not be the actual values used on your server.
It is recommended to keep a list of snapshots in case of issues with your node. As snapshots are no longer provided by the ARK team, it's your own responsibility to create and maintain them. You can easily keep a list of snapshots by installing Hermod, or check below how you can create them manually.
Creating a Snapshot
A snapshot can be created with
ark snapshot:dump. The full list of options can be found in the official ARK snapshot docs. In most cases, it will suffice to use the following command:
ark snapshot:dump --network="mainnet"
Restoring from a Snapshot
A snapshot can be restored with
ark snapshot:restore. The full list of options can be found in the official ARK snapshot docs. In most cases, it will suffice to use the following command:
ark snapshot:restore --network="mainnet"
In case your node gets stuck, it can in some cases suffice to rollback a couple blocks before the issue surfaced and let it sync with the network from there. This can be done with the following command:
ark snapshot:rollback --network=NETWORK --height=HEIGHT
HEIGHT is a number indicating the blockheight to which you want to roll back. If you want to go back to height
mainnet, the command will look like this:
ark snapshot:rollback --network="mainnet" --height=7700000
You can also make a database dump instead of a snapshot. The following command will dump your
ark_mainnet database to a file called
pg_dump -Fc ark_mainnet > snapshot_latest
To import the database dump, you need to run the following commands:
dropdb ark_mainnet # or ark_devnet createdb ark_mainnet # or ark_devnet wget <snapshot url> # fetch the snapshot, not needed if you already have it somewhere locally pg_restore -n public -O -j 8 -d ark_mainnet <snapshot> # where <snapshot> points to the location + name of the snapshot file
Sharing a Snapshot
In case you need to share a snapshot between server (e.g. your forger was formatted and you want to get a snapshot from your relay), there is an easy method involving Http Server.
- Install Http Server on the server you have your snapshots on:
npm install http-server -g
- You can now serve any folder by running
http-server [path] [options]. In case of snapshots, you can for example do the following:
cdsnaps # Alias, otherwise use cd ~/.local/share/ark-core/<network>/snapshots/ http-server ./
- Download your snapshot from another server through
wgetor something similar.
Note: the default port used is
8080, so if you have a firewall running you need to make sure that the port is open!
Protip: you can make it easier to download a snapshot by tar'ing it, as that will combine the snapshot folder into a single file.
cdsnaps # Combine a snapshot folder into a single file, make sure to rename mySnapshotFolder to the actual name of the snapshot folder tar cvf mySnapshotFolder.tar mySnapshotFolder
On the receiving server you can then extract the tar by running
tar -xvf mySnapshotFolder.tar
Core File Locations
Core v2 gets installed globally through
yarn and can be found in the following location:
There are multiple locations that are used by core to store specific config or data:
CORE_PATH_DATA=$HOME/.local/share/ark-core/$network CORE_PATH_CONFIG=$HOME/.config/ark-core/$network CORE_PATH_CACHE=$HOME/.cache/ark-core/$network CORE_PATH_LOG=$HOME/.local/state/ark-core/$network CORE_PATH_TEMP=/tmp/$USER/ark-core/$network cache => $HOME/.cache/ark-core/$network config => $HOME/.config/ark-core/$network database => $HOME/.local/share/ark-core/$network/database .env => $HOME/.config/ark-core/$network/.env logs => $HOME/.local/state/ark-core/$network/logs snapshots => $HOME/.local/share/ark-core/$network/snapshots temp => /tmp/$USER/ark-core/$network
In the above paths,
$network needs to be replaced by
testnet, depending on which network you currently are
Disabling API Ratelimit
If you run into API Ratelimit issues on your node, you can disable it (or whitelist the IP that needs access). Disabling is done by adding
CORE_API_RATE_LIMIT=false to your
You can limit access to the public api on your node by whitelisting IPs.
By default, the whitelist consists of
*, which means that everyone can access it.
When you want to change it to just your server, you can remove the
* and fill in the IP(s) that you allow.
The whitelist can be found in the
~/.config/ark-core/mainnet/plugins.js file, under
Don't forget to restart your relay afterwards.
Getting logs from server
You can fetch logs from your remove server through
scp. Note that you need to replace
Download the full log directory to your current directory:
scp -r username@server:~/.local/state/ark-core/$network/ .
Download a single log file to your current directory
scp username@server:~/.local/state/ark-core/$network/2019-03-11.log . # Change the filename to the correct date
If you use a different ssh port than the default
22, you can run the above commands with
scp -P $port instead, where
$port is the port number you use.
Common Issues / FAQ
Removing Processes from PM2
You can remove a process from PM2 by running
pm2 delete ID if you want to remove a specific process, or
pm2 delete all if you want to remove everything.
The ID of a process can be retrieved by running
pm2 list, as it will show the ID next to the name of the process.
If you don't see the ID, try increasing the size of your terminal window and running
pm2 list again.
Process Showing Errored
When you try to start the relay / forger and you see
errored when running
pm2 list, it means that the process could not be started successfully.
In that case, you should take a look at the logs (
pm2 logs) as that should indicate why it was not able to start.
Cannot find module ...
If you run into an error indicating
Error: Cannot find module '...', it most likely means that you have a no longer supported plugin, or an incorrect plugin, added in your
The followup line in that case would be
To solve it, you simply have to edit your
plugins.js file and remove / change the module it showed in the error message.
If you see something else directly below the error, not related to the
PluginRegistrar, it can also mean that a package is not correctly installed.
The "..." process has entered an unknown state
This often indicates an issue with PM2 itself.
Most likely you'll be able to resolve it by running
If it still gives the error after updating, run
pm2 kill and start the processes again.
- ARK CLI Docs
- Creating Plugins
- ARK Core Docs
- Migrating v2.1 to v2.2
- Installing v2.2 from scratch
If you have any suggestions / improvements for this cheatsheet, feel free to open a PR or an issue to get it added!