DevNews: Google Cloud 101 — Basic Configuration for Validator Nodes

In this new series of DevNews articles, we’re going to be covering some basic configurations for the three main Cloud platforms: AWS, Google Cloud and Microsoft Azure. We’ll spin up a full node, connect it to the network and turn the full node into a Validator node.

This second article introduces a very simple “quick start” single Google Cloud (GC) VM instance, using a simple network infrastructure. Validator node operators are highly encouraged to explore more sophisticated architecture configurations to increase the security, reliability and availability of their Validator node — for example, multi layered network with both private/public subnets, one or more “sentry” full (non-validator) nodes placed in front of your main (hidden and private) Validator node to handle and relay communication from the outside world, and reverse proxy for any RPC access via the sentries etc. in addition to investigating implementing hardware KMS solutions to protect validator private keys.

This guide should not be considered the default, full, out of the box solution for a Validator node, but more an “Google Cloud 101” guide to familiarise the reader with the core concepts involved in setting up the minimum Google Cloud Linux VM instance and associated service requirements in order to operate a UND Validator node. It should be considered a starting point giving you the building blocks from which to build a more sophisticated network/node architecture to support and protect your Validator node.

Please note: any public IPs generated by Google Cloud during this guide are not static — they will change if the VM instance is restarted. It is recommended that the reader also investigates GC static IPs for their public-facing node(s).

Where the guide prompts users to open a terminal, Windows 10 users should use PowerShell.

This guide assumes the reader already has a Google Cloud account.

Part 0: Create a new Project & Enable APIs

If you do not have an existing project for the node, you’ll need to create a new GC project. Click on the menu icon in the top left of the GC console, and select “Home” followed by “Create new project”. Give the project a suitable name, check it is in the correct organisation and click “Create”.

Once created, in the organisation/project drop-down (top-left of the console in the header), select your new project name.

Next, go to “Menu” and click on “APIs & Services”. Click the “Enable APIs and Services” button. From the filter menu on the left, select “Compute”, then enable billing for “Compute Engine API”.

Part 1: Create an SSH key pair

An SSH key is required to log in to your GC VM — this can be created on your local PC, using the ssh-keygen command.

Open a terminal on your local PC, and check if you have a $HOME/.ssh directory:

$ ls -la $HOME/.ssh

If you do not have a $HOME/.ssh directory, create it:

$ mkdir $HOME/.ssh
$ chmod 700 $HOME/.ssh

Run the following commands, replacing vmusername with something easily identifiable such as the admin username (only letters, no spaces) you will choose later in the guide for the VM, and enter a password to encrypt the key when prompted to do so:

$ ssh-keygen -t rsa -b 4096 -f $HOME/.ssh/gc_vmusername_id_rsa
$ chmod 400 $HOME/.ssh/gc_vmusername_id_rsa

Finally, the public key will be required later in the guide, so open it up in a text editor. The public key counterpart has the .pub file extension, e.g. $HOME/.ssh/gc_vmusername_id_rsa.pub

Part 2: VPC Network & Firewall rules

We first need to create a VPC and define some firewall rules that will allow your node to communicate via P2P, and allow you to broadcast transactions to your node. Validator operators are encouraged to explore more sophisticated configurations for their production node, and not just rely on the defaults.

2.1: Create a VPC

From the Google Cloud console menu, scroll down to “VPC Network” and click “VPC Networks”. Click the “Create VPC Network” button.

  1. Enter a suitable name for the VPC, such as “und-vpc”, and a description.
  2. For “Subnets”, select “Automatic”.
  3. Don’t select any of the predefined firewall rules.
  4. Leave the rest as defaults, and click the “Create” button.

2.2: Firewall Rules

