What is Hyperboria?

Hyperboria is an encrypted Mesh Network that utilizes cjdns, a layer 3 routing protocol which implements end to end encryption.

Many of the Hyperboria's nodes are connected over the internet, making it at least partially an Overlay network, however, cjdns works quite well running over its own infrastructure. If you can establish point to point connections with people in your neighbourhood, you can establish what we call a Meshlocal, a community operated networking initiative.

Ultimately, we hope to build a viable alternative to the regular internet, which we call clearnet. Wherever we see hierarchical network structures, we attempt to replace them with decentralized structures.

Our community mirrors the technology that we are building. Development is distributed across many communities around the world, and we stitch together smaller networks with UDP links over the internet, and communicate largely over IRC, available at irc://irc.fc00.io (development) and irc://irc.hypeirc.net (general communication).

To find peers, /join #peering. To Help with development, /join #cjdns. To assist us in documenting cjdns and Hyperboria, /join #documentation. In case, you have no peers so far and want to access hyperirc, you can use one of the public peers or this node.

Can I run Cjdns in a virtual machine?

You can, but you might have trouble finding willing peers, since you're not really contributing much to the network by having a 'sometimes-on' node.

Why is it taking so long to find a peer?

This project is run entirely by volunteers. In fact, 'run' might give you the idea that it's some kind of beureaucratic body. It isn't. We argue about things, sometimes IN ALL CAPS. Sometimes people QUIT IRC FOREVER. We reach a consensus, or we don't, and people just do what they want. Actually, even if we do reach a consensus, we're still just doing what we want. If you expected something other than anarchy, I encourage you to read more about what a meshnet is.

That means you should be patient, since you're relying on other people's good will (crazy, I know). This is a friend of a friend network, which shocks people, because they actually have to make friends. Tell us about yourself. Where are you located? Do you operate any servers, or are you new to this? If you're new, why do you want to learn? Maybe you maintain a blag or something? That's pretty much what we do on Hyperboria. If you aren't interested in doing that kind of thing, but want access, I'm not sure what your motivation is. We're basically a bunch of DIYers making our own internet. That kind of thing takes time. Think in terms of years, not months. Read this and this to get a sense of context for what this project is about.

With that in mind, say hi, tell us what you're doing. We're pretty enthusiastic about sharing our interests if it's unlikely that you're a FED.

Read this document on peering for more info.

Why should I prefer the friend of a friend model?

Hyperboria is a pseudonymous network, your direct peers can tell where you are (by virtue of their connection), no one else can (unless you expose your data personally).

A network that presupposes this principle is resistant to censorship because people cannot simply find you and punish you for your opinions. Many of the links that make up our network cross between legal jurisdictions, and are not subject to the whims of a single government.

Other networks which do more to guarantee absolute anonymity tend to attract behaviour which would be reprehensible in almost any other social situation. We are proud of our network's ability to promote free speech, while minimizing behaviour which violates human rights. Some have made the point that restriction of any kind of content is censorship, and our views are self contradictory.

The premise is simple: you get to decide who you connect to, provided they consent. It is not some centralized body which will decide to disconnect you if you use our bandwidth for malicious purposes. You are only accountable to your peers. The rest tends to sort itself out.

