Skip to content

Commit 6ab4335

Browse files
mattkasunmattkasun
authored
Merge pull request #16 from devilcove/docs
Docs
2 parents aa8845e + 9746588 commit 6ab4335

31 files changed

+592
-1
lines changed

‎README.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
Plexus
2+
======
3+
![tests](https://github.com/devilcove/plexus/actions/workflows/integrationtest.yml/badge.svg)
4+
[![Go Report Card](https://goreportcard.com/badge/github.com/devilcove/pleuxs?style=flat-square)](https://goreportcard.com/report/github.com/devilcove/plexus)
5+
[![Go Reference](https://pkg.go.dev/badge/github.com/devilcove/plexus.svg)](https://pkg.go.dev/github.com/devilcove/plexus)
6+
7+
Plexus provides tools to easily manage private wireguard networks.
8+
9+
Overview
10+
========
11+
This repository provides the code for plexus-server and plexus-agent.
12+
Plexus-server serves the web ui and controls communications with plexus agents for peer and network updates.
13+
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.
14+
15+
QuickStart
16+
==========
17+
Server
18+
------
19+
* Requirements
20+
* linux VPS with minimum 1CPU/1GB memory (eg. $6 [DigitalOcean droplet](https://m.do.co/c/17e44f225e2e))
21+
* DNS record pointing to the IP of your server
22+
* systemd
23+
* tcp ports 443 and 4222 -- for server
24+
* udp ports 51820 -- for agent: additional ports are needed for each network
25+
* Download [install script](https://raw.githubusercontent.com/devilcove/plexus/master/scripts/install-server.sh)
26+
* make script executable (chmod +x install-server.sh)
27+
* run script (as root)
28+
* script will ask for
29+
* FQDN of server
30+
* email to use with [Let's Encrypt](https://letsencrypt.org)
31+
* name/password for web ui admin user
32+
* script will install and start plexus-server and plexus-agent daemons
33+
* log into server web ui
34+
* create registration key via web ui
35+
* create network via web ui
36+
* register agent(s) with server vi agent cli
37+
* join peer to network : can use server web ui or agent cli
38+
39+
Agent
40+
-----
41+
* Requirements
42+
* Linux host with systemd
43+
* Download [install script](https://raw.githubusercontent.com/devilcove/plexus/master/scripts/install-agent.sh)
44+
* make script executable (chmod +x install-server.sh)
45+
* run script (as root)
46+
* script will install and start plexus-agent daemon
47+
* copy registration key from server
48+
* register with server and join network
49+
```
50+
plexus-agent register <registraton key>
51+
plexus-agent join <network name>
52+
```
53+
54+
Tech Stack
55+
==========
56+
* Language: [Go](https://go.dev)
57+
* HTTP Framework: [Gin](https://github.com/gin-gonic/gin)
58+
* FrontEnd Framework: html/[htmx](https://htmx.org)
59+
* CSS Library: [w3schools](https://w3schools.com/w3css)
60+
* Database(key/value): [bbolt](https://github.com/etcd-io/bbolt)
61+
* Pub/Sub Broker: [nats.io](https://nats.io)
62+
* Automatic SSL Certificates: [certmagic](https://github.com/caddyserver/certmagic)
63+
64+
Docs
65+
====
66+
### [Installation](docs/install.md)
67+
### [Configuration](docs/configuration.md)
68+
### [Security](docs/security.md)
69+
### [Server](docs/server.md)
70+
### [Agent](docs/agent.md)
71+
72+
Legal
73+
=====
74+
WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.
75+
76+
Support
77+
=======
78+
Please use [Issues](https://github.com/devilcove/plexus/issues) or [Discussions](https://github.com/devilcove/plexus/discussions) for support requests
79+
80+
[![coffee](https://cdn.buymeacoffee.com/buttons/v2/default-blue.png)](https://www.buymeacoffee.com/mkasun)

‎app/plexus-server/html/about.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<div class="w3-container w3-center w3-theme-dark">
66
<img src="images/plexus.svg" alt="logo" height="75"><br>
77
<small>Version {{ .Version }}</small>
8-
<h3>&copy; 2023-2004 Matthew R. Kasun</h3>
8+
<h3>&copy; 2023-2024 Matthew R. Kasun</h3>
99
<small>built with
1010
<a href="https://go.dev" target="_blank">go</a>
1111
<a href="https://github.com/gin-gonic/" target="_blank">gin</a>

‎docs/agent.md

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
Plexus Agent CLI
2+
----------------
3+
4+
plexus-agent commands can be run by an ordinary user with exception of run commmand (agent daemon) which is intended to be run by plexus user
5+
```
6+
plexus agent to setup and manage plexus wireguard
7+
networks. Communicates with plexus server for network updates.
8+
CLI to join/leave networks.
9+
10+
Usage:
11+
plexus-agent [command]
12+
13+
Available Commands:
14+
completion Generate the autocompletion script for the specified shell
15+
drop unregister from server
16+
help Help about any command
17+
join join network
18+
leave leave network
19+
loglevel set log level of daemon (error, warn, info, debug)
20+
register register with a plexus server
21+
reload reload network configuration(s)
22+
reset reset interface peers for specified network
23+
run plexus-agent deamon
24+
status display status
25+
version display version information
26+
27+
Flags:
28+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
29+
-h, --help help for plexus-agent
30+
-v, --verbosity string logging verbosity (default "INFO")
31+
32+
Use "plexus-agent [command] --help" for more information about a command.
33+
```
34+
Register
35+
========
36+
The register command registers a peer with the plexus server.
37+
To use, copy a registration key token from the plexus server
38+
and run command
39+
40+
``` plexus-agent register <token> ```
41+
```
42+
register with a plexus server using token
43+
44+
Usage:
45+
plexus-agent register token [flags]
46+
47+
Flags:
48+
-h, --help help for register
49+
50+
Global Flags:
51+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
52+
-v, --verbosity string logging verbosity (default "INFO")
53+
```
54+
55+
Drop
56+
====
57+
The drop command will delete all networks and drop registration with server
58+
```
59+
unregister from server. Also deletes networks controlled by server
60+
61+
Usage:
62+
plexus-agent drop [flags]
63+
64+
Flags:
65+
-h, --help help for drop
66+
67+
Global Flags:
68+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
69+
-v, --verbosity string logging verbosity (default "INFO")
70+
```
71+
72+
Join
73+
====
74+
Join command joins an existing network
75+
```
76+
join network
77+
78+
Usage:
79+
plexus-agent join network [flags]
80+
81+
Flags:
82+
-h, --help help for join
83+
84+
Global Flags:
85+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
86+
-v, --verbosity string logging verbosity (default "INFO")
87+
```
88+
89+
Leave
90+
=====
91+
Leave network command deletes network on peer
92+
```
93+
Usage:
94+
plexus-agent leave network [flags]
95+
96+
Flags:
97+
-h, --help help for leave
98+
99+
Global Flags:
100+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
101+
-v, --verbosity string logging verbosity (default "INFO")
102+
Leave command deletes current network on peer
103+
```
104+
105+
Status
106+
======
107+
Status command displays infomation about server and networks/wireguard interfaces. The server information includes server endpoint and connectivity status. The network/wireguard interface information is displayed in a format similar to ```wg show``` but with additional information about networks/interfaces and peers.
108+
109+
Networks additional information
110+
* network name
111+
* network address
112+
* public listen port
113+
114+
Peers additional information
115+
* peer name
116+
* peer address
117+
```
118+
~> plexus-agent status
119+
Server
120+
nats://plexus.nusak.ca:4222 : true
121+
122+
interface: plexus0
123+
network name: plexus
124+
public key: p1AvfOzFgL2nEJrr8pvBeqEt+DPWGrcBfdHfKivjqVk=
125+
listen port: 51820
126+
public listen port: 51820
127+
address: 10.10.10.1
128+
peer: WhpdSseydj0jpJcNqsnzt8PZ93FUlpKFbR4ZyoUpVDo= winterfell 10.10.10.2
129+
endpoint: 129.222.192.188: 30403
130+
allowed ips: 10.10.10.2/32
131+
last handshake: 117.5493160.0 seconds ago
132+
transfer: 9980 sent 10328 received
133+
keepalive: 20s
134+
peer: pG8tT7Yj0e50JAk9MQw3vZuuN256ispkOfXDzzHC+kI= firefly 10.10.10.3
135+
endpoint: 140.238.132.144: 51820
136+
allowed ips: 10.10.10.3/32 10.225.211.0/24
137+
last handshake: 104.2563300.0 seconds ago
138+
transfer: 3216 sent 12336 received
139+
keepalive: 20s
140+
peer: vrn9w9h8CwmZ++M7BS6EBDSpUUdu+gOXPmp7lZX37m0= oracle 10.10.10.4
141+
endpoint: 150.230.31.118: 51820
142+
allowed ips: 10.10.10.4/32
143+
last handshake: 37.8089930.0 seconds ago
144+
transfer: 12364 sent 3272 received
145+
keepalive: 20s
146+
```
147+
Reload
148+
======
149+
Reload commands fetches fresh data from plexus server and reinitializes wireguard interfaces.
150+
```
151+
reload network configurations(s)
152+
153+
Usage:
154+
plexus-agent reload [flags]
155+
156+
Flags:
157+
-h, --help help for reload
158+
159+
Global Flags:
160+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
161+
-v, --verbosity string logging verbosity (default "INFO")
162+
```
163+
164+
Reset
165+
=====
166+
Reset command resets the wireguard interface for a given network
167+
```
168+
resets wg interface peers for given network
169+
170+
Usage:
171+
plexus-agent reset network [flags]
172+
173+
Flags:
174+
-h, --help help for reset
175+
176+
Global Flags:
177+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
178+
-v, --verbosity string logging verbosity (default "INFO")
179+
```
180+
181+
Version
182+
=======
183+
Version command displays version information:
184+
* semantic version number
185+
* git commit hash
186+
* local modifications to commit
187+
188+
-l --long flags displays version infomation for
189+
* current binary
190+
* agent daemon
191+
* server
192+
```
193+
plexus-agent version
194+
v0.1.0: git 2dee6a3b1e8551dc637bcbecd62d1a298b9c3f1f 2024-03-25T11:38:43Z true
195+
196+
plexus-agent version -l
197+
Server: v0.1.0: git 873255e5f846292c787fe4e332818592d6991baa 2024-03-31T13:51:06Z false
198+
Agent: v0.1.0: git 2dee6a3b1e8551dc637bcbecd62d1a298b9c3f1f 2024-03-25T11:38:43Z true
199+
Binary: v0.1.0: git 2dee6a3b1e8551dc637bcbecd62d1a298b9c3f1f 2024-03-25T11:38:43Z true
200+
```
201+
202+
LogLevel
203+
========
204+
LogLevel command sets the logging level of agent daemon
205+
```
206+
plexus-agent loglevel -h
207+
set log level of damemon
208+
debug, info, warn, or error
209+
.
210+
211+
Usage:
212+
plexus-agent loglevel level [flags]
213+
214+
Flags:
215+
-h, --help help for loglevel
216+
217+
Global Flags:
218+
--config string config file (default is /etc/plexus/plexus-agent.yaml)
219+
-v, --verbosity string logging verbosity (default "INFO")
220+
```
221+
222+
Run
223+
===
224+
Run command stars the plexus-agent daemon. It is intended to be called as systemd service. If it is run as an ordinary user it will fail with permission errors.
225+
226+
227+

‎docs/configuration.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Configuration
2+
=============
3+
Order of precedence
4+
1. Environment variable with prefix of PLEXUS_
5+
2. Configuration variables in file /etc/plexus/config.yml
6+
3. Default values
7+
8+
9+
Server
10+
------
11+
| Variable | Env | Default | Usage |
12+
| --- | ---- | ---- | --- |
13+
| adminname | PLEXUS_ADMINNAME | admin | default admin username |
14+
| adminpass | PLEXUS_ADMINPASS | password | password for default admin |
15+
| verbosity | PLEXUS_VERBOSITY | info | level for logs |
16+
| secure | PLEXUS_SECURE | true | use TLS for http and nats |
17+
| port | PLEXUS_PORT | 8080 | web listen port when secure is false |
18+
| email | PLEXUS_EMAIL | | email for use with Let's Encrypt |
19+
20+
* adminname/adminpass is only used to create a default user iff an admin user does not exist on server startup
21+
22+
Agent
23+
-----
24+
| Variable | Env | Default | Usage |
25+
| --- | ---- | ---- | --- |
26+
| verbosity | PLEXUS_VERBOSITY | info | level for logs |
27+
| natsport | PLEXUS_NATSPORT | 4223 | port for cli <-> agent nats comms |

0 commit comments

Comments
 (0)