First, we need a firewall rule that allows only your local PC’s IP address to connect via SSH. You can find your IP address by running ifconfig in a terminal, or visiting https://www.whatismyip.com. Note: if your PC’s IP changes, you will need to update this rule in order to connect to your VM.

  1. Click the Menu button in the top left of the GC console, scroll down to “VPC Network” and click “Firewall Rules”. Click the “Create Firewall Rule” button.
  2. Enter a name for the rule, such as “und-node-ssh”, and suitable description.
  3. Change the value for “Network” from “default” to “und-vpc” (or whatever you called your VPC Network).
  4. For “direction of traffic”, select “Ingres” and for “Action on Match”, select “Allow”
  5. For “Targets”, select “Specified Target Tag”, and enter “und-node” under “Target Tags” (this will be used as the “network tag” when creating the VM instance later).
  6. For “Source IP Ranges”, enter YOUR_IP/32, for example 22.33.44.55/32
  7. Under “Protocols and Ports”, select “specified protocols and ports”, tick “tcp” and enter 22 as the port
  8. Click “Create”

Next, we need a firewall rule that allows the node to communicate via P2P. Click the “Create Firewall Rule” button.

  1. Enter a name for the rule, such as “und-node-p2p”, and suitable description.
  2. Leave logs “off”.
  3. Change the value for “Network” from “default” to “und-vpc” (or whatever you called your VPC Network)
  4. For “direction of traffic”, select “Ingres” and for “Action on Match”, select “Allow”
  5. For “Targets”, select “Specified Target Tag”, and enter “und-node” under “Target Tags” (this will be used as the “network tag” when creating the VM instance later).
  6. For “Source IP Ranges”, enter 0.0.0.0/0
  7. Under “Protocols and Ports”, select “specified protocols and ports”, tick “tcp” and enter 26656 as the port
  8. Click “Create”.

Next, we need to open the RPC port, so that we can broadcast Txs to the node. As with the SSH rule, we should restrict access to our own IP.

Repeat the steps above. Use “und-node-rpc” as the name, and your_IP/32 (e.g. 22.33.44.55/32) as the IP range. Finally, tick “tcp” and enter 26657 as the port. As before, enter “und-node” under “Target Tags”, ensure you select “und-vpc” as the network, and click “Create”.

Note: port 26657 can be closed on your Validator node once you have registered your validator.

Part 3: Create a VM Instance

To begin, ensure that billing for Compute Engine API is enabled for the current project. You will also need the public key for the SSH key created earlier.

We’ll now create a VM for the node.

  1. Click the Navigation Menu icon in the top left of the GC console, and go to Compute -> Compute Engine -> VM Instances. Click the “Create” button.
  2. Give your VM instance a suitable name.
  3. Under “Machine Configuration”, leave “General purpose” selected, along with “E2” for Series.
  4. For “Machine Type”, select “e2-small
  5. In the “Boot Disk” section click the “Change” button
  6. Select “CentOS” as the operating system, and “CentOS 7” as the version
  7. Leave the disk size as default, and select “SSD Persistent Disk” as the Boot Disk Type. Click the “Select” button.
  8. Click the “Management, security, disks, networking, sole-tenancy” link (under “Firewall”).
  9. Click the “Security” tab.
  10. Copy your SSH public key into the input “Enter public SSH key”. Note: your public key will be in the format: ssh-rsa PUBLIC_KEY username@host. The “username@host” part will be used to define the admin username for the VM, e.g. ssh-rsa PUBLIC_KEY vmusername@host
  11. Click the “Networking” tab.
  12. Enter “und-node” in the “Network tags” input (this is the tag we selected to apply our firewall rules to earlier).
  13. Click the “Network Interface” option, and change the Network from “default” to “und-vpc” (or whatever you named your VPC earlier).
  14. Click the “Disks” tab, and click the “Add New Disk” button.
  15. Leave the rest of the options as their defaults, and click the “Create” button.

Part 4: Log in to VM and configure via SSH

Once back on the Instances dashboard, you should see your new VM Instance listed. Find your instance, and make a note of the public IP address.

Note: any bold_text in the following commands should be replaced with your own values. For example, vmusername should be replaced with the administrator username entered when creating the VM in Part 3.

Note for Windows users: Windows 10 should have an SSH client available in the PowerShell terminal. Older Windows versions will require PuTTY.

Open a terminal on your PC, and run:

$ ssh -i $HOME/.ssh/gc_vmusername_id_rsa vmusername@vm_ip

Part 4.1: Install the prerequisites, and mount the drive

Update the installed packages:

$ sudo yum update -y

Install the following additional software:

$ sudo yum install nano jq -y

