A scalable overlay networking tool with a focus on performance, simplicity and security
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
Go to file
Nate Brown cc8b3cc961 Add config option for local_cidr control 3 weeks ago
.github Add link to logs guide in bug report template (#1065) 1 month ago
cert cert: fix dropped errors (#961) 6 months ago
cidr At the end 4 weeks ago
cmd cmd/nebula-cert: fix clobbered error (#1032) 3 months ago
config SIGHUP is only useful when config was loaded from a file (#1030) 3 months ago
dist Attempt to notify systemd of service readiness on linux (#929) 7 months ago
e2e add gvisor based service library (#965) 3 months ago
examples Add config option for local_cidr control 3 weeks ago
firewall switch to new sync/atomic helpers in go1.19 (#728) 1 year ago
header Add relay e2e tests and output some mermaid sequence diagrams (#691) 2 years ago
iputil firewall reject packets: cleanup error cases (#957) 4 months ago
noiseutil add test for GOEXPERIMENT=boringcrypto (#861) 10 months ago
overlay Fix mobile builds (#1035) 3 months ago
service add gvisor based service library (#965) 3 months ago
sshd Fix 756 SSH command line parsing error to write to user instead of stderr (#757) 1 year ago
test chore: remove refs to deprecated io/ioutil (#987) 4 months ago
udp Fix UDP listener on IPv4-only Linux (#787) 1 month ago
util Return full error context from ContextualError.Error() (#1069) 1 month ago
wintun switch to new sync/atomic helpers in go1.19 (#728) 1 year ago
.gitignore Add nebula-cert.exe and cert files to .gitignore (#722) 1 year ago
AUTHORS Public Release 4 years ago
CHANGELOG.md v1.8.2 (#1058) 2 months ago
LICENSE Public Release 4 years ago
LOGGING.md Normalize logs (#837) 11 months ago
Makefile test: build all non-main modules for mobile (#1036) 2 months ago
README.md Update Arch Linux package link (#1024) 2 months ago
SECURITY.md add SECURITY.md (#864) 10 months ago
allow_list.go Use generics for CIDRTrees to avoid casting issues (#1004) 4 months ago
allow_list_test.go Use generics for CIDRTrees to avoid casting issues (#1004) 4 months ago
bits.go Don't use a global logger (#423) 3 years ago
bits_test.go Move util to test, contextual errors to util (#575) 2 years ago
boring.go add boringcrypto Makefile targets (#856) 10 months ago
calculated_remote.go Use generics for CIDRTrees to avoid casting issues (#1004) 4 months ago
calculated_remote_test.go add calculated_remotes (#759) 12 months ago
connection_manager.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
connection_manager_test.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
connection_state.go Clean up a hostinfo to reduce memory usage (#955) 4 months ago
control.go add gvisor based service library (#965) 3 months ago
control_test.go Clean up a hostinfo to reduce memory usage (#955) 4 months ago
control_tester.go Simplify getting a hostinfo or starting a handshake with one (#954) 7 months ago
dns_server.go Pull hostmap and pending hostmap apart, remove unused functions (#843) 7 months ago
dns_server_test.go Public Release 4 years ago
firewall.go Add config option for local_cidr control 3 weeks ago
firewall_test.go At the end 4 weeks ago
go.mod Bump github.com/vishvananda/netlink (#1034) 1 month ago
go.sum Bump github.com/vishvananda/netlink (#1034) 1 month ago
handshake_ix.go Clean up a hostinfo to reduce memory usage (#955) 4 months ago
handshake_manager.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
handshake_manager_test.go Clean up a hostinfo to reduce memory usage (#955) 4 months ago
hostmap.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
hostmap_test.go Pull hostmap and pending hostmap apart, remove unused functions (#843) 7 months ago
hostmap_tester.go Fix relay (#827) 11 months ago
inside.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
inside_bsd.go Immediately forward packets from self to self on FreeBSD (#808) 1 year ago
inside_generic.go Immediately forward packets from self to self on FreeBSD (#808) 1 year ago
interface.go Added firewall.rules.hash metric (#1010) 3 months ago
lighthouse.go Fix re-entrant `GetOrHandshake` issues (#1044) 3 months ago
lighthouse_test.go Send the lh update worker into its own routine instead of taking over the reload routine (#935) 7 months ago
logger.go Move util to test, contextual errors to util (#575) 2 years ago
main.go when listen.port is zero, fix multiple routines (#1057) 2 months ago
message_metrics.go Have lighthouses ack updates to reduce test packet traffic (#851) 10 months ago
metadata.go Update dependencies - 2022-04 (#664) 2 years ago
nebula.pb.go Have lighthouses ack updates to reduce test packet traffic (#851) 10 months ago
nebula.proto Have lighthouses ack updates to reduce test packet traffic (#851) 10 months ago
noise.go Relay (#678) 2 years ago
notboring.go add boringcrypto Makefile targets (#856) 10 months ago
outside.go firewall reject packets: cleanup error cases (#957) 4 months ago
outside_test.go Rework some things into packages (#489) 2 years ago
pki.go Combine ca, cert, and key handling (#952) 7 months ago
punchy.go Rehandshaking (#838) 10 months ago
punchy_test.go add punchy.respond_delay config option (#721) 11 months ago
relay_manager.go Fix relay migration (#964) 6 months ago
remote_list.go Fix reconfig freeze attempting to send to an unbuffered, unread channel (#886) 9 months ago
remote_list_test.go Dns static lookerupper (#796) 10 months ago
ssh.go Support inlined sshd host key (#1054) 1 month ago
stats.go add boringcrypto Makefile targets (#856) 10 months ago
timeout.go Generic timerwheel (#804) 1 year ago
timeout_test.go Generic timerwheel (#804) 1 year 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

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.yml 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.yml

Building Nebula from source

Make sure you have go installed 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

Curve P256 and BoringCrypto

The default curve used for cryptographic handshakes and signatures is Curve25519. This is the recommended setting for most users. If your deployment has certain compliance requirements, you have the option of creating your CA using nebula-cert ca -curve P256 to use NIST Curve P256. The CA will then sign certificates using ECDSA P256, and any hosts using these certificates will use P256 for ECDH handshakes.

In addition, Nebula can be built using the BoringCrypto GOEXPERIMENT by running either of the following make targets:

make bin-boringcrypto
make release-boringcrypto

This is not the recommended default deployment, but may be useful based on your compliance requirements.

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.