Skip to content
A scalable overlay networking tool with a focus on performance, simplicity and security
Go Other
  1. Go 98.6%
  2. Other 1.4%
Branch: master
Clone or download
Pull request Compare This branch is 3 commits behind slackhq:master.
alanhlam conform to new build format for vagrant (slackhq#153)
* conform to new build format for vagrant
Latest commit 5c126cd Jan 8, 2020
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows GitHub Action: add release script (slackhq#124) Dec 21, 2019
cert
cmd fix(nebula-cert): flag duration is optional, so reflect this is the c… Jan 6, 2020
examples conform to new build format for vagrant (slackhq#153) Jan 8, 2020
sshd Public Release Nov 19, 2019
.gitignore Support for 1.0.0 release Nov 19, 2019
AUTHORS Public Release Nov 19, 2019
LICENSE Public Release Nov 19, 2019
Makefile
README.md Update README.md Jan 7, 2020
bits.go Public Release Nov 19, 2019
bits_test.go Public Release Nov 19, 2019
cert.go Public Release Nov 19, 2019
cidr_radix.go Add a way to find the most specific network Dec 10, 2019
cidr_radix_test.go Add a way to find the most specific network Dec 10, 2019
config.go Better error message when no config files found Nov 22, 2019
config_test.go Public Release Nov 19, 2019
connection_manager.go subnet support Dec 12, 2019
connection_manager_test.go subnet support Dec 12, 2019
connection_state.go Public Release Nov 19, 2019
dns_server.go Allow configuration of dns listener host/port (slackhq#74) Dec 12, 2019
dns_server_test.go Public Release Nov 19, 2019
firewall.go Actual fix for the real issue with tests Dec 19, 2019
firewall_test.go Actual fix for the real issue with tests Dec 19, 2019
go.mod Update dependencies, December 2019 Dec 16, 2019
go.sum Update dependencies, December 2019 Dec 16, 2019
handshake.go remove old hmac function. superceded by ix_psk0 Nov 23, 2019
handshake_ix.go subnet support Dec 12, 2019
handshake_manager.go
handshake_manager_test.go subnet support Dec 12, 2019
header.go Public Release Nov 19, 2019
header_test.go Public Release Nov 19, 2019
hostmap.go make this a warning, even though i believe it is fundamentally an error Dec 13, 2019
hostmap_test.go subnet support Dec 12, 2019
inside.go subnet support Dec 12, 2019
interface.go remove old hmac function. superceded by ix_psk0 Nov 23, 2019
lighthouse.go Allow ValidateLHStaticEntries to check all static host map entries (s… Jan 3, 2020
lighthouse_test.go Fail with a better error message if lh a hosts is unparsable Dec 10, 2019
main.go new mtu setting and const for default Dec 12, 2019
main_test.go Public Release Nov 19, 2019
metadata.go Public Release Nov 19, 2019
nebula.pb.go Public Release Nov 19, 2019
nebula.proto Public Release Nov 19, 2019
noise.go Public Release Nov 19, 2019
outside.go subnet support Dec 12, 2019
outside_test.go Public Release Nov 19, 2019
ssh.go gofmt Dec 12, 2019
stats.go Correct typo (slackhq#150) Jan 6, 2020
timeout.go Public Release Nov 19, 2019
timeout_system.go Public Release Nov 19, 2019
timeout_system_test.go Public Release Nov 19, 2019
timeout_test.go Public Release Nov 19, 2019
tun_common.go new mtu setting and const for default Dec 12, 2019
tun_darwin.go Support unsafe_routes on Darwin (slackhq#139) Jan 6, 2020
tun_linux.go Make linux tx queue length an error log instead of a fatal on error Dec 20, 2019
tun_test.go Public Release Nov 19, 2019
tun_windows.go subnet support Dec 12, 2019
udp_darwin.go Public Release Nov 19, 2019
udp_generic.go Public Release Nov 19, 2019
udp_linux.go fix listen.host Dec 17, 2019
udp_linux_32.go Rework udp for linux into just 2 files, add more mips targets Dec 11, 2019
udp_linux_64.go Rework udp for linux into just 2 files, add more mips targets Dec 11, 2019
udp_windows.go Public Release Nov 19, 2019

README.md

What is Nebula?

Nebula is a scalable overlay networking tool with a focus on performance, simplicity and security. It lets you seamlessly connect computers anywhere in the world. Nebula is portable, and runs on Linux, OSX, and Windows. (Also: keep this quiet, but we have an early prototype running on iOS). It can be used to connect a small number of computers, but is also able to connect tens of thousands of computers.

Nebula incorporates a number of existing concepts like encryption, security groups, certificates, and tunneling, and each of those individual pieces existed before Nebula in various forms. What makes Nebula different to existing offerings is that it brings all of these ideas together, resulting in a sum that is greater than its individual parts.

You can read more about Nebula here.

You can also join the NebulaOSS Slack group here

Technical Overview

Nebula is a mutually authenticated peer-to-peer software defined network based on the Noise Protocol Framework. Nebula uses certificates to assert a node's IP address, name, and membership within user-defined groups. Nebula's user-defined groups allow for provider agnostic traffic filtering between nodes. Discovery nodes allow individual peers to find each other and optionally use UDP hole punching to establish connections from behind most firewalls or NATs. Users can move data between nodes in any number of cloud service providers, datacenters, and endpoints, without needing to maintain a particular addressing scheme.

Nebula uses elliptic curve Diffie-Hellman key exchange, and AES-256-GCM in its default configuration.

Nebula was created to provide a mechanism for groups hosts to communicate securely, even across the internet, while enabling expressive firewall definitions similar in style to cloud security groups.

Getting started (quickly)

To set up a Nebula network, you'll need:

1. The Nebula binaries for your specific platform. Specifically you'll need nebula-cert and the specific nebula binary for each platform you use.

2. (Optional, but you really should..) At least one discovery node with a routable IP address, which we call a lighthouse.

Nebula lighthouses allow nodes to find each other, anywhere in the world. A lighthouse is the only node in a Nebula network whose IP should not change. Running a lighthouse requires very few compute resources, and you can easily use the least expensive option from a cloud hosting provider. If you're not sure which provider to use, a number of us have used $5/mo DigitalOcean droplets as lighthouses.

Once you have launched an instance, ensure that Nebula udp traffic (default port udp/4242) can reach it over the internet.

3. A Nebula certificate authority, which will be the root of trust for a particular Nebula network.

./nebula-cert ca -name "Myorganization, Inc"

This will create files named ca.key and ca.cert in the current directory. The ca.key file is the most sensitive file you'll create, because it is the key used to sign the certificates for individual nebula nodes/hosts. Please store this file somewhere safe, preferably with strong encryption.

4. Nebula host keys and certificates generated from that certificate authority

This assumes you have four nodes, named lighthouse1, laptop, server1, host3. You can name the nodes any way you'd like, including FQDN. You'll also need to choose IP addresses and the associated subnet. In this example, we are creating a nebula network that will use 192.168.100.x/24 as its network range. This example also demonstrates nebula groups, which can later be used to define traffic rules in a nebula network.

./nebula-cert sign -name "lighthouse1" -ip "192.168.100.1/24"
./nebula-cert sign -name "laptop" -ip "192.168.100.2/24" -groups "laptop,home,ssh"
./nebula-cert sign -name "server1" -ip "192.168.100.9/24" -groups "servers"
./nebula-cert sign -name "host3" -ip "192.168.100.10/24"

5. Configuration files for each host

Download a copy of the nebula example configuration.

  • On the lighthouse node, you'll need to ensure am_lighthouse: true is set.

  • On the individual hosts, ensure the lighthouse is defined properly in the static_host_map section, and is added to the lighthouse hosts section.

6. Copy nebula credentials, configuration, and binaries to each host

For each host, copy the nebula binary to the host, along with config.yaml from step 5, and the files ca.crt, {host}.crt, and {host}.key from step 4.

DO NOT COPY ca.key TO INDIVIDUAL NODES.

7. Run nebula on each host

./nebula -config /path/to/config.yaml

Building Nebula from source

Download go and clone this repo. Change to the nebula directory.

To build nebula for all platforms: make all

To build nebula for a specific platform (ex, Windows): make bin-windows

See the Makefile for more details on build targets

Credits

Nebula was created at Slack Technologies, Inc by Nate Brown and Ryan Huber, with contributions from Oliver Fross, Alan Lam, Wade Simmons, and Lining Wang.

You can’t perform that action at this time.