Follow Google’s guide for “formatting and mounting a zonal persistent disk”, and use /mnt/disks/data as the mount point

Part 4.2: Install the und binary

We have a shell script available in the mainchain GitHub repository which will automatically download and install the latest version of und. While still logged in to the VM instance via SSH, run the following:

$ sh -c "$(curl -sfSL https://git.io/JvHZO)"

This should install the binary into /usr/local/bin/und. Verify the installation was successful:

$ which und

should output:

/usr/local/bin/und

and:

$ und version --long

should output something similar to:

name: UndMainchain
server_name: und
client_name: undcli
version: 1.4.2
commit: 72bd43882a2d8142649ff1faab2956ca2b627009
build_tags: netgo ledger
go: go version go1.13.3 linux/amd64

Part 5: Initialising your full node

We’ll now initialise and configure the und node itself. As previously, any bold_text in the following commands should be replaced with your own values accordingly. If you are not currently logged in to the VM instance via SSH, do so.

Once logged in, run:

$ und init your_node_tag --home=/mnt/disks/data/.und_mainchain

your_node_tag can be any ID you like but is restricted to ASCII characters. If you have used anything other than /mnt/disks/data as your data disk mount point, change the--home flag to reflect this.

IMPORTANT: There is a known issue with the syncable pruning option in the Cosmos SDK. Since pruning = “syncable” is the default value when und init is run, it is recommended to set the value to either pruning = “everything" or pruning = “nothing" in $HOME/.und_mainchain/config/app.toml. Note that setting to pruning = “nothing”will increase storage usage considerably.

Download the latest Genesis file. The following command downloads the latest UND-Mainchain-TestNet genesis. Command is all one line:

$ curl https://raw.githubusercontent.com/unification-com/testnet/master/latest/genesis.json > /mnt/disks/data/.und_mainchain/config/genesis.json

Get the current chain ID from genesis. Make a note of the output, it’ll be required in commands later in the guide. Command is all on one line:

$ jq --raw-output '.chain_id' /mnt/disks/data/.und_mainchain/config/genesis.json

Next, we need the seed node info. This will allow your node to bootstrap some initial peers and connect to the network. Go to https://github.com/unification-com/testnet/blob/master/latest/seed_nodes.md and copy one or more of the seed nodes (you need the id@address:port)

Edit your node configuration file using nano:

$ nano /mnt/disks/data/.und_mainchain/config/config.toml

Hit Ctrl+Alt+W, type [p2p](including the square brackets) and hit return — this will take you to the[p2p]section of the config file, which begins with:

##### peer to peer configuration options #####
[p2p]

Find the external_address = “” variable about 9 lines below, and set it to your vm_ip:26656 e.g.:

external_address = "11.22.33.44:26656"

Find the seeds = “” variable about 12 lines below, and add the seed node information between the double quotes (comma separated, no spaces if more than one). For example:

seeds = "node_id@ip:port"

Next, hit Ctrl+Alt+W, type [rpc](including the square brackets) and hit return — this will take you to the[rpc]section of the config file, which begins with:

##### rpc server configuration options #####
[rpc]

About 3 lines under this, find:

laddr = "tcp://127.0.0.1:26657"

Change the value to:

laddr = "tcp://0.0.0.0:26657"

Hit Ctrl+X followed by y and then return to save the file and exit nano.

Note: you can revert the [rpc] configuration for port 26657 to:

laddr = “tcp://127.0.0.1:26657”

once you have run the create-validator command. Broadcasting transactions can instead be done via a public RPC node, or, more securely, via a full node running on your local PC. See Part 8: Final cleanup for further details.

Gas Prices & Pruning

It is good practice to set the minimum-gas-prices value in /mnt/disks/data/.und_mainchain/config/app.toml , in order to protect your full node from spam transactions. This should be set as a decimal value in nund, and the recommended value is currently 0.25nund. This means your node will ignore any Txs with a gas price below this value. To do so, open up /mnt/disks/data/.und_mainchain/config/app.toml in a text editor, and set minimum-gas-prices

$ nano /mnt/disks/data/.und_mainchain/config/app.toml

Change:

minimum-gas-prices = ""

To, for example:

