Feat/start wrt

landing/index.html

@@ -149,6 +149,14 @@ <h2>Bitcoin Guides</h2>
           StartOS.
         </p>
       </a>
+
+      <a class="card" href="/start-wrt/">
+        <h2>StartWRT</h2>
+        <p>
+          A router operating system for home-based self-hosting, built on
+          OpenWrt.
+        </p>
+      </a>
     </div>
 
     <footer>

serve.sh

@@ -28,6 +28,7 @@ echo "  Landing:     http://localhost:3000/"
 echo "  StartOS:     http://localhost:3000/start-os/"
 echo "  StartTunnel: http://localhost:3000/start-tunnel/"
 echo "  Packaging:   http://localhost:3000/packaging/"
+echo "  StartWRT:    http://localhost:3000/start-wrt/"
 echo ""
 echo "To live-reload a single book while editing, run in another terminal:"
 echo "  cd $BOOK && mdbook serve -p 3001"

start-wrt/accent.css

@@ -0,0 +1,4 @@
+.ayu {
+  --links: #c678dd;
+  --sidebar-active: #c678dd;
+}

start-wrt/book.toml

@@ -0,0 +1,39 @@
+[book]
+authors = ["Start9"]
+language = "en"
+src = "src"
+title = "StartWRT"
+
+[build]
+build-dir = "../docs/start-wrt"
+
+[preprocessor.tabs]
+
+[output]
+
+[output.html]
+sidebar-header-nav = false
+admonitions = true
+no-section-label = false
+default-theme = "ayu"
+preferred-dark-theme = "ayu"
+additional-css = [
+    "./theme/docs-agent.css",
+    "./theme/youtube.css",
+    "./theme/tabs.css",
+    "./accent.css"
+]
+additional-js = [
+    "./theme/docs-agent-init.js",
+    "./theme/docs-agent.js",
+    "./theme/youtube.js",
+    "./theme/tabs.js",
+    "./theme/home-link.js"
+]
+git-repository-url = "https://github.com/start9labs/docs"
+edit-url-template = "https://github.com/start9labs/docs/edit/master/start-wrt/{path}"
+site-url = "/start-wrt/"
+
+[output.html.fold]
+enable = true
+level = 0

start-wrt/src/README.md

@@ -0,0 +1,47 @@
+# StartWRT Documentation
+
+StartWRT is a router operating system designed specifically for home-based self-hosting. Built on OpenWrt, it pairs a hardened networking backend with a modern web interface that makes advanced features — VPN chaining, per-device security profiles, Wi-Fi schedules, dynamic DNS — accessible to everyone.
+
+## Getting Started
+
+- [Installing StartWRT](installing.md)
+- [Initial Setup](initial-setup.md)
+- [Trusting Your Root CA](trust-ca.md)
+- [Updating](updating.md)
+
+## Core Concepts
+
+- [Security Profiles](security-profiles.md)
+- [Points of Entry](points-of-entry.md)
+
+## Internet
+
+- [WAN Settings](wan.md)
+- [Dynamic DNS](ddns.md)
+- [Published Ports](published-ports.md)
+- [Outbound VPNs](outbound-vpn.md)
+
+## Network
+
+- [LAN Settings](lan.md)
+- [Devices](devices.md)
+
+## Points of Entry
+
+- [Ethernet](ethernet.md)
+- [Wi-Fi](wifi.md)
+- [Wi-Fi Schedules](wifi-schedules.md)
+- [Inbound VPNs](inbound-vpn.md)
+
+## System
+
+- [Settings](settings.md)
+- [SSH Access](ssh.md)
+- [Backups](backups.md)
+- [Factory Reset](factory-reset.md)
+
+## Reference
+
+- [CGNAT](cgnat.md)
+- [Architecture](architecture.md)
+- [FAQ](faq.md)

start-wrt/src/SUMMARY.md

