# Improving connectivity

Filecoin miners, like participants in all peer-to-peer protocols, require a steady and quality pool of peers to communicate with in order to perform their various functions. For other participants on the network to establish incoming P2P connections with a miner, a few conditions must be met:

  • The miner's public IP address must be known
  • The protocol (TCP/UDP) and port number (0-65535) on which the miner is listening must be known
  • All routers & firewalls must be configured to allow incoming traffic on that protocol/port combination

The following steps are highly recommended for all miners who wish to successfully accept storage and retrieval deals.

Prefer a more visual approach? Check out this fantastic video for a walkthrough on the processes of testing and debugging connectivity issues, as well as setting up port forwarding via UPnP on a local router:

# Setting multiaddresses

You can set the multiaddresses that your miner listens on in a miner's config.toml file (by default located at ~/.lotusminer/config.toml).

Once you've done so, you can set the on-chain record of your miner's listen addresses with the command:

lotus-miner actor set-addrs <multiaddr_1> <multiaddr_2> ... <multiaddr_n>

This updates the MinerInfo object in your miner's actor, which will be looked up when a client attempts to make a deal with you. You can provide any number of addresses.

As an example, you could run:

 lotus-miner actor set-addrs /ip4/ /ip4/ 

This step is the best way to ensure your miner is dial-able for storage and retrieval deals!

# Checking peer count

To ensure storage and retrieval deals operate smoothly, it is recommended to check how many peers a miner is connected to after each start-up. In the Lotus client, a manual peer check can be performed with the command:

lotus-miner net peers

If a very low peer count is present (1-5), it is possible to manually connect the miner to the DHT by utilising one of the bootstrap peers listed in the branch's ./build/bootstrap/bootstrappers.pi file with the commmand:

lotus-miner net connect <address1> <address2>…

# Port forwarding

In order to ensure that Filecoin packets are able to pass freely and unfiltered through a local firewall, it is highly recommended to set up port forwarding for a miner's libp2p address. By default, this port is randomised; for optimal connectivity, make sure that it is set to a static IP.