minimum-gas-prices = "0.25nund"

Also, modify the pruning setting at the end of the file.

Change:

pruning = "syncable"

To:

pruning = "everything"

Hit Ctrl+X followed by y and then return to save the file and exit nano.

Finally, check that your node can connect to and sync with the network:

$ und start

The following output just means that the seed node has sent its peer address data to your node, and closed its connection:

E[2020-03-19|09:42:06.072] Stopping peer for error                      module=p2p peer="Peer{MConn{1.2.3.4:26656} dcff5de69dcc170b28b6628a1336d420f7eb60c0 out}" err=EOF

After a few seconds, you should see your node start downloading the blocks.

Hit Ctrl+C to stop the node — it will be configured as a background service next.

======================================= IMPORTANT: keep your /mnt/disks/data/.und_mainchain/config/node_key.json and /mnt/disks/data/.und_mainchain/config/priv_validator_key.json files safe! These are required for your node to propose and sign blocks. If you ever migrate your node to a different host/VM instance, you will need these. =======================================

Part 6: Running und as a daemon

Once you have initialised and tested the und node, it can be set up as a background daemon on the server using systemctl. This means that you can easily start/stop/restart the service, and do not need to leave the SSH session open while und is running.

If you’re not logged in to your VM instance via SSH, log in. If you are still logged in, and have not stopped the und node, hit Ctrl+C to stop the node.

We need to use the nano text editor to create the service configuration. Run:

$ sudo nano /etc/systemd/system/und.service

Add the following as a minimum, replacing vmusername with the administrator username entered when creating the VM in Part 3.:

[Unit]
Description=Unification Mainchain Validator Node
[Service]
User=vmusername
Group=vmusername
WorkingDirectory=/mnt/disks/data
ExecStart=/usr/local/bin/und start --home=/mnt/disks/data/.und_mainchain
[Install]
WantedBy=default.target

Note: the ExecStart= is all one line.

Hit Ctrl+X followed by y and then return to save the file and exit nano.

Run:

$ sudo systemctl daemon-reload

to update systemctl

You can now start and stop the und daemon in the background using:

$ sudo systemctl start und
$ sudo systemctl stop und

Finally, you can monitor the log output for the service by running:

$ sudo journalctl -u und --follow

and use Ctrl+C to exit the journalctl command. You can now log out of your SSH session and und will continue running in the background.

Part 7: Become a Validator

Important: ensure your node has fully synced with the network before continuing.

If not already logged in, log in to your VM instance via SSH, and run:

$ sudo journalctl -u und --follow

Once fully synced (check the downloaded height against the current clock in the block explorer), hit Ctrl+C to quit the journalctl command.

You will need your Validator node’s Tendermint public key in order to register it on the Mainchain network as a validator. Whilst still in the SSH session connected to your VM, run:

$ und tendermint show-validator --home=/mnt/disks/data/.und_mainchain

Make a note of the output, as you will need this in later commands, where it will be referred to as your_validator_public_key.

You can now exit the SSH session — the rest of the commands will be run in a terminal on your local PC.

Go to https://github.com/unification-com/mainchain/releases/latest and download the undcli archive for your OS — for example, undcli_v1.4.3_windows_x86_64.tar.gz. You do not need to download the und archive. Extract the archive to a suitable location.

Open a terminal/PowerShell, and cd into the directory where you extracted the undcli executable:

$ cd path/to/extracted/undcli_directory

As previously, any bold_text in the following commands should be replaced with your own values accordingly.

If you do not already have a wallet/account, you can create one (on your local PC) by running:

$ ./undcli keys add account_name

If you already have a wallet, you can import the account using:

$ ./undcli keys add account_name --recover

in which case, you will be prompted for the mnemonic and a password to secure the wallet.

From here, it is assumed the reader has an account with sufficient UND from which to self-delegate to their Validator node.

On your local PC, run the following command, replacing any bold_text accordingly with your own values:

./undcli tx staking create-validator \
--amount=stake_in_nund \
--pubkey=your_validator_public_key \
--moniker="your_ev_moniker" \
--website="your_website" \
--details="description" \
--security-contact="security_email" \
--chain-id=chain_id \
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=account_name \
--node=tcp://vm_ip:26657 \
--broadcast-mode block \
--trust-node false

