github.com/slackhq/nebula@v1.9.0/README.md (about)

     1  ## What is Nebula?
     2  Nebula is a scalable overlay networking tool with a focus on performance, simplicity and security.
     3  It lets you seamlessly connect computers anywhere in the world. Nebula is portable, and runs on Linux, OSX, Windows, iOS, and Android.
     4  It can be used to connect a small number of computers, but is also able to connect tens of thousands of computers.
     5  
     6  Nebula incorporates a number of existing concepts like encryption, security groups, certificates,
     7  and tunneling, and each of those individual pieces existed before Nebula in various forms.
     8  What makes Nebula different to existing offerings is that it brings all of these ideas together,
     9  resulting in a sum that is greater than its individual parts.
    10  
    11  Further documentation can be found [here](https://nebula.defined.net/docs/).
    12  
    13  You can read more about Nebula [here](https://medium.com/p/884110a5579).
    14  
    15  You can also join the NebulaOSS Slack group [here](https://join.slack.com/t/nebulaoss/shared_invite/enQtOTA5MDI4NDg3MTg4LTkwY2EwNTI4NzQyMzc0M2ZlODBjNWI3NTY1MzhiOThiMmZlZjVkMTI0NGY4YTMyNjUwMWEyNzNkZTJmYzQxOGU).
    16  
    17  ## Supported Platforms
    18  
    19  #### Desktop and Server
    20  
    21  Check the [releases](https://github.com/slackhq/nebula/releases/latest) page for downloads or see the [Distribution Packages](https://github.com/slackhq/nebula#distribution-packages) section.
    22  
    23  - Linux - 64 and 32 bit, arm, and others
    24  - Windows
    25  - MacOS
    26  - Freebsd
    27  
    28  #### Distribution Packages
    29  
    30  - [Arch Linux](https://archlinux.org/packages/extra/x86_64/nebula/)
    31      ```
    32      $ sudo pacman -S nebula
    33      ```
    34  
    35  - [Fedora Linux](https://src.fedoraproject.org/rpms/nebula)
    36      ```
    37      $ sudo dnf install nebula
    38      ```
    39  
    40  - [Debian Linux](https://packages.debian.org/source/stable/nebula)
    41      ```
    42      $ sudo apt install nebula
    43      ```
    44  
    45  - [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=nebula)
    46      ```
    47      $ sudo apk add nebula
    48      ```
    49  
    50  - [macOS Homebrew](https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/nebula.rb)
    51      ```
    52      $ brew install nebula
    53      ```
    54  
    55  - [Docker](https://hub.docker.com/r/nebulaoss/nebula)
    56      ```
    57      $ docker pull nebulaoss/nebula
    58      ```
    59  
    60  #### Mobile
    61  
    62  - [iOS](https://apps.apple.com/us/app/mobile-nebula/id1509587936?itsct=apps_box&itscg=30200)
    63  - [Android](https://play.google.com/store/apps/details?id=net.defined.mobile_nebula&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1)
    64  
    65  ## Technical Overview
    66  
    67  Nebula is a mutually authenticated peer-to-peer software defined network based on the [Noise Protocol Framework](https://noiseprotocol.org/).
    68  Nebula uses certificates to assert a node's IP address, name, and membership within user-defined groups.
    69  Nebula's user-defined groups allow for provider agnostic traffic filtering between nodes.
    70  Discovery nodes allow individual peers to find each other and optionally use UDP hole punching to establish connections from behind most firewalls or NATs.
    71  Users can move data between nodes in any number of cloud service providers, datacenters, and endpoints, without needing to maintain a particular addressing scheme.
    72  
    73  Nebula uses Elliptic-curve Diffie-Hellman (`ECDH`) key exchange and `AES-256-GCM` in its default configuration.
    74  
    75  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.
    76  
    77  ## Getting started (quickly)
    78  
    79  To set up a Nebula network, you'll need:
    80  
    81  #### 1. The [Nebula binaries](https://github.com/slackhq/nebula/releases) or [Distribution Packages](https://github.com/slackhq/nebula#distribution-packages) for your specific platform. Specifically you'll need `nebula-cert` and the specific nebula binary for each platform you use.
    82  
    83  #### 2. (Optional, but you really should..) At least one discovery node with a routable IP address, which we call a lighthouse.
    84  
    85  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](https://digitalocean.com) droplets as lighthouses.
    86  
    87    Once you have launched an instance, ensure that Nebula udp traffic (default port udp/4242) can reach it over the internet.
    88  
    89  
    90  #### 3. A Nebula certificate authority, which will be the root of trust for a particular Nebula network.
    91  
    92    ```
    93    ./nebula-cert ca -name "Myorganization, Inc"
    94    ```
    95    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.
    96  
    97  #### 4. Nebula host keys and certificates generated from that certificate authority
    98  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.
    99  ```
   100  ./nebula-cert sign -name "lighthouse1" -ip "192.168.100.1/24"
   101  ./nebula-cert sign -name "laptop" -ip "192.168.100.2/24" -groups "laptop,home,ssh"
   102  ./nebula-cert sign -name "server1" -ip "192.168.100.9/24" -groups "servers"
   103  ./nebula-cert sign -name "host3" -ip "192.168.100.10/24"
   104  ```
   105  
   106  #### 5. Configuration files for each host
   107  Download a copy of the nebula [example configuration](https://github.com/slackhq/nebula/blob/master/examples/config.yml).
   108  
   109  * On the lighthouse node, you'll need to ensure `am_lighthouse: true` is set.
   110  
   111  * On the individual hosts, ensure the lighthouse is defined properly in the `static_host_map` section, and is added to the lighthouse `hosts` section.
   112  
   113  
   114  #### 6. Copy nebula credentials, configuration, and binaries to each host
   115  
   116  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.
   117  
   118  **DO NOT COPY `ca.key` TO INDIVIDUAL NODES.**
   119  
   120  #### 7. Run nebula on each host
   121  ```
   122  ./nebula -config /path/to/config.yml
   123  ```
   124  
   125  ## Building Nebula from source
   126  
   127  Make sure you have [go](https://go.dev/doc/install) installed and clone this repo. Change to the nebula directory.
   128  
   129  To build nebula for all platforms:
   130  `make all`
   131  
   132  To build nebula for a specific platform (ex, Windows):
   133  `make bin-windows`
   134  
   135  See the [Makefile](Makefile) for more details on build targets
   136  
   137  ## Curve P256 and BoringCrypto
   138  
   139  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.
   140  
   141  In addition, Nebula can be built using the [BoringCrypto GOEXPERIMENT](https://github.com/golang/go/blob/go1.20/src/crypto/internal/boring/README.md) by running either of the following make targets:
   142  
   143      make bin-boringcrypto
   144      make release-boringcrypto
   145  
   146  This is not the recommended default deployment, but may be useful based on your compliance requirements.
   147  
   148  ## Credits
   149  
   150  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.
   151  
   152  
   153