To fully connect to the swarm, your Bee node needs to be able to both send and receive messages from the outside world. Normally, your router will not allow other IP's on the Internet to connect, unless you have initiated the connection. Bees welcome newcomers in the swarm, as long as they play by the rules! If a node misbehaves, we will simply add it to a list of blocked nodes and refuse future connections from them.
Here at Swarm, every Bee counts! To make sure all Bees can join the swarm, below you will find a detailed guide to navigating your way through your network and making out into the wild so you can buzz around fellow bees and maximise your chances of earning those BZZs. If you still have problems, please join us in our Discord server and we'll help you find the way! 🐝 🐝 🐝 🐝 🐝
To ensure your Bee has the best chance of particpating in the swarm,
you must ensure your Bee is able to handle both incoming and
outgoing connections from the global Internet to its p2p port
1634 by default). See below for a detailed guide on how to make sure
this is the case, or for the 1337: check your
http://localhost:1635/addresses to see which public ip and port
libp2p is advertising and verify its connectivity to the rest of the
Internet! You may need to alter your Bee nodes
In a network, each computer is assigned an IP address. Each IP address is then subdivided into thousands of sockets or ports, each of which has an incoming and outgoing component.
In a completely trusted network of computers, any connections to or from any of these ports are allowed. However, to protect ourselves from nefarious actors when we join the wider Internet, it is sometimes important to filter this traffic so that some of these ports are off limits to the public.
In order to allow messages to our p2p port from other Bee nodes that
we have previously not connected, we must ensure that our network is
set up to receive incoming connections (on port
1634 by default).
There are also some ports which you should never expose to the outside
Internet. Make sure that your
1633) is only ever
Gateway Mode and your
is never exposed to the Internet. It is good practice to employ one or
more firewalls that block traffic on every port except for those you
are expecting to be open.
When you connect to the Internet, you are assigned a unique number called an IP Address. IP stands for Internet Protocol. The most prevalent IP version used is still the archaic IPv4 which was invented way back in 1981. IPv6 is available but not well used. Due to the mitigation of the deficiencies inherent in the IPv4 standard, we may encounter some complications.
If you are renting space in a datacenter, the chances are that your computer will be connected directly to the real Internet. This means that the IP of your networking interface will be directly set to be the same as your public IP.
You can investigate this by running:
Your output should contain something like:
Here we can see our computer's public IP address
188.8.131.52. This is the address that is used by other computers
we connect to over the Internet. We can verify this using a third
party service such as icanhazip.
With Bee running, try to connect to your Bee's p2p port using the public IP adddress from another computer:
If you have success, congratulations!
If this still doesn't work for you, see the last part of Manual: Configure Your Router and Bee section below, as you may need to configure your
To address the scarcity of IP numbers, Network Address Translation (NAT) was implemented. This approach creates a smaller, private network which many devices connect to in order to share a public IP address. Traffic destined for the Internet at large is then mediated by another specialised computer. In the cases of the a home network, this computer is the familiar home router, normally also used to provide a WiFi network.
If we run the above commands to find the computer's IP in this scenario, we will see a different output.
Here we can see that, instead of the public IP address, we can see
that our computer's IP address is
192.168.0.10. This is part of the
IP address space that the Internet Engineering Task Force has
As this IP won't work on the global Internet, our router remembers that our computer has been assigned this IP. It then uses Network Address Translation (NAT) to modify all requests from our computer to another computer somewhere in the Internet. As the requests pass through the router it changes our local IP to the public IP of the router, and vice versa when the responses are sent back, from the public IP to the local one.
The presence of NAT presents two problems for p2p networking.
The first is that it can be difficult for programs running on our computer to know our real public IP as it is not explicitly known by our computer's networking interface, which is configured with a private network IP. This is a relatively easy problem to solve as we can simply discover our public IP and then specify it in Bee's configuration, or indeed determine it using other means.
The second issue is that our router has only 65535 ports to expose to the public network, however, each device on your private network is capable of exposing 65535 each. To the global Internet, it appears that there is only one set of ports to connect to, whereas, in actual fact, there is a full set of ports for each of the devices which are connected to the private network. To solve this second problem, routers commonly employ an approach known as port forwarding.
Bee's solution to these problems come in two flavours, automatic and manual.
UPnP is a protocol designed to simplify the administration of NAT and port forwarding for the end user by providing an API from which software running within the network can use to ask the router for the public IP and to request for ports to be forwarded to the private IP of the computer running the software.
UPnP is a security risk!
UPnP is a security risk as it allows any host or process inside (sometimes also outside) your network to open arbitrary ports which may be used to transfer malicious traffic, for example a RAT. UPnP can also be used to determine your IP, and in the case of using ToR or a VPN, your real public IP. We urge you to disable UPnP on your router and use manual port forwarding as described below.
Bee will use UPnP to determine your public IP, which is required for various internal processes.
In addition to this, a request will be sent to your router to ask it
to forward a random one of its ports, which are exposed directly to
the Internet, to the Bee p2p port (default
1634) which your computer
is exposing only to the private network. Doing this creates a tunnel
through which other Bee's may connect to your computer safely.
If you start your Bee node in a private network with UPnP available, the output of the addresses endpoint of your Debug API will look something like this:
Note that the port in the external
multiaddress is the
router's randomly selected
20529 which is forwarded by the router to
192.168.0.10:1634. These addresses in this multiaddress are also
known as the underlay addresses.
Inspecting the underlay addresses in the output of the addresses
endpoint of our Debug API, we can see addresses only for localhost
127.0.0.1 and our private network IP
192.168.0.10. Bee must be
having trouble navigating our NAT.
To help fix the first problem, let's determine our public IP address.
Now we can simply supply this IP in our Bee configuration on startup.
Solving our second problem is a little more difficult as we will need to interact with our router's firmware, which is a little cranky.
Each router is different, but the concept is usually the same. Log in to your router by navigating your browser to your router's configuration user interface, usually at http://192.168.0.1. You will need to log in with a password. Sadly, passwords are often left to be the defaults, which can be found readily on the Internet.
Once logged in, find the interface to set up port forwarding. The Port Forward website provides some good information, or you may refer to your router manual or provider.
Here, we will then set up a rule that forwards port
1634 of our
private IP address
192.168.0.10 to the same port
1634 of our
Now, when requests arrive at our public address
are modified by our router and forwarded to our private IP and port
Sometimes this can be a little tricky, so let's verify we are able to make a TCP connection using netcat.
First, with Bee not running, let's set up a simple TCP listener using Netcat on the same machine we would like to run Bee on.
If this didn't work for you, check out our Debugging Connectivity guide below.
If it did, let's start our Bee node with the
Checking our addresses endpoint again, we can now see that Bee has been able to successfully assign a public address! Congratulations, your Bee is now connected to the outside world!
If you are regularly connecting and disconnecting to a network, you may also want to use your router's firmware to configure the router to reserve and only assign the same local network IP from its DHCP pool to your computer's MAC address. This will ensure that your Bee seamlessly connects when you rejoin the network!
The above guide navigates your NAT, but there are still a few hurdles to overcome. To make sure there is a clear path from your computer to the outside world, let's follow our Bee's journey from the inside out.
Let's set up a netcat listener on all interfaces on the computer we'd like to run Bee on as we have above.
Now, let's verify we're able to connect to netcat by checking the connection from our local machine.
This should be a no brainer, the connection between localhost in not normally mediated.
If there is a problem here, the problem is with some other software running on your operating system or your operating system itself. Try a different port, such as
1734 and turning off any unneccesary software. If this doesn't work, you may need to try a different operating system environment. Please get in touch and we'll try to help!
If we were successful, let's move on to the next stage.
If you are not able to get access to some firewall settings, or otherwise debug incoming connectivity, don't worry! All is not lost. Bee can function just fine with just outgoing connections. However, if you can, it is worth the effort to allow incoming connections, as the whole swarm will benefit from the increased connectivity.
Let's find out what our IP looks like to the Internet.
Now try to connect to your port using the global IP.
If this is successful, our Bee node's path is clear!
If not, we can try a few things to make sure there are no barriers stopping us from getting through.
Check your computer's firewall.
Sometimes your computer is configured to prevent connections. If you are on a private network mediated by NAT, you can check if this is the problem by trying to connect from another device on your network using the local IP
nc -zv 192.168.0.10 1634.
For each of these firewalls, set a special rule to allow UDP and TCP traffic to pass through on port
1634. You may want to limit this traffic to the Bee application only.
Check your ingress' firewall.
For a datacenter hired server, this configuration will often take place in somewhere in the web user interface. Refer to your server hosting provider's documentation to work out how to open ports to the open Internet. Ensure that both TCP and UDP traffic are allowed.
Similarly, if you are connecting from within a private network, you may find that the port is blocked by the router. Each router is different, so consult your router's firware documentation to make sure there are no firewalls in place blocking traffic on your Bee's designated p2p port.
You may check this using netcat by trying to connect using your computer's public IP, as above
nc -zv 184.108.40.206 1634.
Docker adds another level of complexity.
To debug docker connectivity issues, we may use netcat as above to check port connections are working as expected. Double check that you are exposing the right ports to your local network, either by using the command line flags or in your docker-compose.yaml. You should be able to successfully check the connection locally using eg.
nc -zv localhost 1634then follow instructions above to make sure your local network has the correct ports exposed to the Internet.
Something else entirely?
Networking is a complex topic, but it keeps us all together. If you still can't connect to your Bee, get in touch via The Beehive and we'll do our best to get you connected. In the swarm, no Bee is left behind.