Using Node Binary
As per instructions on the cloud guides, the host needs to open up port 9000 for blockchain consensus messages and port 6000 for blockchain state syncing. Other ports are NOT necessary for syncing and should NOT be opened to the internet if you are staking only.
  • 9000 port is used for blockchain consensus messages (base port)
  • 6000 port is used for blockchain state syncing (base port - 3000)
  • 9500 port is used for SDK RPC service (base port + 500)
  • 9800 port is used for Websocket service (base port + 800)
The 9500, 9800 ports are only listened by localhost 127.0.0.1 by default.

1. Download Node Binary

Before we proceed to next steps we need to download the node binary first:
x86_64 (Mainnet)
x86_64 (Testnet)
arm64 (Mainnet)
1
curl -LO https://harmony.one/binary && mv binary harmony && chmod +x harmony
Copied!
1
curl -LO https://harmony.one/binary_testnet && mv binary_testnet harmony && chmod +x harmony
Copied!
1
curl -LO https://harmony.one/binary-arm64 && mv binary-arm64 harmony && chmod +x harmony
Copied!
Check the node binary version that was downloaded:
1
./harmony -V
Copied!
The below explain the different method the node binary can be used. Option 1 is what being used when setting up systemd (at step 2).
If you choose another method make sure to use the correct command line
All the start options can be persisted and loaded from a single config file. To start a node, the following steps are also available**:**
  1. 1.
    Dump the default config.
  2. 2.
    Customize the config file.
  3. 3.
    Run harmony node with the config file.

Dump the Default Config File

Mainnet
Testnet
1
./harmony config dump harmony.conf
Copied!
1
./harmony config dump --network testnet harmony.conf
Copied!
A file harmony.conf is created and the default node options are set in the file in TOML formatting. Here is an example:
1
Version = "2.1.0"
2
​
3
[BLSKeys]
4
KMSConfigFile = ""
5
KMSConfigSrcType = "shared"
6
KMSEnabled = false
7
KeyDir = "./.hmy/blskeys"
8
KeyFiles = []
9
MaxKeys = 10
10
PassEnabled = true
11
PassFile = ""
12
PassSrcType = "auto"
13
SavePassphrase = false
14
​
15
[DNSSync]
16
Client = true
17
LegacySyncing = false
18
Port = 6000
19
Server = true
20
ServerPort = 6000
21
Zone = "t.hmny.io"
22
​
23
[General]
24
DataDir = "./"
25
IsArchival = false
26
IsBeaconArchival = false
27
IsOffline = false
28
NoStaking = false
29
NodeType = "validator"
30
ShardID = -1
31
​
32
[HTTP]
33
Enabled = true
34
IP = "127.0.0.1"
35
Port = 9500
36
RosettaEnabled = false
37
RosettaPort = 9700
38
​
39
[Log]
40
FileName = "harmony.log"
41
Folder = "./latest"
42
RotateSize = 100
43
Verbosity = 3
44
​
45
[Log.VerbosePrints]
46
Config = false
47
​
48
[Network]
49
BootNodes = ["/dnsaddr/bootstrap.t.hmny.io"]
50
NetworkType = "mainnet"
51
​
52
[P2P]
53
IP = "0.0.0.0"
54
KeyFile = "./.hmykey"
55
Port = 9000
56
​
57
[Pprof]
58
Enabled = false
59
ListenAddr = "127.0.0.1:6060"
60
​
61
[RPCOpt]
62
DebugEnabled = false
63
RateLimterEnabled = true
64
RequestsPerSecond = 1000
65
​
66
[Sync]
67
Concurrency = 6
68
DiscBatch = 8
69
DiscHardLowCap = 6
70
DiscHighCap = 128
71
DiscSoftLowCap = 8
72
Downloader = false
73
Enabled = false
74
InitStreams = 8
75
MinPeers = 6
76
​
77
[TxPool]
78
BlacklistFile = "./.hmy/blacklist.txt"
79
​
80
[WS]
81
Enabled = true
82
IP = "127.0.0.1"
83
Port = 9800
Copied!
The content of the config file can be modified for custom node start up command.
For example, to open the public HTTP RPCs, change the field IP under [HTTP] tag to "0.0.0.0":
1
[HTTP]
2
Enabled = true
3
IP = "0.0.0.0"
4
Port = 9500
5
RosettaEnabled = false
6
RosettaPort = 9700
Copied!
To run harmony internal nodes under legacy mode instead of staking mode, change the field NoStaking under [General] tag to true:
1
[General]
2
DataDir = "./"
3
IsArchival = false
4
IsBeaconArchival = false
5
IsOffline = false
6
NoStaking = true
7
NodeType = "validator"
8
ShardID = -1
Copied!
To enable streamsync, modify the below two sections (Experimental)
Testnet
1
[DNSSync]
2
Client = false
3
LegacySyncing = false
4
Port = 6000
5
Server = true
6
ServerPort = 6000
7
Zone = "b.hmny.io"
8
9
[Sync]
10
Concurrency = 4
11
DiscBatch = 8
12
DiscHardLowCap = 4
13
DiscHighCap = 1024
14
DiscSoftLowCap = 4
15
Downloader = true
16
InitStreams = 4
17
MinPeers = 4
Copied!
Stream Sync is the new harmony Syncing method allowing to get rid of the previous sync via DNS causing issue when the DNS node wasn't in sync.

