restructure, create overview

doc/0-chirpstack/0-prerequisites.md

@@ -0,0 +1 @@
+# ChirpStack Server Prerequisites

doc/0-chirpstack/1-chirpstack.md

@@ -0,0 +1,69 @@
+# ChirpStack
+
+Reference install instructions: <https://www.chirpstack.io/docs/getting-started/debian-ubuntu.html>
+
+Additional instructions/tips not on the official site:
+
+To install the ChirpStack GPG key, use this instead of what's on the ChirpStack documentation page:
+
+```sh
+# https://superuser.com/a/1773782
+gpg --keyserver hkps://keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00 && \
+gpg --export 1CE2AFD36DBCCA00 | sudo tee /etc/apt/trusted.gpg.d/chirpstack.gpg >/dev/null && \
+gpg --batch --yes --delete-keys 1CE2AFD36DBCCA00
+```
+
+Don't install the `chirpstack-gateway-bridge` here; just do `chirpstack`.
+
+Edit `/etc/chirpstack/chirpstack.toml` as needed (specifically the PostgreSQL config). Add the missing US regions.
+
+## Nginx + TLS setup
+
+Install Lego
+
+Get certificate (using DNS-01 + ACME-DNS)
+
+Setup certificate for autorenewal and auto-reload Nginx
+
+Set Nginx config to have two files:
+
+`default`:
+
+```nginx
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+
+    server_name _;
+
+    return 301 https://$host$request_uri;
+}
+```
+
+`chirpstack`:
+
+```nginx
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    ssl_protocols TLSv1.2 TLSv1.3;
+    
+    ssl_certificate /var/www-certs/chirpstack.roeber.dev.crt;
+    ssl_certificate_key /var/www-certs/chirpstack.roeber.dev.key;
+
+    server_name chirpstack.roeber.dev;
+
+    server_tokens off; # disable banner
+
+    location / {
+        proxy_pass http://localhost:8080;
+    }
+}
+```
+
+Symlink `chirpstack` to be active: `sudo ln -s /etc/nginx/sites-available/chirpstack /etc/nginx/sites-enabled/chirpstack`
+
+Reload Nginx: `sudo systemctl reload nginx`
+
+(Optional) Run [`testssl.sh`](https://github.com/drwetter/testssl.sh/) to verify security: clone, then `./testssl.sh chirpstack.roeber.dev`

doc/0-chirpstack/2-mosquitto-tls.md

@@ -0,0 +1,65 @@
+# Mosquitto TLS Setup
+
+Ref: <https://www.chirpstack.io/docs/guides/mosquitto-tls-configuration.html>
+
+You generate a certificate authority which has the following purposes:
+
+- Generate a Mosquitto server certificate so gateways can connect to it via TLS
+- Generate client certificates for gateways so they can prove their identity to the Mosquitto server
+
+When you create the CA, three files are generated:
+
+- `ca.csr`
+- `ca.pem`
+- `ca-key.pem`
+
+Then when you create the MQTT cert, three more files are generated:
+
+- `mqtt-server.csr`
+- `mqtt-server.pem`
+- `mqtt-server-key.pem`
+
+Then you add the CA (with its key) to the ChirpStack config. Make sure to change ownership to `chirpstack` when copying certs to `/etc/chirpstack/certs`.
+
+Then create a folder for MQTT cert and copy files.
+
+Set ownership and permission on the key:
+
+```sh
+chown root:mosquitto /etc/mosquitto/certs/mqtt-server-key.pem
+chmod 640 /etc/mosquitto/certs/mqtt-server-key.pem
+```
+
+Once set up, you can create a Gateway in ChirpStack and generate a TLS certificate. It is only shown after being created; clicking the TLS tab again later will not show the cert but will let you generate a new one. Certs don't seem to be stored anywhere.
+
+Don't forget to allow `8883` in the firewall.
+
+## Gateway Bridge Config
+
+Create `/etc/chirpstack-gateway-bridge/certs` folder and copy certs in. Make everything owned by `gatewaybridge`. Set permission to `640`.
+
+Modify the config, ref: <https://www.chirpstack.io/docs/chirpstack-gateway-bridge/configuration.html>
+
+Don't forget to change `tcp` to `ssl` in the server list.
+
+Check `journalctl` on both the bridge and Mosquitto to see that the connection is established.
+
+Be sure to set the Gateway ID in both the `chirpstack-gateway-bridge` and `packet-forwarder` configs (though this doesn't seem to matter? Need to experiment). Also be sure the UDP port matches between the two.
+
+## Troubleshooting
+
+Install `mosquitto-clients` on the Gateway.
+
+Send a message to the `test` topic:
+
+```sh
+mosquitto_pub \
+  -h chirpstack.roeber.dev \
+  -p 8883 \
+  --cafile /etc/chirpstack-gateway-bridge/certs/ca.crt \
+  --cert /etc/chirpstack-gateway-bridge/certs/cert.crt \
+  --key /etc/chirpstack-gateway-bridge/certs/cert.key \
+  -t "test" \
+  -d \
+  -m "hello"
+```