@@ -0,0 +1,61 @@
+# Summary
+
+[StartWRT Documentation](README.md)
+
+---
+
+# Getting Started
+
+- [Installing StartWRT](installing.md)
+- [Initial Setup](initial-setup.md)
+- [Trusting Your Root CA](trust-ca.md)
+- [Updating](updating.md)
+
+---
+
+# Core Concepts
+
+- [Security Profiles](security-profiles.md)
+- [Points of Entry](points-of-entry.md)
+
+---
+
+# Internet
+
+- [WAN Settings](wan.md)
+- [Dynamic DNS](ddns.md)
+- [Published Ports](published-ports.md)
+- [Outbound VPNs](outbound-vpn.md)
+
+---
+
+# Network
+
+- [LAN Settings](lan.md)
+- [Devices](devices.md)
+
+---
+
+# Points of Entry
+
+- [Ethernet](ethernet.md)
+- [Wi-Fi](wifi.md)
+- [Wi-Fi Schedules](wifi-schedules.md)
+- [Inbound VPNs](inbound-vpn.md)
+
+---
+
+# System
+
+- [Settings](settings.md)
+- [SSH Access](ssh.md)
+- [Backups](backups.md)
+- [Factory Reset](factory-reset.md)
+
+---
+
+# Reference
+
+- [CGNAT](cgnat.md)
+- [Architecture](architecture.md)
+- [FAQ](faq.md)

start-wrt/src/architecture.md