Start the node with Config File

Harmony node binary is able to start with options provided by the config file:
1
./harmony -c harmony.conf
Copied!
The values stored in the config file will be read and parsed to harmony as node start options.

Option 2: Setup Using Flag Parsing

You can run your node binary using flag parsing:
Mainnet
Testnet
1
./harmony
Copied!
1
./harmony --network testnet
Copied!
A full list of active flags as well as examples can be accessed through running the binary with --help option:
1
./harmony --help
Copied!
Output:
1
Examples usage:
2
​
3
# start a validator node with default bls folder (default bls key files in ./.hmy/blskeys)
4
./harmony
5
​
6
# start a validator node with customized bls key folder
7
./harmony --bls.dir [bls_folder]
8
​
9
# start a validator node with open RPC endpoints and customized ports
10
./harmony --http.ip=0.0.0.0 --http.port=[http_port] --ws.ip=0.0.0.0 --ws.port=[ws_port]
11
​
12
# start an explorer node
13
./harmony --run=explorer --run.archive --run.shard=[shard_id]
14
​
15
# start a harmony internal node on testnet
16
./harmony --run.legacy --network
17
18
Usage:
19
harmony [flags]
20
harmony [command]
21
​
22
Available Commands:
23
dumpconfig dump the config file for harmony binary configurations
24
help Help about any command
25
version print version of the harmony binary
26
​
27
Flags:
28
--bls.dir string directory for BLS keys (default "./.hmy/blskeys")
29
--bls.keys strings a list of BLS key files (separated by ,)
30
--bls.kms enable BLS key decryption with AWS KMS service (default true)
31
--bls.kms.config string json config file for KMS service (region and credentials)
32
--bls.kms.src string the AWS config source (region and credentials) for KMS service (shared, prompt, file) (default "shared")
33
--bls.pass enable BLS key decryption with passphrase (default true)
34
--bls.pass.file string the pass file used for BLS decryption. If specified, this pass file will be used for all BLS keys
35
--bls.pass.save after input the BLS passphrase from console, whether to persist the input passphrases in .pass file
36
--bls.pass.src string source for BLS passphrase (auto, file, prompt) (default "auto")
37
--bootnodes strings a list of bootnode multiaddress (delimited by ,)
38
-c, --config string load node config from the config toml file.
39
--datadir string directory of chain database (default "./")
40
--dns.port int port of customized dns node (default 9000)
41
--dns.zone string use customized peers from the zone for state syncing
42
-h, --help help for harmony
43
--http enable HTTP / RPC requests (default true)
44
--http.ip string ip address to listen for RPC calls. Use 0.0.0.0 for public endpoint (default "127.0.0.1")
45
--http.port int rpc port to listen for HTTP requests (default 9500)
46
--log.dir string directory path to put rotation logs (default "./latest")
47
--log.max-size int rotation log size in megabytes (default 100)
48
--log.name string log file name (e.g. harmony.log) (default "harmony.log")
49
-v, --log.verb int logging verbosity: 0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail (default 3)
50
-n, --network string network to join (mainnet, testnet, pangaea, localnet, partner, stressnet, devnet) (default "mainnet")
51
--p2p.keyfile string the p2p key file of the harmony node (default "./.hmykey")
52
--p2p.port int port to listen for p2p protocols (default 9000)
53
--pprof enable pprof profiling
54
--pprof.addr string listen address for pprof (default "127.0.0.1:6060")
55
--run string run node type (validator, explorer) (default "validator")
56
--run.archive run node in archive mode
57
--run.legacy whether to run node in legacy mode
58
--run.shard int run node on the given shard ID (-1 automatically configured by BLS keys) (default -1)
59
--txpool.blacklist string file of blacklisted wallet addresses (default "./.hmy/blacklist.txt")
60
-V, --version display version info
61
--ws enable websocket endpoint (default true)
62
--ws.ip string ip endpoint for websocket. Use 0.0.0.0 for public endpoint (default "127.0.0.1")
63
--ws.port int port for websocket endpoint (default 9800)
64
​
65
Use "harmony [command] --help" for more information about a command.
Copied!