Can I run cjdns from home (dynamic IP/NAT'ed connection)?

We describe it in terms of 'inbound' and 'outbound' peers

Inbound means people can connect to you, which requires either not being behind a router, or being able to forward ports

Anyone who can install and run cjdns can be an outbound peer

Do I need to exchange credentials with all my peers?

No, you do not. One of you needs to have an accessible IP in order to establish a connection, but once connected, traffic flow is bidirectional.

It won't hurt for you to add each other to your conf file, but unless one of your IPs suddenly changes, there isn't much benefit to the redundancy.

What information should I provide with my peering credentials?

thefinn93 recommends offering valid JSON, including fields labelled:


Technically, only the IP, port, publicKey, and password are required. IPV6 will make it easier to keep track of who is connected, and what kind of latency they are experiencing. The location helps your peer direct possible local meshers your way. Contact should be some non-hyperborian method, in case your connection breaks. Email, XMPP, PGP, Keybase.io, etc.

Beyond my first peer, how can I set up a more efficient network?

Read this

People are much more receptive to peering requests if you have already connected to Hyperboria. EFNet has a much wider audience, and as such is treated with skepticism. Those with their foot already in the door will have an easier time making friends. If you think this is clique-ish or elitist, you may be right. If you want it to change, then be the change you want to see in the world, and get on EFNet and start helping!

It's a bit circular, but it's a not a rule we have, more of an emergent behaviour. Many of us have spent a lot of time on EFNet helping newcomers to connect, only to have them leave after connecting for fifteen minutes. Once we've seen that you are competent enough to connect, and that you have some lasting interest, there is far more incentive to spend time getting to know you.

As to how the technical specifications of the network architecture...

How many peers should I have?

The number of peers you should have depends on a number of factors

if you're on a laptop that you travel with, you probably don't want to route for people. For instance, if you occasionally tether your phone, you might accidentally run up your data bill if you aren't mindful of the traffic you are routing. In such a case, keep only one peer, and you will never be a path, only a leaf node.

If, however, you are trying to peer with, say, a home connection with a decent data cap and throughput, you may want to add a few more connections. These ought to be limited to fairly local peers, as latency can add up fairly quickly with each successive hop. Home connections are primarily where the wireless aspect of the meshnet comes into play, since neither your laptop or VPS will likely be able to connect to a mid-range wireless antenna. If you have a clear line of sight to your peer (you live on a hill, or have really cool neighbours), all data travelling over this connection is free! Make use of that! Put each other on IP whitelists with access to higher bandwidth services. A meshlocal is capable of a lot of things that become difficult at the scale of a global meshnet.

If you're peering up a VPS with high throughput and unlimited data, you have the capacity to do things most residential connections can not. You are capable of acting as a highway for the meshnet. Keep in mind that it can be a bad idea for highway traffic to have direct exits into residential areas (metaphorically speaking). It's a good idea to use your connection to establish long range links between your meshLocal and others in far off places. Trans-Oceanic links help link together a greater number of node operators across the globe, and allow us all to communicate what kinds of issues we are each experiencing.

It would be unrealistic to expect any network to be completely uniform. The optimal configuration changes over time according to the habits of its many users. Healthy configurations look less like a spoke-hub distribution and more alike a river, or tree. It is possible to have an efficient hierarchy without being centralized, just avoid SPOFs.

This may sound a lot like urban planning to you. It is! Consider The 100-Mile Diet. You don't want to have to 'drive halfway across town to get to the grocery store'. We are simply trying to mitigate the unpleasant side effects of urban sprawl. We are planning for walkable neigbourhoods.

If there is only one grocery store in a 400-mile radius, then everyone needs a car. Prime real estate (that which is close to the store) becomes quite expensive, while it is cheaper, yet inefficient, to live on the fringe. Following this metaphor, ISPs are basically a grocery delivery service. If they decide not to deliver your groceries (remember the wikileaks blockade?) you starve. We want to help you plant a community garden, where everyone can benefit - as long as they contribute their fair share. I may have no reason to just give away vegetables that I worked hard for, but I'd be happy to trade for a different crop simply because I enjoy variety.

How can I generate passwords for new peers?

Easy, just run the following command:

cat /dev/urandom | strings | head -n 20 | tr -d '\n"`\ \t' | head -c 40 && echo

Can I use UPNP to bypass NAT?

cjdns does not interact at all with your NAT setup. Use some other upnp client to control your router.

Can I substitute a domain for an IP in my connectTo?

cjd originally had no intention of implementing this, but someone(?) implemented it and submitted a pull request. Now you can.

Is there a meshlocal in my vicinity?

Check this page for a basic list of some general areas. It is not an exhaustive list. If you'd like to get listed, check my contributions page for an idea on how to do that.

Can someone give me peering info?

01:53 -!- newguy [webchat@] has joined #cjdns
01:54 < newguy> can someone point me toward a public peer?
01:55 -!- newguy [webchat@] has quit [Client Quit]

We see this a lot. Please read the peering section of my old faq, and my page about meshlocals.

TL;DR :: this isn't a public network, and we're under no obligation to give credentials to everyone who asks. We aren't a non-profit, or a corporation, or even a cohesive group. Everyone here has their own motivations and ideas of what the network should be, and you need to find someone who wants to connect to you. Don't be shy, introduce yourself.

My peer's connection details aren't working, what's wrong?

I don't know, maybe start by asking your peer? If you don't know how to contact your peer, then you may have just learned a valuable lesson. Take down your next peer's info so that you can tell them when something is wrong. If somebody gave you credentials to connect, then you are officially their problem.

How can a figure out which peers I am directly connected to?

    "addr": ""
    ,"port": 11234
    ,"password": "notAnActualPass.UseYourOwnFoundInYourConf"

Make a file called ~/.cjdnsadmin, containing valid JSON with the properties above. These credentials will be used by any scripts which need to connect to the admin interface to gather data.

To find your peers, run cjdns/contrib/nodejs/tools/peerStats.js

Alternatively, you can use this tool which does a few other things as well.

How to sniff for ethernet cjdns traffic?

tcpdump -nn -s0 -t -vv -e -i mon0 ether proto 0xfc00

What are the EAGAIN errors about?

This is a red herring. It simply means that UDPInterface received a packet, and that there's not immediately another packet received.


recvmsg(13, {msg_name(16)={sa_family=AF_INET, sin_port=htons(25021), sin_addr=inet_addr("")}, msg_iov(1)=[{"\0\0\0\1\1\312\250\207\206\6p\230\200\0k\333\305(\204\27`0\370\202\332B\341`89\376\210"..., 3496}], msg_controllen=0, msg_flags=0}, 0) = 160
recvmsg(13, 0x7fff9490f030, 0)          = -1 EAGAIN (Resource temporarily unavailable)