plexus

README

Plexus

Plexus provides tools to easily manage private wireguard networks.

Overview

This repository provides the code for plexus-server and plexus-agent. Plexus-server serves the web ui and controls communications with plexus agents for peer and network updates. Plexus-agent runs as a daemon to communicate with the plexus server for peer and network updates. It also provided a cli to register and leave servers and to join/leave networks.

Quick Start

Server

• Requirements
  • linux VPS with minimum 1CPU/1GB memory (eg. $6 DigitalOcean droplet)
  • DNS record pointing to the IP of your server
  • systemd
  • tcp ports 443 and 4222 -- for server
  • udp ports 51820 -- for agent: additional ports are needed for each network
• Download install script
• make script executable (chmod +x install-server.sh)
• run script (as root)
  • script will ask for
    • FQDN of server
    • email to use with Let's Encrypt
    • name/password for web ui admin user
  • script will install and start plexus-server and plexus-agent daemons
• log into server web ui
• create registration key via web ui
• create network via web ui
• register agent(s) with server vi agent cli
• join peer to network : can use server web ui or agent cli

Agent

• Requirements
  • Linux host with systemd
• Download install script
• make script executable (chmod +x install-server.sh)
• run script (as root)
  • script will install and start plexus-agent daemon
• copy registration key from server
• register with server and join network

    plexus-agent register <registraton key>
    plexus-agent join <network name>

Tech Stack

• Language: Go
• HTTP Framework: Gin
• FrontEnd Framework: html/htmx
• CSS Library: w3schools
• Database(key/value): bbolt
• Pub/Sub Broker: nats.io
• Automatic SSL Certificates: certmagic

Docs

Installation

Configuration

Security

Server

Agent

Legal

WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

Support

Please use Issues or Discussions for support requests

Documentation

Index

• Constants
• func Get(name string) (*wireguard, error)
• func GetDevice(name string) (*wgtypes.Device, error)
• func New(name string, mtu int, address netlink.Addr, config wgtypes.Config) *wireguard
• func SetLogging(v string)
• type CheckinData
• type ConnectivityData
• type DeviceUpdate
• type ErrorResponse
• type JoinRequest
• type JoinResponse
• type Key
• type KeyValue
  • func DecodeToken(token string) (KeyValue, error)
• type LeaveRequest
• type LevelRequest
• type ListenPortRequest
• type ListenPortResponse
• type MessageResponse
• type NatsUser
• type Network
• type NetworkPeer
• type NetworkResponse
• type NetworkUpdate
• type Peer
• type PingResponse
• type PrivateEndpoint
• type RegisterRequest
• type ResetRequest
• type ServerJoinRequest
• type ServerRegisterRequest
• type User
• type VersionResponse

Constants

const (
	DeletePeer         = ".deletePeer"
	AddRouter          = ".addRouter"
	AddPeer            = ".addPeer"
	UpdatePeer         = ".updatePeer"
	UpdateNetworkPeer  = ".updateNetworkPeer"
	UpdateListenPorts  = ".updateListenPorts"
	AddRelay           = ".addRelay"
	DeleteRelay        = ".deleteRelay"
	DeleteRouter       = ".deleteRouter"
	DeleteNetwork      = ".deleteNetwork"
	JoinNetwork        = ".join"
	LeaveNetwork       = ".leaveNetwork"
	LeaveServer        = ".leaveServer"
	LogLevel           = ".loglevel"
	Ping               = ".ping"
	Register           = ".register"
	Reload             = ".reload"
	Reset              = ".reset"
	SetPrivateEndpoint = ".privateEndpoint"
	Status             = ".status"
	Version            = ".version"
	Checkin            = ".checkin"
	SendListenPorts    = ".listenPorts"
	Update             = "update."
	Networks           = "networks."
)

nats topics

Functions

func Get

func Get(name string) (*wireguard, error)

Get returns an existing wireguard interface as a plexus.Wireguard

func GetDevice

func GetDevice(name string) (*wgtypes.Device, error)

GetDevice returns a wireguard device as wgtype.Device

func New

func New(name string, mtu int, address netlink.Addr, config wgtypes.Config) *wireguard

New returns a new wireguard interface

func SetLogging

func SetLogging(v string)

Types

type CheckinData

type CheckinData struct {
	ID               string
	Version          string
	ListenPort       int
	PublicListenPort int
	Endpoint         net.IP
	PrivateEndpoints []PrivateEndpoint
	Connections      []ConnectivityData
}

type ConnectivityData

type ConnectivityData struct {
	Network      string
	Connectivity float64
}

type DeviceUpdate

type DeviceUpdate struct {
	Action  string
	Server  string
	Network Network
}

type ErrorResponse

type ErrorResponse struct {
	Message string
}

type JoinRequest

type JoinRequest struct {
	Network          string
	ListenPort       int
	PublicListenPort int
	Peer
}

type JoinResponse

type JoinResponse struct {
	Message string
	Network Network
}

type Key

type Key struct {
	Name    string `form:"name"`
	Value   string
	Usage   int `form:"usage"`
	Expires time.Time
	DispExp string `form:"expires"`
}

type KeyValue

type KeyValue struct {
	URL     string
	Seed    string
	KeyName string
}

func DecodeToken

func DecodeToken(token string) (KeyValue, error)

type LeaveRequest

type LeaveRequest struct {
	Network string
}

type LevelRequest

type LevelRequest struct {
	Level string
}

type ListenPortRequest

type ListenPortRequest struct {
	Network string
}

type ListenPortResponse

type ListenPortResponse struct {
	Message          string
	ListenPort       int
	PublicListenPort int
}

type MessageResponse

type MessageResponse struct {
	Message string
}

type NatsUser

type NatsUser struct {
	Kind      string
	Name      string
	Subscribe []string
	Publish   []string
}

type Network

type Network struct {
	Name          string `form:"name"`
	Net           net.IPNet
	AddressString string `form:"addressstring"`
	Peers         []NetworkPeer
}

type NetworkPeer

type NetworkPeer struct {
	WGPublicKey        string
	HostName           string
	Address            net.IPNet
	ListenPort         int
	PublicListenPort   int
	Endpoint           net.IP
	PrivateEndpoint    net.IP
	UsePrivateEndpoint bool
	NatsConnected      bool
	Connectivity       float64
	IsRelay            bool
	RelayedPeers       []string
	IsRelayed          bool
	IsSubnetRouter     bool
	Subnet             net.IPNet
	UseNat             bool
	UseVirtSubnet      bool
	VirtSubnet         net.IPNet
}

type NetworkResponse

type NetworkResponse struct {
	Message  string
	Networks []Network
}

type NetworkUpdate

type NetworkUpdate struct {
	Action string
	Peer   NetworkPeer
}

type Peer

type Peer struct {
	WGPublicKey   string
	PubNkey       string
	Version       string
	Name          string
	OS            string
	Endpoint      net.IP
	Updated       time.Time
	NatsConnected bool
}

type PingResponse

type PingResponse struct {
	Message string
}

type PrivateEndpoint

type PrivateEndpoint struct {
	IP      string
	Network string
}

type RegisterRequest

type RegisterRequest struct {
	Token string
}

type ResetRequest

type ResetRequest struct {
	Network string
}

type ServerJoinRequest

type ServerJoinRequest struct {
	Network Network
}

type ServerRegisterRequest

type ServerRegisterRequest struct {
	KeyName string
	Peer
}

type User

type User struct {
	Username string `json:"username" form:"username"`
	Password string `json:"password" form:"password"`
	IsAdmin  bool
	Updated  time.Time
}

type VersionResponse

type VersionResponse struct {
	Server string
	Agent  string
}