Setting up a cluster

This page describes how to set up a local cluster of nodes, advise how to make it private, and how to hook up your nodes on the eth-netstat network monitoring app. A fully controlled ethereum network is useful as a backend for network integration testing (core developers working on issues related to networking/blockchain synching/message propagation, etc or DAPP developers testing multi-block and multi-user scenarios).

We assume you are able to build geth following the build instructions

Setting up multiple nodes

In order to run multiple ethereum nodes locally, you have to make sure:

  • each instance has a separate data directory (--datadir)
  • each instance runs on a different port (both eth and rpc) (--port and --rpcport)
  • in case of a cluster the instances must know about each other
  • the ipc endpoint is unique or the ipc interface is disabled (--ipcpath or --ipcdisable)

You start the first node (let's make port explicit and disable ipc interface)

geth --datadir="/tmp/eth/60/01" -verbosity 6 --ipcdisable --port 30301 --rpcport 8101 console 2>> /tmp/eth/60/01.log

We started the node with the console, so that we can grab the enode url for instance:

> admin.nodeInfo.NodeUrl

[::] will be parsed as localhost ( If your nodes are on a local network check each individual host machine and find your ip with ifconfig (on Linux and MacOS):

$ ifconfig|grep netmask|awk '{print $2}'

If your peers are not on the local network, you need to know your external IP address (use a service) to construct the enode url.

Now you can launch a second node with:

geth --datadir="/tmp/eth/60/02" --verbosity 6 --ipcdisable --port 30302 --rpcport 8102 console 2>> /tmp/eth/60/02.log

If you want to connect this instance to the previously started node you can add it as a peer from the console with admin.addPeer(enodeUrlOfFirstInstance).

You can test the connection by typing in geth console:

> net.listening
> net.peerCount 
> admin.peers

Local cluster

As an extention of the above, you can spawn a local cluster of nodes easily. It can also be scripted including account creation which is needed for mining. See script, and the README there for usage and examples.

Private network

An ethereum network is a private network if the nodes are not connected to the main network nodes. In this context private only means reserved or isolated, rather than protected or secure. Since connections between nodes are valid only if peers have identical protocol version and network id, you can effectively isolate your network by setting either of these to a non default value. We recommend using the semantic networkid command line option for this. Its argument is an integer, the main network has id 1 (the default). So if you supply your own custom network id which is different than the main network your nodes will not connect to other nodes and form a private network.

Monitoring your nodes

This page describes how to use the The Ethereum (centralised) network status monitor (known sometimes as "eth-netstats") to monitor your nodes.

This page or this README describes how you set up your own monitoring service for a (private or public) local cluster.