You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
Nate Brown 92dfccf01a
v1.6.0 (#701)
6 hours ago
.github/workflows Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
cert Update dependencies - 2022-04 (#664) 2 months ago
cidr Rework some things into packages (#489) 8 months ago
cmd Be more clear about ipv4 in nebula-cert (#604) 7 months ago
config add listen.send_recv_error config option (#670) 3 days ago
dist Add Wintun support (#289) 8 months ago
e2e Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
examples Remove EXPERIMENTAL text from routines example config. (#702) 11 hours ago
firewall Rework some things into packages (#489) 8 months ago
header Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
iputil Update dependencies - 2022-04 (#664) 2 months ago
overlay Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
sshd Fix single command ssh exec (#483) 1 year ago
test Remove WriteRaw, cidrTree -> routeTree to better describe its purpose, remove redundancy from field names (#582) 8 months ago
udp Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
util Move util to test, contextual errors to util (#575) 8 months ago
wintun fix `wintun` package to have // +build comments (#598) 7 months ago
.gitignore Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
AUTHORS Public Release 3 years ago
CHANGELOG.md v1.6.0 (#701) 6 hours ago
LICENSE Public Release 3 years ago
Makefile Relay (#678) 1 week ago
README.md Update link to nebula docs (#655) 3 months ago
allow_list.go Rework some things into packages (#489) 8 months ago
allow_list_test.go Move util to test, contextual errors to util (#575) 8 months ago
bits.go Don't use a global logger (#423) 1 year ago
bits_test.go Move util to test, contextual errors to util (#575) 8 months ago
cert.go Remove x509 config loading code (#685) 1 week ago
connection_manager.go Relay (#678) 1 week ago
connection_manager_test.go Lighthouse reload support (#649) 4 months ago
connection_state.go Don't use a global logger (#423) 1 year ago
control.go Relay (#678) 1 week ago
control_test.go Relay (#678) 1 week ago
control_tester.go Add relay e2e tests and output some mermaid sequence diagrams (#691) 3 days ago
dns_server.go Relay (#678) 1 week ago
dns_server_test.go Public Release 3 years ago
firewall.go Rework some things into packages (#489) 8 months ago
firewall_test.go Move util to test, contextual errors to util (#575) 8 months ago
go.mod Update dependencies - 2022-04 (#664) 2 months ago
go.sum Update dependencies - 2022-04 (#664) 2 months ago
handshake.go Relay (#678) 1 week ago
handshake_ix.go Relay (#678) 1 week ago
handshake_manager.go Relay (#678) 1 week ago
handshake_manager_test.go Relay (#678) 1 week ago
hostmap.go Relay (#678) 1 week ago
hostmap_test.go Refactor remotes and handshaking to give every address a fair shot (#437) 1 year ago
inside.go Immediately forward packets received on the nebula TUN device from self to self (#501) 3 days ago
inside_darwin.go Immediately forward packets received on the nebula TUN device from self to self (#501) 3 days ago
inside_generic.go Immediately forward packets received on the nebula TUN device from self to self (#501) 3 days ago
interface.go add listen.send_recv_error config option (#670) 3 days ago
lighthouse.go Relay (#678) 1 week ago
lighthouse_test.go Relay (#678) 1 week ago
logger.go Move util to test, contextual errors to util (#575) 8 months ago
main.go add listen.send_recv_error config option (#670) 3 days ago
message_metrics.go Rework some things into packages (#489) 8 months ago
metadata.go Update dependencies - 2022-04 (#664) 2 months ago
nebula.pb.go reserve NebulaHandshakeDetails fields for multiport (#674) 3 days ago
nebula.proto reserve NebulaHandshakeDetails fields for multiport (#674) 3 days ago
noise.go Relay (#678) 1 week ago
outside.go add listen.send_recv_error config option (#670) 3 days ago
outside_test.go Rework some things into packages (#489) 8 months ago
punchy.go Lighthouse reload support (#649) 4 months ago
punchy_test.go Lighthouse reload support (#649) 4 months ago
relay_manager.go Relay (#678) 1 week ago
remote_list.go Relay (#678) 1 week ago
remote_list_test.go Rework some things into packages (#489) 8 months ago
ssh.go Relay (#678) 1 week ago
stats.go Rework some things into packages (#489) 8 months ago
timeout.go Rework some things into packages (#489) 8 months ago
timeout_system.go Rework some things into packages (#489) 8 months ago
timeout_system_test.go Rework some things into packages (#489) 8 months ago
timeout_test.go Rework some things into packages (#489) 8 months ago

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, Windows, iOS, and Android. 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.

Further documentation can be found here.

You can read more about Nebula here.

You can also join the NebulaOSS Slack group here.

Supported Platforms

Desktop and Server

Check the releases page for downloads or see the Distribution Packages section.

  • Linux - 64 and 32 bit, arm, and others
  • Windows
  • MacOS
  • Freebsd

Distribution Packages

  • Arch Linux
    $ sudo pacman -S nebula
    
  • Fedora Linux
    $ sudo dnf copr enable jdoss/nebula
    $ sudo dnf install nebula
    

Mobile

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 (ECDH) key exchange and AES-256-GCM in its default configuration.

Nebula was created to provide a mechanism for groups of 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 or Distribution Packages 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.