Getting started

From meshwiki
Jump to: navigation, search

Project Meshnet aims to build a sustainable, decentralized, alternative internet. You can help in several ways, from spreading the word, starting up your first Cjdns node, or starting a local meshnet group called a MeshLocal.

Project Meshnet

Project Meshnet is an effort to replace the existing Internet, a goal borne from the /r/darknetplan community. It aims to use a combination of software and hardware to achieve the goal of a censorship-free internet.

How does it work?

The software basis of Project Meshnet is Cjdns, which allows nearby devices to connect to each other without the internet. Cjdns is being used to build a network similar to the internet called Hyperboria.

The current aim for Hyperboria is for each major city to have a MeshLocal, which is a group of devices connected using Cjdns and appropriate hardware. Initially, a MeshLocal is connected to another MeshLocal over the existing internet, and this forms the worldwide Hyperboria. However, as physical, longer-distance links are created, connection over the internet will be phased out.

How can I help?

What Project Meshnet needs right now is more MeshLocals, which involves finding interested people in your community, and setting up a network. This obviously requires a fair bit of technical knowledge, but also needs people to get out there, spread the message, and gather interest.

Joining the community

Joining us on IRC is the most important part. We are social people and like to talk — helping people and discussing the latest topics on IRC is way easier than in a wiki. Don't be shy. Introduce yourself. See the IRC page for info on how to get on IRC.

Here are of some of the folks you'll see answering questions and working on Project Meshnet: Project Contributors

What this guide is not

  • A place to find peers to connect to Hyperboria — you find them on the IRC
  • A Linux quick start guide
  • A networking guide
  • An explanation of difficult terms — see the glossary


Cjdns needs to be installed on the device that connects to Hyperboria. It is a routing engine designed for security, scalability, speed and ease-of-use. The dream: You type ./cjdns and give it an interface which connects another node and it gives you an IPv6 address (generated from a public encryption key) and a virtual network card (TUN device) through which you can connect to the Cjdns network you have chosen. For example, the largest current Cjdns network is called Hyperboria.

How cjdns works

In order to understand how Cjdns works, it is important to understand how the existing Internet works. When you send a packet from your computer to another, each router it passes through reads the address on the packet and decides where to send it next. In a Cjdns network, a packet goes to a router and the router labels the packet with directions to a router which will be able to best handle it. That is, a router which is near by in physical space and has an address which is numerically close to the destination address of the packet. The additional directions for the packet allow it to go through numerous routers with minimal handling. Each router just reads the label and bounces the packet wherever the next bits in the label tells it to. Routers have a responsibility to "keep in touch" with other routers that are numerically close to their address and also routers which are physically close to them.

The Cjdns routing engine is a modified implementation of the Kademlia DHT design.

Please read the whitepaper for more information.

Installing and setting up Cjdns

Decide where you will run it

The Cjdns program can be run on both a home computer or a server on the Internet. This will turn your system into a Cjdns "node". To connect to a Cjdns network, your system needs to install Cjdns, then "peer" with a system already connected to a Cjdns network (peering is usually via the Internet). Once "peered", Cjdns traffic can flow both ways.

If you decide to install Cjdns on your home computer, it is likely that you will be on a private network behind your home router. This means that nodes cannot peer to you directly over the Internet unless you forward a port through your router. However, you can still peer from a computer on a private network to a node on the Internet. Once peered (in either direction) you will be able to connect to and from other nodes on the Cjdns network via Cjdns.

Alternatively, running Cjdns on an internet server helps by extending the Cjdns network, and enables you to provide access to the Cjdns network (ie, to friends) via your server. If you want to install Cjdns on an Internet server, but don't have one, consider a virtual private server.

Install it

Follow one of the guides below to setup Cjdns. Make sure you've read the whitepaper.

Note Note: These guides require some knowledge of GNU/Linux. If you don't understand the command line and basic networking, you should prepare to study those first before attempting to use this software. Cjdns is alpha software that may not be fully functional or build properly at all times. People in the IRC are friendly and willing to help, but probably do not have time to teach you more basic topics so you can use Cjdns. At this point, the goal is for you to test Cjdns.