To enable port forwarding on your local router:

  1. Browse to the management website for your home router (typically
  2. Log in as admin / root
  3. Find the section to configure port forwarding
  4. Choose a port, and configure a port forwarding rule with the following values:
    • External port: [CHOSEN PORT]
    • Internal port: [CHOSEN PORT]
    • Protocol: TCP
    • IP Address: Private IP address of the host system running the miner

# Establishing a public IP address

To help storage and retrieval deals operate smoothly, your miner will need to be dialable from a public IP address. Below are multiple ways to achieve this, from manually setting an IP address for your miner, to using software or hardware to set up a relay endpoint.

# Manually setting an IP address

To manually set an IP address for your miner, edit the ~/.lotusminer/config.toml configuration file's AnnounceAddresses address list. You will need to include the port number. DNS4 multi-address or IPV6 formats are also acceptable.

Below is an example ~/.lotusminer/config.toml configuration file in which the public IP address is

   ListenAddresses = ["/ip4/"]
   AnnounceAddresses = ["/ip4/"]

In the above example, port 10240 is forwarded to <internal-miner-host-ip>:5472.

Verify that the port is listening by using telnet (eg: telnet 10240. nc is also sufficient.) If successful, a plaintext /multistream/1.0.0 line will be within the response.

As an additional litmus test, you should be able to:

  • Ping your Public IP address using https://ping.eu/ping
  • Establish a TCP socket to your Public IP address and port using https://ping.eu/port-chk/

If any of these tests fail, then your IP is not publicly dialable.

# Using relay endpoints

If you do not control the NAT/Firewall that your device is behind (such as within enterprise networks and other firewalls), there is an alternative solution for you. You can set up a relay endpoint so that your miner can relay its internet traffic through an external, publicly dialable endpoint.

There are multiple ways to achieve this.

Note: Remember that libp2p (the underlying network stack of the Filecoin miner) listens on multiple addresses simultaneously. This means that adding a relay endpoint is not a tradeoff but an advantage, as it will be used as a last resort when direct connectivity can't be achieved.

# libp2p relay

The libp2p circuit relay is a standard libp2p node that offers a service to any other relay node to route their traffic through it. You can deploy a libp2p circuit relay on a machine with a public IP address (e.g. a standard cloud provider), then instruct your miner to route all of its traffic through the libp2p relay by adding the new multiaddr to your miner.

# Wireguard

Wireguard is a fast, simple, lean VPN. It is transparent for applications and presents itself as yet another network interface for your machine. Similar to the libp2p relay, you will need to deploy a Wireguard endpoint on a public machine, and route your miner's traffic through it.

# Ungleich IPv6 VPN Service

Ungleich is a Swiss company offering a hosted IPv6 VPN service powered by Wireguard.

    1. Contract the service from Ungleich
    1. Install Wireguard on your machine
    1. Create a Wireguard keypair using the command umask 077; wg genkey > privkey
    1. Send the public key associated with your private key to Ungleich. You can get the public key using wg pubkey < privkey
    1. Wait to receive the Wireguard configuration from Ungleich, then set it up on your machine
    1. Follow the Setting multiaddresses steps to add this multiaddr to your miner and announce it on-chain.

Voilà, now you have a new network interface with an IPv6 address. All traffic using that interface will be routed through Ungleich IPv6 VPN, which means that your machine, no matter where it is, will be publicly dialable through that IPv6 address.

You can test your IPv6 connectivity using the service https://www.ultratools.com/tools/ping6

# VPN IPv6 Router Box (VIIRB)

Recently, Ungleich announced an even simpler setup: a VPN contained in a hardware box. This box is known as the VIIRB.

You can order a VIIRB at:

Note: VIIRB uses open source software and hardware. You can also build your own using the specifications for the VIIRB box and its microcomputer, the VoCore.

# SSH Reverse Tunnel

Another option is to use an ssh reverse tunnel to set up a proxy between your miner machine and a public IP machine.

With this approach, you link a local port in your local address to a public port in the public IP machine, and then announce the public port + public IP address to the world. When peers dial back to you on your public multiaddr, the traffic is relayed through that tunnel to your miner machine.

# Troubleshooting

Connectivity issues? Please run the following steps:

  1. Go to https://ping.eu/ping/ and check if the service can ping your public IP address
  2. Go to https://ping.eu/port-chk/ and check if the port that leads to your miner is accessible
  3. From another network (another computer in another house, datacenter, etc), do telnet or netcat to the ip+port and a /multistream/1.0.0 should come out
  4. Go to https://calibration.spacerace.filecoin.io/check to check if the dealbot can successfully get a query-ask from your miner
  5. Check deal details page for your miner at https://calibration.spacerace.filecoin.io/. If it shows an error “routing: not found”, follow the steps in Setting Multiaddresses to set your lotus-miner actor set-addrs.
Error What it means How to fix
ClientQueryAsk failed : failed to open stream to miner: dial backoff The connection to the remote host was attempted, but failed. This may be due to issues with porting, IPs set within the config file, or simply no internet connectivity.
ClientQueryAsk failed : failed to open stream to miner: failed to dial The deal-bot was unable to open a network socket to the miner. This is likely because the miner's IP is not publicly dialable, or a port issue.
ClientQueryAsk failed : failed to open stream to miner: routing: not found The deal-bot was unable to locate the miners IP and/or port. Follow the instructions under the multiaddresses section of this page.
ClientQueryAsk failed : failed to read ask response: stream reset Connectivity loss, usually due to a high packet droprate. Check your internet connectivity and available bandwidth.

If you fail to succeed in any of these steps, please start a thread on #fil-net-calibration in the Filecoin Slack. Please include all of the steps you have tried, their output, and your miner ID.