Skip to content

configuration.md

Latest commit

 

History

History
235 lines (183 loc) · 9.51 KB

configuration.md

File metadata and controls

235 lines (183 loc) · 9.51 KB
Raw

Configuration

handshake-node has a number of configuration options, which can be viewed by running: $ handshake-node --help.

Configuration precedence is:

  1. Built-in defaults
  2. handshake-node.conf
  3. Environment variables
  4. Command-line flags

Environment variables use the HANDSHAKE_NODE_ prefix followed by the long option name in uppercase. Dashes are converted to underscores. For example, --rpcuser can be set with HANDSHAKE_NODE_RPCUSER, and --blockmaxweight can be set with HANDSHAKE_NODE_BLOCKMAXWEIGHT. Slice options such as --addpeer accept comma-separated values. Bootstrap-only flags that must be handled before the config file is loaded, such as --configfile and --version, are not applied from environment variables.

HANDSHAKE_NODE_RPCUSER=myuser \
HANDSHAKE_NODE_RPCPASS=mypassword \
HANDSHAKE_NODE_RPCLISTEN=127.0.0.1:12037 \
handshake-node

Peer server listen interface

handshake-node allows you to bind to specific interfaces which enables you to setup configurations with varying levels of complexity. The listen parameter can be specified on the command line as shown below with the -- prefix or in the configuration file without the -- prefix (as can all long command line options). The configuration file takes one entry per line.

NOTE: The listen flag can be specified multiple times to listen on multiple interfaces as a couple of the examples below illustrate.

Command Line Examples:

Flags Comment
--listen= all interfaces on default port which is changed by --regtest (default)
--listen=0.0.0.0 all IPv4 interfaces on default port which is changed by --regtest
--listen=:: all IPv6 interfaces on default port which is changed by --regtest
--listen=:12038 all interfaces on port 12038
--listen=0.0.0.0:12038 all IPv4 interfaces on port 12038
--listen=[::]:12038 all IPv6 interfaces on port 12038
--listen=127.0.0.1:12038 only IPv4 localhost on port 12038
--listen=[::1]:12038 only IPv6 localhost on port 12038
--listen=:8336 all interfaces on non-standard port 8336
--listen=0.0.0.0:8336 all IPv4 interfaces on non-standard port 8336
--listen=[::]:8336 all IPv6 interfaces on non-standard port 8336
--listen=127.0.0.1:8337 --listen=[::1]:12038 IPv4 localhost on port 8337 and IPv6 localhost on port 12038
--listen=:12038 --listen=:8337 all interfaces on ports 12038 and 8337

The following config file would configure handshake-node to only listen on localhost for both IPv4 and IPv6:

[Application Options]

listen=127.0.0.1:12038
listen=[::1]:12038

In addition, if you are starting handshake-node with TLS and want to make it available via a hostname, then you will need to generate the TLS certificates for that host. For example,

gencerts --host=myhostname.example.com --directory=/home/me/.handshake-node/

RPC server listen interface

handshake-node allows you to bind the RPC server to specific interfaces which enables you to setup configurations with varying levels of complexity. The rpclisten parameter can be specified on the command line as shown below with the -- prefix or in the configuration file without the -- prefix (as can all long command line options). The configuration file takes one entry per line.

A few things to note regarding the RPC server:

  • The RPC server will not be enabled unless the rpcuser and rpcpass options are specified.
  • When the rpcuser and rpcpass and/or rpclimituser and rpclimitpass options are specified, the RPC server will only listen on localhost IPv4 and IPv6 interfaces by default. You will need to override the RPC listen interfaces to include external interfaces if you want to connect from a remote machine.
  • The RPC server has TLS enabled by default, even for localhost. You may use the --notls option to disable it, but only when all listeners are on localhost interfaces.
  • The --rpcallowip flag can be specified multiple times to restrict RPC clients to explicit IP addresses or CIDR networks. Empty means all remote addresses are allowed subject to authentication.
  • The --rpclisten flag can be specified multiple times to listen on multiple interfaces as a couple of the examples below illustrate.
  • HTTP and websocket JSON-RPC requests are limited to 16 MiB. This admits a maximum-size Handshake wire object after hex encoding while bounding memory use per request. Split larger batches into separate requests.
  • The RPC server is disabled by default when using the --regtest and --simnet networks. You can override this by specifying listen interfaces.

Command Line Examples:

Flags Comment
--rpclisten= all interfaces on default port which is changed by --regtest
--rpclisten=0.0.0.0 all IPv4 interfaces on default port which is changed by --regtest
--rpclisten=:: all IPv6 interfaces on default port which is changed by --regtest
--rpclisten=:12037 all interfaces on port 12037
--rpclisten=0.0.0.0:12037 all IPv4 interfaces on port 12037
--rpclisten=[::]:12037 all IPv6 interfaces on port 12037
--rpclisten=127.0.0.1:12037 only IPv4 localhost on port 12037
--rpclisten=[::1]:12037 only IPv6 localhost on port 12037
--rpclisten=:8336 all interfaces on non-standard port 8336
--rpclisten=0.0.0.0:8336 all IPv4 interfaces on non-standard port 8336
--rpclisten=[::]:8336 all IPv6 interfaces on non-standard port 8336
--rpclisten=127.0.0.1:8337 --listen=[::1]:12037 IPv4 localhost on port 8337 and IPv6 localhost on port 12037
--rpclisten=:12037 --listen=:8337 all interfaces on ports 12037 and 8337

The following config file would configure the handshake-node RPC server to listen to all interfaces on the default port, including external interfaces, for both IPv4 and IPv6:

[Application Options]

rpclisten=

Operations endpoints

The Prometheus metrics endpoint and Stratum server are disabled by default. Bind them to loopback or an internal management network unless there is a specific reason to expose them.

[Application Options]

metricslisten=127.0.0.1:12039

--metricslisten serves Prometheus text format at /metrics. It is not authenticated. Binding it to a non-loopback interface requires --metricsallowpublic.

[Application Options]

miningaddr=hs1qyourhandshakeaddress
stratumlisten=127.0.0.1:12040
stratumuser=worker
stratumpass=secret

--stratumlisten enables the Handshake Stratum v1 MVP server. It requires at least one --miningaddr. Binding it to a non-loopback interface requires --stratumallowpublic, and public Stratum binds also require --stratumuser and --stratumpass.

Default ports

While handshake-node is highly configurable when it comes to the network configuration, the following is intended to be a quick reference for the default ports used so port forwarding can be configured as required.

handshake-node provides a --upnp flag which can be used to automatically map the peer-to-peer listening port if your router supports UPnP. If your router does not support UPnP, or you don't wish to use it, please note that only the peer-to-peer port should be forwarded unless you specifically want to allow RPC access to your handshake-node from external sources such as in more advanced network configurations.

Name Port
Default peer-to-peer port TCP 12038
Default RPC port TCP 12037
Default Prometheus metrics port TCP 12039
Default Stratum port TCP 12040

Using bootstrap.dat

What is bootstrap.dat?

It is a flat, binary file containing blockchain data starting from the genesis block and continuing through a relatively recent block height depending on the last time it was updated.

NOTE: Using bootstrap.dat is entirely optional. handshake-node will download the block chain from other peers through the protocol with no extra configuration needed.

What are the pros and cons of using bootstrap.dat?

Pros:

  • Typically accelerates the initial process of bringing up a new node as it downloads from public P2P nodes and generally is able to achieve faster download speeds
  • It is particularly beneficial when bringing up multiple nodes as you only need to download the data once

Cons:

  • Requires you to setup and configure a torrent client if you don't already have one available
  • Requires roughly twice as much disk space since you'll need the flat file as well as the imported database

How do I know I can trust the bootstrap.dat I downloaded?

You don't need to trust the file as the addblock utility verifies every block using the same rules that are used when downloading the block chain normally through the protocol. Additionally, the chain rules contain hard-coded checkpoints for the known-good block chain at periodic intervals. This ensures that not only is it a valid chain, but it is the same chain that everyone else is using.

How do I use bootstrap.dat with handshake-node?

handshake-node comes with a separate utility named addblock which can be used to import bootstrap.dat. This approach is used since the import is a one-time operation and we prefer to keep the daemon itself as lightweight as possible.

  1. Stop handshake-node if it is already running. This is required since addblock needs to access the database used by handshake-node and it will be locked if handshake-node is using it.
  2. Note the path to the downloaded bootstrap.dat file.
  3. Run the addblock utility with the -i argument pointing to the location of bootstrap.dat:

Linux/Unix/BSD/POSIX:

$GOPATH/bin/addblock -i /path/to/bootstrap.dat