Starship 🚀

Overview

Caution

THIS PROJECT IS NOT PRODUCTION READY.

The goal of this project is to provide a config and certificate management system for nebula. This project was done in a short amount of time and it is my first project using golang. I would not recommend using it without auditing it first.

Quasar Server

Overview

Quasar is a Central Management System (CMS) for managing Starship networks. It provides APIs for two types of clients:

• Neutron Nodes

  • These authenticate by signing requests using their nebula private key

• Frontend clients / management tools

  • These authenticate using JSON Web Tokens

Quasar can be configured using a yaml config file.

The API for neutron nodes provides the following endpoints:

The API for management clients provides endpoints for:

• listing networks

• getting CA cert for a network

• listing nodes in a network

• updating network settings

• updating node settings

• approving / enabling / disabling nodes

Installation Instructions

make quasar

Operating Instructions

# set JWT signing secret
export QUASAR_AUTHSECRET=$(uuid)

# set admin account password
export QUASAR_ADMINPASS="password"

# start server
./quasar serve -config examples/quasar.yml

Neutron

Overview

Neutron is a client which Starship nodes use to request to join networks, and update their configuration and certificates.

When joining a new network, Neutron will create a new Nebula keypair. It will then send a request to Quasar to join a specific network. This request includes the node name, the network it wants to join, its hostname and its Nebula public key. This information is sent as a JSON payload, signed using the Nebula private key. This is encoded similarly to a PASETO token. PASETO tokens are similar to JSON Web Tokens (JWTs), however do not suffer the same vulnerabilities JWTs suffer due to the vague protocol specification.

When updating, Neutron will send requests to Quasar to obtain an updated certificate and configuration file. For Quasar to send these, Neutron must include a signed token which includes it’s nodename and the network name it is trying to update, and the node must be approved and active on the Quasar server. The signature on the token is verified against the public key stored for the node on the Quasar server.

The update script can be run at frequent intervals to keep the node updated with the most recent configuration changes.

Installation Instructions

# build
cd starship

# equivalent of `go build -o neutron cmd/neutron/*.go`
make neutron

Operating Instructions

Manual install

# request to join network
./neutron join -quasar http://127.0.0.1:6947 -network NETWORK -name NAME

# approve node from frontend then fetch latest config from Quasar
./neutron update -network NETWORK
# send SIGHUP to nebula to force config reload
pgrep nebula | xargs sudo kill -1

Using Install Script

# quick install from release
wget https://github.com/b177y/starship/releases/download/v0.3.0/install-neutron.sh -O /tmp/install-neutron.sh

# check content
less /tmp/install-neutron.sh
bash /tmp/install-neutron.sh

# approve node from frontend then fetch latest config from Quasar
neutron update -network NETWORK

# start nebula with systemd
sudo systemctl start nebula@NETWORK

# send SIGHUP to nebula to force config reload
pgrep nebula | xargs sudo kill -1

Hubble

Hubble is the frontend for managing Starship networks. See hubble/README.adoc for setup instructions.