Option 3: Setup Using Flag Parsing and a Config file combined

If both config file and flag is provided, the node option stored in config file will be override by the values given in flag.
For example, In config file harmony.conf, HTTP server is enabled, and is open to public:
1
[HTTP]
2
Enabled = true
3
IP = "0.0.0.0"
4
Port = 9500
5
RosettaEnabled = false
6
RosettaPort = 9700
Copied!
And a flag is also provided during the node start command to disable the HTTP server:
1
./harmony -c harmony.conf --http=false
Copied!
In this case, the command line flags will override the settings in the config file and thus the HTTP server is disabled.
1
> curl localhost:9500
2
curl: (7) Failed to connect to localhost port 9500: Connection refused
Copied!
The above steps would have you started the node, please CTRL+C, so you can continue with step 2.

Non-Validating/Explorer Nodes

A Non-validating Node is a node that runs in archival mode and does not join the consensus.
Check here for Explorer Node requirements.
Check here for instructions on how to sync your node in archival mode.
Keep in mind that the storage space used increases around ~50+ GB per month on s0 due to staking transaction being stored. Other shard should take around 25GB per month. Please plan your storage space accordingly.
The following steps assume the node is connected to mainnet on shard 0, which is required for all exchanges.
If you are using the config file, which is the recommended way to configure your node, change the settings to the ones below:
1
[General]
2
DataDir = "./"
3
IsArchival = true
4
IsBeaconArchival = false
5
IsOffline = false
6
NoStaking = true
7
NodeType = "explorer"
8
ShardID = 0
Copied!
NoStaking = true will verify if the BLS keys in your .hmy/blskeys folder are part of the original FN keys. You will need add in the folder dummy empty files and remove all others
1
# remove all keys, save it before if necessary
2
rm -f .hmy/blskeys/*
3
# create dummy files
4
touch .hmy/blskeys/bls.key
5
touch .hmy/blskeys/bls.pass
Copied!
IsBeaconArchival flag is applicable to explorer node only. For shard 1/2/3 the beacon shard 0 doesn't need to be in archival mode. So to save space, the recommendation is to set to false. For shard 0 explorer node, IsArchival flag will determine if the database is in archival mode or not.
DataDir (or --db_dir below for cli flag) is the folder where the blockchain data will be store (ie location of harmony_db_0)
Alternatively, you can also run it using flag parsing:
1
./harmony --run=explorer --run.archive --run.shard=0 --db_dir=./
Copied!
Make sure to follow the upgrading Explorer DB schema process here afterwards. This fixes a critical issue on Explorer DB.

2. Setup Systemd

On this example, we will be installing the harmony daemon for user harmony on its home directory. Daemon will be configured with sudobut it will run with the harmonyuser at the end.
Create the harmony.service file:
1
sudo vi /etc/systemd/system/harmony.service
Copied!
Add the content below to the file and save it. Change User to the local user you will be running the daemon and also WorkingDirectory to the home directory where you downloaded the harmony binary file previously. Parameter ExecStart needs to point to this same directory. On the example below we will be running the harmony binary using the harmony.conf file.
1
[Unit]
2
Description=Harmony daemon
3
After=network-online.target
4
​
5
[Service]
6
Type=simple
7
Restart=always
8
RestartSec=1
9
User=harmony
10
WorkingDirectory=/home/harmony
11
ExecStart=/home/harmony/harmony -c harmony.conf
12
SyslogIdentifier=harmony
13
StartLimitInterval=0
14
LimitNOFILE=65536
15
LimitNPROC=65536
16
​
17
[Install]
18
WantedBy=multi-user.target
Copied!
Give the necessary permissions to run the daemon service, enable it and start it:
1
sudo chmod 755 /etc/systemd/system/harmony.service
2
sudo systemctl enable harmony.service
3
sudo service harmony start
Copied!
If you want to check the status of the daemon you can use:
1
sudo service harmony status
Copied!
To restart, or stop the service daemon you can run:
Restart
Stop
1
sudo service harmony restart
Copied!
1
sudo service harmony stop
Copied!
To check your node follow instructions on Checking A Node.