@@ -0,0 +1,58 @@
+# Architecture
+
+StartWRT is a router operating system built on OpenWrt with a custom Rust backend and Angular web interface. It reimagines the router experience by abstracting raw networking primitives — VLANs, firewall zones, subnets, routing tables — behind the [Security Profile](security-profiles.md) model. The result is enterprise-grade network segmentation that anyone can configure in minutes.
+
+## What StartWRT Adds to OpenWrt
+
+OpenWrt is a powerful open-source router OS, but it exposes raw networking primitives through its LuCI interface. Configuring VLANs, firewall zones, and multi-password Wi-Fi requires understanding how these systems interact at a low level. StartWRT keeps OpenWrt's battle-tested networking stack and adds:
+
+- **Security Profiles** — A single abstraction that replaces manual VLAN, firewall, subnet, and routing configuration. One click creates an isolated network segment with its own DHCP, DNS, firewall rules, and VPN routing.
+- **Multi-password Wi-Fi** — One SSID with multiple passwords, each mapping to a different Security Profile. No separate SSIDs, no manual VLAN tagging.
+- **VPN chaining** — Route traffic through multiple VPN providers in sequence for multi-jurisdictional privacy.
+- **Modern web interface** — A purpose-built Angular UI that manages the full router configuration without requiring CLI knowledge. The underlying OpenWrt CLI and LuCI remain available for advanced users.
+- **OTA updates** — Firmware updates delivered through the web interface.
+
+## How It Works
+
+StartWRT has three components:
+
+- **OpenWrt** — The base operating system. Handles kernel-level networking, Wi-Fi drivers, and package management.
+- **Rust backend** — A single binary (`startwrt`) that runs as the RPC server and CLI. It manages all configuration, service reloads, TLS certificates, authentication, and system operations.
+- **Angular frontend** — A single-page application embedded in the backend binary. Communicates with the backend over JSON-RPC 2.0.
+
+All persistent configuration lives in UCI files under `/etc/config/` — the same configuration system used by stock OpenWrt. There is no separate database. The backend reads and writes these files atomically, so the CLI, LuCI, and the StartWRT web interface all share a single source of truth.
+
+## Security Profile Internals
+
+When you create a [Security Profile](security-profiles.md), the backend orchestrates changes across multiple UCI config files:
+
+| UCI Config | What Changes |
+|------------|-------------|
+| `network` | New bridge interface, VLAN, and subnet |
+| `firewall` | New zone with inter-zone forwarding rules |
+| `dhcp` | New DHCP server for the profile's subnet |
+| `wireless` | New PSK entry in `wpa_psk_file` (for Wi-Fi passwords) |
+
+This is why the web interface never exposes raw VLANs or firewall rules — the profile abstraction handles all of it consistently.
+
+## Network Isolation
+
+Device isolation uses bridge VLAN filtering at Layer 2. Each Security Profile is assigned a unique VLAN ID. Traffic is tagged at the entry point (Ethernet port, Wi-Fi password, or VPN server) and can only reach destinations within the same VLAN unless the firewall explicitly allows inter-zone traffic.
+
+## Multi-Password Wi-Fi
+
+StartWRT's multi-password Wi-Fi uses WPA2's identity PSK feature with dynamic VLAN assignment. Each password in the PSK file is associated with a VLAN ID. When a device authenticates, the router matches the password, looks up the VLAN, and places the device on the correct network segment — all transparently.
+
+## Security
+
+- **Admin password** — Stored as a SHA-512 hash
+- **Sessions** — Random token with 1-day expiry; HTTP-only SameSite=Strict cookie
+- **Rate limiting** — 3 login attempts per 20 seconds
+- **SSH** — Public key authentication or password auth (Admin password)
+- **TLS** — rustls with a Root CA certificate chain
+
+## Source Code
+
+The StartWRT source code lives in the [start-wrt repository](https://github.com/Start9Labs/start-wrt).
+
+To report bugs or request features, [open an issue](https://github.com/Start9Labs/start-wrt/issues).

start-wrt/src/backups.md

@@ -0,0 +1,46 @@
+# Backups
+
+Back up your router's configuration so you can restore it after an update, factory reset, or hardware failure. Backups capture your settings — security profiles, Wi-Fi passwords, firewall rules, VPN configurations, SSH keys, and other customizations.
+
+## Creating a Backup
+
+1. Navigate to `System > Settings > Backup`.
+
+1. Click "Create Backup".
+
+1. A backup file will be downloaded to your computer.
+
+Store the backup file in a safe location, such as a password manager or encrypted drive.
+
+> [!TIP]
+> Create a backup before performing firmware updates. While the "Keep Settings" path preserves settings, having a backup provides an extra safety net.
+
+## Restoring a Backup
+
+1. Navigate to `System > Settings > Backup`.
+
+1. Click "Restore Backup".
+
+1. Select the backup file from your computer.
+
+1. Click "Restore".
+
+The router will apply the configuration and restart.
+
+> [!WARNING]
+> Restoring a backup overwrites your current configuration entirely. Any changes made since the backup was created will be lost.
+
+## What Is Included
+
+| Included | Not Included |
+|----------|--------------|
+| Security Profiles | System logs |
+| Wi-Fi passwords | Device history |
+| Published Ports | Data usage counters |
+| Ethernet port assignments | |
+| Inbound and Outbound VPN configs | |
+| SSH keys | |
+| DDNS settings | |
+| LAN/WAN settings | |
+| Admin password | |
+| Router name, timezone, language | |

start-wrt/src/cgnat.md

@@ -0,0 +1,51 @@
+# CGNAT (Carrier-Grade NAT)
+
+CGNAT is a networking technique where your ISP places your home network behind an additional layer of NAT that you do not control. If your ISP uses CGNAT, several StartWRT features will not work.
+
+## What Is CGNAT?
+
+Normally, your router is assigned a public IP address by your ISP. This allows devices on the Internet to initiate connections to your router, which can then forward them to devices on your LAN.
+
+With CGNAT, your ISP does _not_ give your router a public IP. Instead, many customers share a single public IP managed by the ISP's equipment. Your router's "WAN IP" is actually a private address on the ISP's internal network. Because you don't control the ISP's NAT, no one on the Internet can initiate a connection to your router.
+
+## Who Is Affected?
+
+CGNAT is common with:
+
+- **Satellite Internet** — Starlink, HughesNet, Viasat
+- **Cellular/fixed wireless** — T-Mobile Home Internet, Verizon Home Internet, and similar 4G/5G home broadband services
+- **Some fiber and cable ISPs** — particularly in regions with IPv4 address shortages
+
+## Impact on StartWRT
+
+CGNAT blocks all inbound connections to your router. This significantly limits StartWRT's feature set:
+
+- **[Inbound VPNs](inbound-vpn.md)** — VPN servers need to accept connections from the Internet. Behind CGNAT, remote devices cannot reach your router.
+- **[Published Ports](published-ports.md)** — Port forwarding requires a public IP. Rules will show "Error" or "Partial" status behind CGNAT.
+- **[Dynamic DNS](ddns.md)** — DDNS maps a domain to your IP, but if that IP is behind CGNAT, the domain still cannot receive inbound connections.
+
+CGNAT does **not** affect:
+
+- **Local network access** — Devices on your LAN connect directly, bypassing the ISP entirely.
+- **[Outbound VPNs](outbound-vpn.md)** — Outbound connections are not blocked by CGNAT.
+- **All other StartWRT features** — Security Profiles, Wi-Fi management, Ethernet configuration, WAN Schedules, and backups work normally.
+
+## The Solution: StartTunnel
+
+[StartTunnel](/start-tunnel/) is a virtual private router (VPR) — a minimal, self-hosted router that runs on a VPS with a public IP address. Your devices connect _outbound_ to the VPS, and the VPS accepts inbound connections on their behalf. Because the VPS has a real public IP, CGNAT is completely bypassed.
+
+## How to Check
+
+Compare your router's WAN IP with your actual public IP:
+
+1. In StartWRT, navigate to `Internet > WAN Settings` and note your WAN IP address.
+
+1. Visit a site like [whatismyip.com](https://whatismyip.com) from a device on the same network.
+
+1. If the two addresses **match**, you are _not_ behind CGNAT. If they **differ**, you are likely behind CGNAT.
+
+> [!TIP]
+> Another indicator: if your router's WAN IP is in the `100.64.0.0/10` range (100.64.x.x through 100.127.x.x), that is the CGNAT address block defined by RFC 6598 and confirms you are behind CGNAT.
+
+> [!NOTE]
+> Some ISPs offer a way to opt out of CGNAT, either through a support request or by purchasing a static IP add-on. Check with your ISP before assuming CGNAT is permanent.

start-wrt/src/ddns.md

@@ -0,0 +1,44 @@
+# Dynamic DNS
+
+Dynamic DNS (DDNS) maps a stable domain name to your home IP address, even when your ISP changes it. This is essential for remote access features like [Inbound VPNs](inbound-vpn.md) and [Published Ports](published-ports.md), which require external devices to find your router on the Internet.
+
+## Why You Need DDNS
+
+Most home Internet connections have a dynamic IP address that can change without warning. When your IP changes, any remote VPN clients or port forwarding rules pointing to the old IP stop working. DDNS automatically updates a domain name to point to your current IP, so remote connections keep working.
+
+## Start9 Dynamic DNS
+
+StartWRT includes free integration with Start9's Dynamic DNS service. No account is required.
+
+1. Navigate to `Internet > WAN Settings > DDNS`.
+
+1. Select **Start9** as the provider.
+
+1. Click "Enable". A unique domain name will be assigned to your router automatically.
+
+> [!TIP]
+> The Start9 DDNS domain is all you need for VPN access. You do not need to own a custom domain name.
+
+## Other Providers
+
+StartWRT also supports third-party DDNS providers:
+
+- Cloudflare
+- DuckDNS
+- Dyn
+- FreeDNS
+- No-IP
+
+To use a third-party provider:
+
+1. Navigate to `Internet > WAN Settings > DDNS`.
+
+1. Select the provider and enter your credentials or API token.
+
+1. Enter the domain name or hostname you have registered with the provider.
+
+1. Click "Save".
+
+## Checking Your DDNS Status
+
+The DDNS section on the WAN Settings page shows the current status of your dynamic DNS configuration, including the domain name, the IP address it points to, and when it was last updated.