stake_in_nund = (required) the amount of UND in nund you are self-delegating. You can use the undcli convert 1000 und nund command to convert UND to nund. E.g. 1000000000000nund. Note: do not enter more nund than you have in your wallet!

your_validator_public_key = (required) the public key output from the previous und tendermint show-validator command.

your_ev_moniker = (required) a publicly visible ID/tag for your Validator node.

your_website = (optional) website promoting your node

description = (optional) short description of your node

security_email = (optional) security contact for your organisation

chain_id = the network (e.g. UND-Mainchain-TestNet-v3) you are creating a validator on — this was obtained earlier in the guide via the jq command

account_name = the account self-delegating the UND, previously created/imported with the undcli keys add command

vm_ip = the IP address of your VM instance running the full node — you can get this from your GC VM Instances console.

Commission Rates

Your commission rates can be set using the --commission-rate , --commission-max-change-rate and --commission-max-rate flags.

--commission-rate: The % commission you will earn from delegators’ rewards. Keeping this low can attract more delegators to your node.

--commission-max-rate: The maximum you will ever increase your commission rate to — you cannot raise commission above this value. Again, keeping this low can attract more delegators.

--commission-max-change-rate: The maximum you can change the commission-rate by in any one change request. For example, if your maximum change rate is 0.01, you can only make changes in 0.01 increments, so from 0.10 (10%) to 0.09 (9%).

The values for --commission-max-change-rate and --commission-max-rate flags cannot be changed after the create-validator command has been run.

Finally, the --min-self-delegation flag is the minimum amount of nund you are required to keep self-delegated to your validtor, meaning you must always have at least this amount self-delegated to your node.

For example:

./undcli tx staking create-validator \
--amount=1000000000000nund \
--pubkey=undvalconspub1zcjduepq6yq7drzefkavsrxhxk69cy63tj3r... \
--moniker="MyAwesomeNode" \
--website="https://my-node-site.com" \
--details="My node is awesome" \
--security-contact="security@my-node-site.com" \
--chain-id=UND-Mainchain-TestNet-v3 \
--commission-rate="0.05" \
--commission-max-rate="0.10" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--gas="auto" \
--gas-prices="0.25nund" \
--gas-adjustment=1.5 \
--from=my_new_wallet \
--node=tcp://33.44.55.66:26657 \
--broadcast-mode block \
--trust-node false

Your validator node should now be registered and contributing to the network. To verify, on you local PC, run the following:

./undcli query staking validator \
$(undcli keys show account_name --bech=val -a) \
--chain-id=chain_id \
--node=tcp://vm_ip:26657

Replacing account_name, chain_id and vm_ip accordingly. Assuming you are going through this guide on TestNet, you should also see your node listed in https://explorer-testnet.unification.io/validators

Part 8: Final cleanup

Finally, it’s a good idea to close the RPC port (26657) on your validator node, leaving only the P2P port (26656) open so that it can communicate with other nodes. This can be done by deleting the firewall rule for the RPC port, and by reverting the RPC laddr configuration value in config.toml to the 127.0.0.1 IP address (which will restrict the node’s RPC access to localhost). Further interaction with the network can be done by spinning up a separate non-validator full node (on your local PC for example), and broadcasting transactions via that node instead.

Important: Do not alter the P2P port (26656) configuration and firewall rules. If you do, your validator node will not be able to communicate with its peers.

That’s it — you should now have a full Validator node up and running on a very basic Google Cloud Linux VM instance. Once again — Validator node operators are highly encouraged to explore more sophisticated architecture configurations to increase the security, reliability and availability of their Validator node.

Further commands relating to Validator Operators can be found in our “DevNews: Running a Full Node and Becoming a Validator” article.

Web: unification.com
Telegram: https://t.me/unificationfoundation
Twitter: https://twitter.com/UnificationUND
Gitter: https://gitter.im/unification-com

Tech issues related to und and undcli can be raised in the Github repo: https://github.com/unification-com/mainchain/issues

As always, feel free to track our overall progress — all of our public repos are available at https://github.com/unification-com

Paul Hodgson, Unification CTO

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store