How to build and configure

Installation packages (build and configure above is preferred)

Install using dust-deploy (especially useful if you maintain Cjdns on multiple machines)

Find peers

To connect to Hyperboria, you will need to find a nearby peer. You can look for one on the IRC channel, or get in touch with a MeshLocal near you. Please read and familiarize yourself with the following peering requirements.

Once you have the peering details, follow this guide to add them to your configuration file.

Configuring and maintaining Cjdns


One useful tool for troubleshooting is cjdcmd. It can check whether your config is correctly formatted, what peers you have, traceroute, ping, etc.


Note: this is only needed if you followed the official installation guide. If you installed cjdns from a package, use your OS updater instead.

Go to the directory where you have your cjdroute file. If you've followed this tutorial before it is probably in /opt/cjdns. A other common place is your home folder ~/cjdns

cd /opt/cjdns

Pull the new changes from github

git pull origin master

Release the magic

sudo ./do

Now kill cjdroute and restart it. (This should be run from the build directory)

sudo killall cjdns && ./cjdroute < /etc/cjdroute.conf

Automatically start at boot

Most Linux based systems support init scripts, so follow the instructions on this page to install one. Distribution packages usually include one, so if you're using a package, you don't have to do anything.

Set up HypeDNS

Although it is optional, if you want to use HypeDNS, add the nameserver fc5d:baa5:61fc:6ffd:9554:67f0:e290:7535 to the top of the /etc/resolv.conf file.

echo 'nameserver fc5d:baa5:61fc:6ffd:9554:67f0:e290:7535' >> /etc/resolv.conf

You might need to run this in a startup script because some distro's create a new resolv.conf on startup. On distributions that use resolvconf to manage DNS (for example, Ubuntu), you instead need to edit /etc/resolvconf/resolv.conf.d/head

echo 'nameserver fc5d:baa5:61fc:6ffd:9554:67f0:e290:7535' >> /etc/resolvconf/resolv.conf.d/head

See HypeDNS and DNS for more info about DNS on Hyperboria

If you want to host something on Hyperboria but don't know what the people want, head on over to the Service Requests page for some inspiration, and pick a project that matches your skill level. Remember, the people on IRC will probably be really helpful for this kind of voluntary stuff, so if you get stuck, ask around in there.

Secure your node

Once your node is running, you're now a newly minted IPv6 host. Your operating system may automatically reconfigure network services to use this new address. If this is not what you intend, you should check to see that you are not offering more services then you intended to.

First find your ip address ip addr | egrep 'fc[a-f0-9:]{20,}' -o. Then run nmap. (Not installed by default everywhere)

   nmap -6 -n -r -v -p1-65535 -sT <your-ip-address>

If you see anything open, fix it.


cjdns provides security on IP address level, but does not yet provide a secure DNS system (although it's in the works, see RainflyDNS), so your computer will use DNS from the regular Internet for accessing cjdns websites. This may compromise security of the connection (see DNS spoofing in Wikipedia for details).

You should use encrypted DNS, e.g. DNSCrypt in conjunction with a DNSSEC-supporting server, if you want your cjdns communications to be secure. Note that this still depends on the security of the DNS server you use - this is why we need a custom DNS system in the long run.

Starting or joining a MeshLocal

To get involved with a MeshLocal, find out if there's a group in your area on our List of Mesh Locals. If there isn't one available, view our guide to starting a MeshLocal—and get a pair of radios, preferably ones that are directional. Below are a few good radios that can handle a fair bit of traffic:

Here are some that will preform moderately well, but if you're buying new please go with something besides Consumer Grade hardware:

  • Most of the Linksys WRT54G series
  • A fair number of Dlink, Buffalo, and most ASUS routers
  • Most TP-Link routers, including the TL-MR3020, as used for pirateboxes.

If you're running short of cash and need a radio, look on eBay, Craigslist or for radios and other hardware.

See also