From bd2a54b94eae96510bb577392cee5174b7ea95d2 Mon Sep 17 00:00:00 2001 From: Shadowy Super Coder Date: Thu, 2 Apr 2026 15:22:04 -0600 Subject: [PATCH 1/3] start-wrt initial draft --- start-wrt/accent.css | 4 + start-wrt/book.toml | 39 +++++++ start-wrt/src/README.md | 46 ++++++++ start-wrt/src/SUMMARY.md | 60 ++++++++++ start-wrt/src/architecture.md | 89 +++++++++++++++ start-wrt/src/backups.md | 47 ++++++++ start-wrt/src/cli-reference.md | 65 +++++++++++ start-wrt/src/ddns.md | 44 ++++++++ start-wrt/src/devices.md | 33 ++++++ start-wrt/src/ethernet.md | 48 ++++++++ start-wrt/src/factory-reset.md | 44 ++++++++ start-wrt/src/faq.md | 46 ++++++++ start-wrt/src/inbound-vpn.md | 169 +++++++++++++++++++++++++++++ start-wrt/src/initial-setup.md | 41 +++++++ start-wrt/src/installing.md | 125 +++++++++++++++++++++ start-wrt/src/lan.md | 28 +++++ start-wrt/src/outbound-vpn.md | 75 +++++++++++++ start-wrt/src/points-of-entry.md | 19 ++++ start-wrt/src/published-ports.md | 59 ++++++++++ start-wrt/src/security-profiles.md | 110 +++++++++++++++++++ start-wrt/src/settings.md | 70 ++++++++++++ start-wrt/src/ssh.md | 53 +++++++++ start-wrt/src/updating.md | 42 +++++++ start-wrt/src/wan.md | 58 ++++++++++ start-wrt/src/wifi-schedules.md | 35 ++++++ start-wrt/src/wifi.md | 72 ++++++++++++ start-wrt/theme | 1 + versions.conf | 1 + 28 files changed, 1523 insertions(+) create mode 100644 start-wrt/accent.css create mode 100644 start-wrt/book.toml create mode 100644 start-wrt/src/README.md create mode 100644 start-wrt/src/SUMMARY.md create mode 100644 start-wrt/src/architecture.md create mode 100644 start-wrt/src/backups.md create mode 100644 start-wrt/src/cli-reference.md create mode 100644 start-wrt/src/ddns.md create mode 100644 start-wrt/src/devices.md create mode 100644 start-wrt/src/ethernet.md create mode 100644 start-wrt/src/factory-reset.md create mode 100644 start-wrt/src/faq.md create mode 100644 start-wrt/src/inbound-vpn.md create mode 100644 start-wrt/src/initial-setup.md create mode 100644 start-wrt/src/installing.md create mode 100644 start-wrt/src/lan.md create mode 100644 start-wrt/src/outbound-vpn.md create mode 100644 start-wrt/src/points-of-entry.md create mode 100644 start-wrt/src/published-ports.md create mode 100644 start-wrt/src/security-profiles.md create mode 100644 start-wrt/src/settings.md create mode 100644 start-wrt/src/ssh.md create mode 100644 start-wrt/src/updating.md create mode 100644 start-wrt/src/wan.md create mode 100644 start-wrt/src/wifi-schedules.md create mode 100644 start-wrt/src/wifi.md create mode 120000 start-wrt/theme diff --git a/start-wrt/accent.css b/start-wrt/accent.css new file mode 100644 index 0000000..0d572b5 --- /dev/null +++ b/start-wrt/accent.css @@ -0,0 +1,4 @@ +.ayu { + --links: #c678dd; + --sidebar-active: #c678dd; +} diff --git a/start-wrt/book.toml b/start-wrt/book.toml new file mode 100644 index 0000000..df61c24 --- /dev/null +++ b/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 diff --git a/start-wrt/src/README.md b/start-wrt/src/README.md new file mode 100644 index 0000000..b535eb3 --- /dev/null +++ b/start-wrt/src/README.md @@ -0,0 +1,46 @@ +# 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, WiFi schedules, dynamic DNS — accessible to everyone. + +## Getting Started + +- [Installing StartWRT](installing.md) +- [Initial Setup](initial-setup.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) +- [WiFi 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 + +- [Architecture](architecture.md) +- [CLI Reference](cli-reference.md) +- [FAQ](faq.md) diff --git a/start-wrt/src/SUMMARY.md b/start-wrt/src/SUMMARY.md new file mode 100644 index 0000000..05fc133 --- /dev/null +++ b/start-wrt/src/SUMMARY.md @@ -0,0 +1,60 @@ +# Summary + +[StartWRT Documentation](README.md) + +--- + +# Getting Started + +- [Installing StartWRT](installing.md) +- [Initial Setup](initial-setup.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) +- [WiFi 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 + +- [Architecture](architecture.md) +- [CLI Reference](cli-reference.md) +- [FAQ](faq.md) diff --git a/start-wrt/src/architecture.md b/start-wrt/src/architecture.md new file mode 100644 index 0000000..0e4c317 --- /dev/null +++ b/start-wrt/src/architecture.md @@ -0,0 +1,89 @@ +# Architecture + +StartWRT is a fork of OpenWrt with a custom Rust backend and Angular web interface. It reimagines the router experience by abstracting raw networking primitives (VLANs, firewall zones, routing tables) behind the [Security Profile](security-profiles.md) model. + +## Components + +- **OpenWrt** — The base operating system. Handles kernel-level networking, WiFi drivers, and package management. StartWRT uses a fork targeting the SpacemiT K1 / BananaPi BPI-F3 board. +- **Rust backend** — A single binary (`startwrt`) that runs as both the RPC server (daemon mode) and the CLI. It manages all UCI 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 via a single endpoint (`/rpc/v1`). + +## Data Flow + +``` +Browser (Angular SPA) + → HTTP POST /rpc/v1 (JSON-RPC 2.0, session cookie) + → Axum router (ports 80/443) + → Session auth middleware + → RPC handler + → UCI config read/write + → Service reload (e.g. /etc/init.d/network reload) + → JSON-RPC response +``` + +The frontend never touches UCI files, shell commands, or system services directly. Every operation goes through a purpose-built RPC method on the backend. + +## UCI as Source of Truth + +All persistent configuration lives in UCI files under `/etc/config/`. There is no separate database. The backend reads and writes these files using a custom Rust UCI parser (`uciedit`) that provides: + +- **Typed access** — Compile-time-safe access to UCI sections via `#[derive(TypedSection)]` +- **Atomic writes** — Temp file, write, fsync, rename pattern to prevent corruption +- **Conflict detection** — Mtime checking with automatic retry on concurrent writes + +## 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 WiFi passwords) | + +This is why the web interface never exposes raw VLANs or firewall rules — the profile abstraction handles all of it consistently. + +## VLAN 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, WiFi password, or VPN server) and can only reach destinations within the same VLAN unless the firewall explicitly allows inter-zone traffic. + +This approach works identically whether the router uses a hardware switch (DSA) or software bridging. + +## Authentication + +- **Admin password** — Stored as a SHA-512 hash in `/etc/shadow` +- **Sessions** — Random token (base32) stored as SHA-256 hash in `/etc/startwrt/sessions.json`; 1-day expiry; HTTP-only SameSite=Strict cookie +- **Rate limiting** — 3 login attempts per 20 seconds +- **SSH** — Public key authentication only (no password auth) +- **CLI auth** — Local auth cookie generated at daemon startup in `/run/startwrt/rpc.authcookie` + +## WiFi Identity PSK + +StartWRT's multi-password WiFi uses WPA2's `wpa_psk_file` with dynamic VLAN assignment. Each password in the PSK file is associated with a VLAN ID. When a device authenticates, hostapd matches the password, looks up the VLAN, and places the device on the correct bridge interface — all transparently. + +``` +WiFi Interface (SSID: "StartWRT") +├── Sticker password → dynamic_vlan = ALLOWED → default LAN +├── "guest-pass" → VLAN 101 → Guest profile subnet +├── "kids-pass" → VLAN 102 → Children profile subnet +└── "iot-pass" → VLAN 103 → Smart Devices profile subnet +``` + +## Tech Stack + +| Component | Technology | +|-----------|-----------| +| Base OS | OpenWrt (SpacemiT K1 target) | +| Backend | Rust (Tokio, Axum, rpc-toolkit) | +| Frontend | Angular 21, TypeScript 5.9, Taiga UI v5 | +| Config storage | UCI files (`/etc/config/`) | +| API protocol | JSON-RPC 2.0 over HTTP | +| VPN | WireGuard (kernel module) | +| TLS | rustls (Root CA → Intermediate → Server cert 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). diff --git a/start-wrt/src/backups.md b/start-wrt/src/backups.md new file mode 100644 index 0000000..d59ac72 --- /dev/null +++ b/start-wrt/src/backups.md @@ -0,0 +1,47 @@ +# 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, WiFi 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 Update 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 | Admin password | +| WiFi passwords | System logs | +| Firewall rules | Device history | +| VPN server and client configs | Data usage counters | +| SSH keys | | +| DDNS settings | | +| LAN/WAN settings | | +| Router name, timezone, language | | + +> [!NOTE] +> The admin password is never included in backups. After restoring, you will use the admin password you set during the restore process, not the one from the backup. diff --git a/start-wrt/src/cli-reference.md b/start-wrt/src/cli-reference.md new file mode 100644 index 0000000..b3500e7 --- /dev/null +++ b/start-wrt/src/cli-reference.md @@ -0,0 +1,65 @@ +# CLI Reference + +The StartWRT router includes a CLI accessible over [SSH](ssh.md). The `startwrt` binary provides subcommands for manufacturing, firmware management, and diagnostics. Day-to-day router configuration is done through the [web interface](initial-setup.md#explore-the-web-interface) — the CLI is for advanced operations and recovery scenarios. + +## startwrt init + +Provision the WiFi password during manufacturing. This is a local-only command run via serial console at the factory. + +``` +startwrt init +``` + +Prompts for the 12-character WiFi password (from the device sticker), validates the character set, and writes it to the eMMC `/key_backup` partition and the WiFi configuration. + +> [!NOTE] +> This command is only available when booted from microSD and no WiFi password exists on the eMMC. It is not used during normal operation. + +## startwrt flash + +Flash firmware from a microSD image to the router's internal eMMC storage. + +``` +startwrt flash +``` + +Used during manufacturing and the reflash wizard. Writes kernel, root filesystem, and overlay partitions to eMMC. + +## startwrt manufacture + +Run the full manufacturing flow (flash + init) in sequence. + +``` +startwrt manufacture +``` + +## startwrt verify + +Verify the integrity of the installed firmware. + +``` +startwrt verify +``` + +## startwrt has-baked-password + +Check whether the current boot image has a custom WiFi password baked in. + +``` +startwrt has-baked-password +``` + +Returns exit code 0 if a baked-in password is present, non-zero otherwise. + +## startwrt-bake-password + +A separate Python utility (not part of the main `startwrt` binary) that embeds a custom WiFi password into a StartWRT firmware image. Use this if you have lost the original sticker password and need to create a recovery image. + +``` +startwrt-bake-password +``` + +The resulting image can be written to a microSD card and used to reflash the router. The baked-in password replaces the original sticker password permanently. + +> [!WARNING] +> After flashing with a custom image, the original sticker password no longer works. The password you baked in becomes the new WiFi password. Update the sticker or store the new password securely. diff --git a/start-wrt/src/ddns.md b/start-wrt/src/ddns.md new file mode 100644 index 0000000..476f4d3 --- /dev/null +++ b/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. diff --git a/start-wrt/src/devices.md b/start-wrt/src/devices.md new file mode 100644 index 0000000..c513959 --- /dev/null +++ b/start-wrt/src/devices.md @@ -0,0 +1,33 @@ +# Devices + +The Devices page shows all devices that have connected to your router, organized into Online (currently connected) and Offline (previously seen) groups. Each device is associated with a [Security Profile](security-profiles.md) based on its [point of entry](points-of-entry.md). + +## Viewing Devices + +Navigate to `Network > Devices` to see the device list. Each entry shows: + +- **Name** — The device's hostname or a custom name you have assigned. Click to open the device detail page. +- **Connection** — How the device connects: Ethernet, Wi-Fi 2.4 GHz, Wi-Fi 5 GHz, or VPN. +- **MAC address** — The device's unique hardware identifier. +- **IP address** — The device's IPv4 and IPv6 addresses. A lock icon indicates a reserved (static) IP address. +- **Data and Speed** — Cumulative data usage and real-time upload/download speed for online devices. + +## Device Detail Page + +Click a device name to open its detail page: + +- **Summary** — Displays the device's current status (online/offline), connection type, [Security Profile](security-profiles.md), IPv4 and IPv6 addresses, and real-time upload/download speed. + +- **Data Usage** — A chart showing historical upload and download over time. Use the dropdown to select a time period: Last 24 Hours, Last Week, Last 30 Days, or Last 3 Months. + +- **Name** — Edit the custom display name for this device. If left empty, the device's hostname is used. + +- **Reserved IP** — Toggle on to assign a fixed IPv4 address that persists across reboots. Enter the desired IP address within the device's profile subnet. Useful for servers, printers, NAS devices, or any device that needs a consistent address. + +- **Forget** — Remove an offline device from the list. Custom name and reserved IP settings are lost. If the device reconnects, it will appear as a new entry. + +> [!TIP] +> Reserve an IP for any device you plan to use with [Published Ports](published-ports.md). Port forwarding rules require a stable IP address to ensure traffic always reaches the correct device. + +> [!NOTE] +> Forgetting a device only removes it from the list. If the device reconnects, it will reappear. diff --git a/start-wrt/src/ethernet.md b/start-wrt/src/ethernet.md new file mode 100644 index 0000000..758cbdd --- /dev/null +++ b/start-wrt/src/ethernet.md @@ -0,0 +1,48 @@ +# Ethernet + +Each physical Ethernet port on the StartWRT router maps to a [Security Profile](security-profiles.md). The port a device plugs into determines its profile — no manual configuration is needed on the device itself. + +## How It Works + +When a device is plugged into an Ethernet port, the router assigns it to the profile mapped to that port. The device receives an IP address on that profile's subnet and is subject to that profile's firewall rules, VPN routing, and schedule restrictions. + +Behind the scenes, StartWRT uses bridge VLAN filtering to isolate traffic between ports. Each port tags traffic with a different VLAN ID, ensuring devices on different profiles cannot communicate at Layer 2 unless explicitly allowed. + +## WAN Port + +One Ethernet port is designated as the WAN port, which connects to your ISP modem or upstream network. The WAN port is shown with a "WAN" badge in the port list and cannot be assigned a Security Profile. + +## Assigning Profiles to Ports + +1. Navigate to `Points of Entry > Ethernet`. + +1. For each non-WAN port, select the desired Security Profile from the dropdown. + +1. Click "Save". + +> [!NOTE] +> Changes take effect immediately. A device currently plugged into a port will be reassigned to the new profile without needing to unplug and replug. + +## Changing the WAN Port + +If you need to use a different physical port for your ISP connection: + +1. Navigate to `Points of Entry > Ethernet`. + +1. Click "Change WAN Port". + +1. Select the new port. + +1. Confirm the change. + +> [!WARNING] +> Changing the WAN port interrupts your Internet connection and restarts the router. Ensure your modem cable is connected to the new port before confirming. + +## Example + +| Port | Profile | Use Case | +|------|---------|----------| +| Port 1 | *(WAN)* | Connected to ISP modem | +| Port 2 | Admin | Desktop computer with full LAN and Internet access | +| Port 3 | Admin | StartOS server with full LAN and Internet access | +| Port 4 | Guest | Guest-accessible Ethernet jack in the living room | diff --git a/start-wrt/src/factory-reset.md b/start-wrt/src/factory-reset.md new file mode 100644 index 0000000..e7fbf16 --- /dev/null +++ b/start-wrt/src/factory-reset.md @@ -0,0 +1,44 @@ +# Factory Reset + +A factory reset restores StartWRT to its default state. There are two ways to reset: from the web interface (soft reset) or from a microSD card (reflash). + +## Soft Reset (Web Interface) + +A soft reset wipes the configuration overlay and reboots the router. The firmware itself is not reinstalled. + +1. Navigate to `System > Settings`. + +1. Click "Factory Reset". + +1. Confirm the action. + +The router will reboot. After reboot: + +- WiFi works immediately using the original sticker password (restored from the router's internal storage). +- The admin password is cleared — you will be prompted to create a new one via the captive portal. +- All settings (security profiles, VPN configs, firewall rules, SSH keys) are wiped. + +> [!IMPORTANT] +> A factory reset cannot be undone. Create a [backup](backups.md) first if you want to preserve your settings. + +## Reflash (microSD) + +A microSD reflash replaces the firmware entirely and offers two options: + +- **Update** — Installs new firmware while preserving settings. See [Updating](updating.md). +- **Fresh Start** — Wipes everything and installs a clean copy of StartWRT. Equivalent to a factory reset plus a firmware reinstall. + +See [Installing StartWRT](installing.md) for instructions on creating a bootable microSD card. + +## What Gets Wiped + +| Soft Reset | Fresh Start (microSD) | +|------------|----------------------| +| All settings and customizations | All settings and customizations | +| Admin password | Admin password | +| Firmware unchanged | Firmware replaced | +| WiFi password preserved (from eMMC) | WiFi password preserved (from eMMC, or replaced if using a custom image) | + +## Lost WiFi Password + +If you have lost the WiFi password printed on your router's sticker, you can create a custom firmware image with a new WiFi password baked in. Use the `startwrt-bake-password` tool to embed a new password, then reflash with the custom image. The baked-in password permanently replaces the original sticker password. See the [CLI Reference](cli-reference.md) for details. diff --git a/start-wrt/src/faq.md b/start-wrt/src/faq.md new file mode 100644 index 0000000..0843422 --- /dev/null +++ b/start-wrt/src/faq.md @@ -0,0 +1,46 @@ +# FAQ + +Answers to common questions about StartWRT's features, security model, and compatibility. + +## What is StartWRT? + +StartWRT is a router operating system built on OpenWrt, designed specifically for home-based self-hosting. It replaces traditional networking concepts (VLANs, firewall rules, routing tables) with [Security Profiles](security-profiles.md) — a simple model where how a device connects determines what it can access. + +## How is StartWRT different from stock OpenWrt? + +Stock OpenWrt exposes raw networking primitives through the LuCI interface, requiring users to understand VLANs, firewall zones, and routing tables. StartWRT abstracts all of this behind Security Profiles and provides a modern web interface that makes advanced features accessible without CLI expertise. Under the hood, StartWRT still uses OpenWrt's networking stack — the difference is entirely in the management layer. + +## How does multi-password WiFi work? + +StartWRT uses WPA2's identity PSK feature. A single SSID (`StartWRT`) accepts multiple passwords, each mapped to a different Security Profile. When a device connects, the router identifies which password was used and places the device on the corresponding VLAN and subnet automatically. See [Wi-Fi](wifi.md) for details. + +## Is VPN chaining really more private? + +Yes, with caveats. VPN chaining routes traffic through multiple providers so that no single provider sees both your identity (home IP) and your destination. However, if the providers collaborate or are compelled by law enforcement across jurisdictions, correlation is still theoretically possible. For most users, the practical benefit is significant — especially when chaining providers in different legal jurisdictions. See [Outbound VPNs](outbound-vpn.md) for setup instructions. + +## Does StartWRT work with my ISP? + +StartWRT supports DHCP, static IP, and PPPoE WAN connections, which covers the vast majority of ISPs. If your ISP uses CGNAT, you can still use all local features, but inbound connections (VPN servers, port forwarding) will not work without a gateway like [StartTunnel](/start-tunnel/). See [WAN Settings](wan.md) for configuration details. + +## Can I still use the OpenWrt CLI? + +Yes. StartWRT is built on OpenWrt, and the full CLI is accessible over [SSH](ssh.md). You can use `opkg` to install packages, edit UCI files directly, and run standard Linux networking tools. Changes made via the CLI are respected by the web interface. + +## What happens if I forget my admin password? + +You have two options: + +1. **Factory reset** — Press and hold the reset button or perform a [factory reset](factory-reset.md) from the web interface (if you are still logged in). This wipes all settings but preserves the WiFi password. +2. **Reflash** — Boot from a microSD card and choose "Update" to reinstall the firmware while preserving settings. You will be prompted to create a new admin password. See [Installing StartWRT](installing.md). + +## What if I lose my WiFi sticker password? + +Use the `startwrt-bake-password` tool to create a custom firmware image with a new WiFi password, then reflash from microSD. The new password permanently replaces the sticker password. See the [CLI Reference](cli-reference.md) for details. + +## Does StartWRT phone home or collect telemetry? + +No. StartWRT has no telemetry, no analytics, and no phone-home behavior. The only outbound connection the router initiates on your behalf is to check for firmware updates (if enabled) and to register with a Dynamic DNS provider (if configured). Both are optional and user-initiated. + +## Can I use StartWRT with StartOS? + +Absolutely. StartWRT and [StartOS](/start-os/) are complementary products. StartOS runs your self-hosted services; StartWRT handles the networking. Together, they provide a complete self-hosting stack with proper network isolation, VPN access, and port forwarding — all without touching a command line. diff --git a/start-wrt/src/inbound-vpn.md b/start-wrt/src/inbound-vpn.md new file mode 100644 index 0000000..1a6af27 --- /dev/null +++ b/start-wrt/src/inbound-vpn.md @@ -0,0 +1,169 @@ +# Inbound VPNs + +Create WireGuard VPN servers on your router for secure remote access to your home network. Each VPN server maps to a [Security Profile](security-profiles.md), so remote devices receive the same access controls as if they were physically connected. + +## How It Works + +An inbound VPN server listens for WireGuard connections from the Internet. When a remote device connects, it is assigned the VPN server's Security Profile — gaining access to the LAN, Internet, or both, according to that profile's rules. This is like giving someone a key to a specific door in your house rather than handing them the master key. + +> [!IMPORTANT] +> Inbound VPN requires either a public IP address or [Dynamic DNS](ddns.md) so remote devices can reach your router. If your ISP uses CGNAT, inbound connections cannot reach your router directly. Consider using [StartTunnel](/start-tunnel/) as a gateway instead. + +## Creating a VPN Server + +1. Navigate to `Points of Entry > Inbound VPNs` and click "Add". + +1. Configure the server: + + - **Label** — A descriptive name (e.g. "Home VPN", "Friends", "Work"). + - **Endpoint** — The address where remote clients will connect. Select from available options: WAN IPv4 address, WAN IPv6 address, or a DDNS domain (if [Dynamic DNS](ddns.md) is configured). If you have a dynamic IP, use a DDNS domain so clients do not need to update their configuration when your IP changes. + - **Security Profile** — The [Security Profile](security-profiles.md) to assign to connecting clients. + - **Port** — The WireGuard listen port (default: `51820`). Must be unique across all VPN servers. If the default is already in use, the next available port is suggested. + +1. Click "Save". + +## Managing Clients + +Each VPN server has a client management page listing all peers. Navigate to a VPN server and click "Manage clients" from the actions menu to view the client list, which shows each peer's name, LAN IP address, and routing mode. + +### Adding a Client + +1. Select the VPN server and click "Add". + +1. Configure the client: + + - **Label** — A name for the client (e.g. "My iPhone", "Work Laptop"). + - **LAN IP Address** — The IP address assigned to this client on the VPN subnet. + - **Public Key** — (Optional) Enter an existing WireGuard public key if the device already has a keypair configured. Leave empty to auto-generate a keypair. + - **Route all traffic through tunnel** — When enabled, all of the client's Internet traffic routes through the VPN (full tunnel). When disabled (the default), only LAN traffic uses the tunnel and the client uses its own Internet connection for everything else (split tunnel). + +1. A WireGuard configuration is generated. + +### Viewing Client Configuration + +After creating a client, the configuration can be viewed in two formats: + +- **File** — Displays the configuration as text. Use the copy button to copy to clipboard, or the download button to save as a `.conf` file that WireGuard apps can import. +- **QR** — Displays the configuration as a QR code. Scan with the WireGuard mobile app to configure the client without manual entry. + +> [!TIP] +> Save the configuration file to your password manager. If you lose it, you will need to remove the client and create a new one. + +### Changing Client Routing + +After creating a client, you can switch between routing modes from the actions menu on the client list: + +- **All traffic** — Full tunnel. All Internet traffic routes through the VPN. +- **LAN only** — Split tunnel. Only local network traffic uses the tunnel. + +### Renaming a Client + +Select "Rename" from the client's actions menu to change its display name. + +### Removing a Client + +Select "Delete" from the client's actions menu. The client's WireGuard configuration is immediately invalidated. + +## Connecting Remote Devices + +Install WireGuard on the remote device and import the configuration file. + +{{#tabs global="platform"}} + +{{#tab name="Mac"}} + +1. Install WireGuard from the [App Store](https://apps.apple.com/us/app/wireguard/id1451685025). + +1. Open WireGuard, click "Import tunnel(s) from file", and select the config file. + +1. MacOS will ask you to allow the VPN configuration. Click "Allow". + +1. Activate the tunnel from the WireGuard app or from System Settings > VPN. + +{{#endtab}} + +{{#tab name="Windows"}} + +1. Install WireGuard from the [official website](https://www.wireguard.com/install/). + +1. Click "Import tunnel(s) from file" and select the config file. + +1. Click "Activate" to connect. + +{{#endtab}} + +{{#tab name="iOS"}} + +1. Install WireGuard from the [App Store](https://itunes.apple.com/us/app/wireguard/id1441195209?ls=1&mt=8). + +1. Tap "Add a tunnel" and either scan the QR code or import the config file. + +1. Allow the VPN configuration when prompted. + +1. Toggle the tunnel on to connect. + +{{#endtab}} + +{{#tab name="Android / Graphene"}} + +1. Install WireGuard from the [Play Store](https://play.google.com/store/apps/details?id=com.wireguard.android) or the [WireGuard website](https://www.wireguard.com/install/). + +1. Tap the `+` button and either scan the QR code or import the config file. + +1. Allow the VPN connection when prompted. + +{{#endtab}} + +{{#tab name="Linux"}} + +1. Install WireGuard: + - Debian / Ubuntu: `sudo apt update && sudo apt install wireguard` + - Fedora / RHEL: `sudo dnf update && sudo dnf install wireguard-tools` + - Arch / Manjaro: `sudo pacman -Syu && sudo pacman -S wireguard-tools wireguard` + +1. Copy the config file: + + ``` + sudo cp myconfig.conf /etc/wireguard/wg0.conf + sudo chmod 600 /etc/wireguard/wg0.conf + ``` + +1. Connect: + + ``` + sudo wg-quick up wg0 + ``` + +1. Verify: + + ``` + sudo wg + ``` + +1. (Optional) Enable on boot: + + ``` + sudo systemctl enable wg-quick@wg0 + ``` + +> [!TIP] +> To disconnect: `sudo wg-quick down wg0` + +{{#endtab}} + +{{#endtabs}} + +## Removing a VPN Server + +1. Navigate to `Points of Entry > Inbound VPNs` and select "Delete" from the server's actions menu. + +> [!WARNING] +> Deleting a VPN server immediately disconnects all clients and invalidates their configuration files. Clients will need new config files if a new server is created. + +## Example + +| VPN Server | Profile | Endpoint | Use Case | +|------------|---------|----------|----------| +| Primary | Admin | DDNS domain | Your personal remote access to everything | +| Family | Shared Services | DDNS domain | Family members accessing the home server | +| Friends | Guest | DDNS domain | Friends using your Internet connection via VPN | diff --git a/start-wrt/src/initial-setup.md b/start-wrt/src/initial-setup.md new file mode 100644 index 0000000..97aac14 --- /dev/null +++ b/start-wrt/src/initial-setup.md @@ -0,0 +1,41 @@ +# Initial Setup + +After unboxing your Start9 router or completing a fresh install, follow these steps to get up and running. The entire process takes just a few minutes. + +## Connect to WiFi + +1. Power on the router. + +1. On your phone or computer, connect to the `StartWRT` WiFi network using the password printed on the sticker on the bottom of the device. + +## Create Your Admin Password + +1. A captive portal will open automatically. If it does not, open a browser and navigate to any URL — you will be redirected to the setup page. + +1. Create an admin password (minimum 12 characters). This password protects the web interface and is separate from the WiFi password. + +1. Confirm the password and click "Submit". + +1. Normal Internet access will resume and you will be logged in to the StartWRT web interface. + +> [!IMPORTANT] +> All Internet access is blocked until you set an admin password. If you dismiss the captive portal popup, open any browser and navigate to any URL to reach the setup page. + +## Explore the Web Interface + +The StartWRT web interface is organized into five sections: + +- **Internet** — WAN settings, published ports, outbound VPNs +- **Network** — LAN settings, connected devices +- **Security Profiles** — Create and manage access control profiles +- **Points of Entry** — Ethernet ports, WiFi passwords, inbound VPN servers +- **System** — General settings, SSH keys, backups, logs + +> [!TIP] +> Toggle **Help Mode** from the header to get a plain-language explanation of everything on the current page, including links to external resources. + +## Next Steps + +- [Security Profiles](security-profiles.md) — Understand the core concept behind StartWRT +- [Wi-Fi](wifi.md) — Set up additional WiFi passwords for different profiles +- [Settings](settings.md) — Configure timezone, language, and other preferences diff --git a/start-wrt/src/installing.md b/start-wrt/src/installing.md new file mode 100644 index 0000000..9ede927 --- /dev/null +++ b/start-wrt/src/installing.md @@ -0,0 +1,125 @@ +# Installing StartWRT + +StartWRT comes pre-installed on Start9 routers. If you need to reinstall or flash a new device, follow the instructions below to create a bootable microSD card and flash the firmware. + +## Requirements + +- A Start9 router (BananaPi BPI-F3) +- A microSD card (4 GB or larger) +- A computer to write the image + +## Download the Image + +Download the latest StartWRT firmware image from the [Start9 releases page](https://github.com/Start9Labs/start-wrt/releases). + +## Write the Image to microSD + +{{#tabs global="platform"}} + +{{#tab name="Mac"}} + +1. Insert the microSD card into your computer. + +1. Open the Terminal app and identify the disk: + + ``` + diskutil list + ``` + + Find your microSD card (e.g. `/dev/disk4`). Be absolutely sure you have the correct disk. + +1. Unmount the disk: + + ``` + diskutil unmountDisk /dev/disk4 + ``` + +1. Write the image: + + ``` + sudo dd if=startwrt.img of=/dev/rdisk4 bs=1m + ``` + + Replace `startwrt.img` with the path to the downloaded file and `/dev/rdisk4` with your disk (note the `r` prefix for raw device, which is faster). + +1. Eject the card: + + ``` + diskutil eject /dev/disk4 + ``` + +{{#endtab}} + +{{#tab name="Windows"}} + +1. Download and install [balenaEtcher](https://etcher.balena.io/). + +1. Insert the microSD card into your computer. + +1. Open balenaEtcher, select the downloaded StartWRT image, select your microSD card, and click "Flash". + +1. When complete, safely eject the microSD card. + +{{#endtab}} + +{{#tab name="Linux"}} + +1. Insert the microSD card into your computer. + +1. Identify the device: + + ``` + lsblk + ``` + + Find your microSD card (e.g. `/dev/sdb`). Be absolutely sure you have the correct device. + +1. Unmount any mounted partitions: + + ``` + sudo umount /dev/sdb* + ``` + +1. Write the image: + + ``` + sudo dd if=startwrt.img of=/dev/sdb bs=1M status=progress + ``` + + Replace `startwrt.img` with the path to the downloaded file and `/dev/sdb` with your device. + +1. Sync and remove the card: + + ``` + sync + ``` + +{{#endtab}} + +{{#endtabs}} + +## Flash the Firmware + +1. Power off the router. + +1. Insert the microSD card into the router. + +1. Power on the router. It will boot from the microSD card automatically. + +1. Connect to the `StartWRT` WiFi network using the password printed on the sticker on the bottom of the device. + +1. A captive portal will open automatically. If it does not, open a browser and navigate to any URL — you will be redirected to the setup wizard. + +1. Choose one of the following: + + - **Update** — Replaces the firmware while preserving your settings. You will be prompted to create a new admin password. + - **Fresh Start** — Wipes everything and installs a clean copy of StartWRT. You will be prompted to select a language, country, and drive, then create a new admin password. + +1. When the wizard completes, power off the router, remove the microSD card, and power it back on. + +> [!TIP] +> If you have lost the WiFi password on the sticker, you can build a custom image with a new password baked in using the `startwrt-bake-password` tool. See the [CLI Reference](cli-reference.md) for details. + +## Next Steps + +- [Initial Setup](initial-setup.md) — Set up your admin password and configure the router diff --git a/start-wrt/src/lan.md b/start-wrt/src/lan.md new file mode 100644 index 0000000..3280c1f --- /dev/null +++ b/start-wrt/src/lan.md @@ -0,0 +1,28 @@ +# LAN Settings + +The LAN (Local Area Network) page configures the router's internal network addressing. Most users will not need to change these settings — the defaults work for typical home networks. Navigate to `Network > LAN Settings`. + +## IPv4 + +Configure the router's LAN IPv4 addressing. + +- **Network Block** — Select the `/16` private IP block for your network. The first octet determines the block: `192.168.x.x`, `10.0.x.x`, or `172.16.x.x`. Each [Security Profile](security-profiles.md) receives its own `/24` subnet within this block, allowing up to 256 separate subnets with 254 devices each. + +- **Router IP** — The router's address within the default subnet. The first two octets are determined by the Network Block, the third octet is configurable (0–254), and the fourth octet is always `1`. For example, with the `192.168.x.x` block and third octet `1`, the router's IP is `192.168.1.1`. This is the address you use to access the web interface. + +> [!NOTE] +> DHCP is managed automatically for each Security Profile. You do not need to configure DHCP ranges or lease times. + +> [!WARNING] +> Changing the Network Block or Router IP changes the router's LAN address. You will need to navigate to the new address to access the web interface. If any inbound VPN servers exist, they will be deleted because their client configurations become invalid with the new addressing. + +## IPv6 + +Configure IPv6 for the LAN if your ISP supports it. + +- **SLAAC** — Toggle to enable or disable IPv6 on the LAN via Stateless Address Autoconfiguration. When enabled, devices generate their own IPv6 addresses from the router's advertised prefix. + +- **Prefix Length** — Shown when SLAAC is enabled. The LAN IPv6 prefix length must be larger (a higher number) than your WAN prefix to create a valid subnet. For example, if your ISP assigns you a `/48` prefix, you can use `/56`, `/60`, or `/64` for the LAN. A `/64` is recommended for most home networks. + +> [!NOTE] +> LAN IPv6 requires WAN IPv6 to be enabled first. See [WAN Settings](wan.md#ipv6). If published port rules use IPv6, SLAAC cannot be disabled until those rules are removed. diff --git a/start-wrt/src/outbound-vpn.md b/start-wrt/src/outbound-vpn.md new file mode 100644 index 0000000..5b29a2f --- /dev/null +++ b/start-wrt/src/outbound-vpn.md @@ -0,0 +1,75 @@ +# Outbound VPNs + +Route your network's Internet traffic through one or more WireGuard VPN providers for privacy. Outbound VPNs hide your home IP address from the services your devices connect to and prevent your ISP from monitoring traffic. + +## Adding a VPN Client + +1. Navigate to `Internet > Outbound VPNs` and click "Add". + +1. Configure the VPN: + + - **Label** — A descriptive name (e.g. "Mullvad Sweden", "Proton US"). + - **Config File** — Upload or paste a WireGuard `.conf` file from your VPN provider. Most providers (Mullvad, ProtonVPN, IVPN, etc.) offer WireGuard config file downloads from their account dashboard. + - **Target** — Where this VPN's traffic should be routed: + - **Internet** — Traffic exits directly to the Internet through this VPN. + - **Another VPN** — Chain through another VPN first for additional privacy. Select the target VPN from the dropdown. Only VPNs that would not create a circular chain are shown. + +1. Click "Save". + +> [!TIP] +> Download a config file for a VPN server location near you for best performance. + +## VPN Chaining + +VPN chaining routes traffic through multiple VPN providers in sequence, so no single provider sees both your identity and your destination. This achieves multi-jurisdictional resilience — the providers would need to collaborate across different legal jurisdictions to correlate your activity. + +Chaining is configured through the **Target** field. When you set a VPN's target to another VPN instead of "Internet", traffic flows through both: + +``` +Your device → StartWRT → First VPN → Second VPN → Internet +``` + +For example, if "Mullvad" targets "Proton" and "Proton" targets "Internet": +- Mullvad knows your home IP but not your destination. +- Proton knows your destination but sees Mullvad's IP, not yours. + +> [!NOTE] +> VPN chaining adds latency since traffic passes through multiple servers. For most users, a single VPN provider is sufficient. + +## VPN Detail Page + +Click a VPN label in the table to open its detail page, which shows: + +- **Connection Path** — The full route traffic takes from this VPN to the Internet (e.g. "Mullvad → Proton → Internet"). +- **Used by** — Which [Security Profiles](security-profiles.md) currently route their traffic through this VPN. Check this before making changes to understand the impact. +- **Label** — Edit the display name. +- **Connects to** — Change the target (Internet or another VPN). + +To delete a VPN, click "Delete" on its detail page. + +> [!NOTE] +> You cannot delete a VPN if other VPNs use it as a target. Change their target first. + +## Enabling and Disabling + +Each VPN has an enable/disable toggle in the table view. When a VPN is disabled, profiles that route through it will fall back to the WAN (direct Internet). + +> [!NOTE] +> You cannot disable a VPN if other VPNs use it as a target. Change their target first. + +## Assigning VPNs to Profiles + +By default, all [Security Profiles](security-profiles.md) use the router's default gateway (your ISP) for Internet traffic. You can override this per profile: + +1. Navigate to `Security Profiles` and select a profile. + +1. Under **Outbound Routing**, select a VPN client. + +1. Click "Save". + +This lets you route different profiles through different VPNs. For example: + +- **Admin** profile routes through Mullvad +- **Children** profile routes through a DNS-filtering VPN +- **Guest** profile routes through Proton +- **Smart Devices** profile uses the default gateway (no VPN) diff --git a/start-wrt/src/points-of-entry.md b/start-wrt/src/points-of-entry.md new file mode 100644 index 0000000..dd1e656 --- /dev/null +++ b/start-wrt/src/points-of-entry.md @@ -0,0 +1,19 @@ +# Points of Entry + +A point of entry is how a device connects to the StartWRT network and receives its [Security Profile](security-profiles.md). There are three types of entry points, each mapping to a profile. + +## Ethernet + +Each physical Ethernet port on the router maps to a Security Profile. The port a device plugs into determines its profile. See [Ethernet](ethernet.md). + +## Wi-Fi + +StartWRT uses one WiFi network (one SSID) with multiple passwords. Each password maps to a different Security Profile. The password a device uses to join the network determines its profile. See [Wi-Fi](wifi.md). + +## Inbound VPN + +Each WireGuard VPN server on the router maps to a Security Profile. Remote devices connect to a VPN server and receive the corresponding profile, as if they were physically present on the network. See [Inbound VPNs](inbound-vpn.md). + +## Why Entry Points Matter + +Traditional routers require you to think in terms of VLANs, firewall rules, and subnets. StartWRT replaces all of that with a simple mental model: **how you connect determines what you can access**. Whether a device plugs into a specific Ethernet port, uses a specific WiFi password, or connects through a specific VPN server, the result is the same — it gets assigned a profile that governs its network access. diff --git a/start-wrt/src/published-ports.md b/start-wrt/src/published-ports.md new file mode 100644 index 0000000..880ffdc --- /dev/null +++ b/start-wrt/src/published-ports.md @@ -0,0 +1,59 @@ +# Published Ports + +Published ports (port forwarding) allow devices on the Internet to reach specific devices on your LAN. Each rule maps a port on the router's public IP address to a port on a device behind the router. + +## When to Use Port Forwarding + +- **Self-hosting** — Expose a web server, email server, or other service running on a LAN device. +- **Remote access** — Allow external access to a specific device or application. +- **Gaming** — Open ports required by game servers or peer-to-peer connections. + +> [!IMPORTANT] +> Port forwarding exposes devices directly to the Internet. Only forward ports for services you intend to be publicly accessible. For private remote access, use [Inbound VPNs](inbound-vpn.md) instead. + +## Creating a Rule + +1. Navigate to `Internet > Published Ports` and click "Add". + +1. Configure the rule: + + - **Label** — A descriptive name (e.g. "Home Assistant", "Minecraft Server", "Bitcoin P2P"). + - **Device** — Select the target device from the list. The device is identified by name and IP address. If the device does not already have a reserved IPv4 address, one will be assigned automatically to ensure the rule always reaches the correct device. + - **Port** — The port or port range on the device to expose. Enter a single port (e.g. `443`) or a range (e.g. `27015-27030`). + - **Protocol** — TCP, UDP, or TCP + UDP. + - **Source** — Who can connect. Select **Any** to allow connections from anywhere on the Internet, or **Custom** to restrict access to a specific IP address or CIDR range (e.g. `203.0.113.0/24`). + - **IP Version** — IPv4, IPv6, or IPv4 + IPv6. Options may be disabled if the device lacks an address for that version or if WAN IPv6 is not configured. + - **External Port** (IPv4 only) — **Same as device** keeps the external port identical to the internal port. Select **Other** to specify a different external port (e.g. forward WAN port `9090` to device port `8080`). + +1. Click "Save". + +## Editing a Rule + +1. Navigate to `Internet > Published Ports` and select "Edit" from the rule's actions menu. + +1. Modify any settings and click "Save". + +## Enabling and Disabling Rules + +Each rule can be toggled on and off without deleting it. Use the "Enable" or "Disable" option in the rule's actions menu. + +## Deleting a Rule + +1. Navigate to `Internet > Published Ports` and select "Delete" from the rule's actions menu. + +## Status Indicators + +Each published port rule shows a status indicator in the table: + +- **Active** (green) — The rule is working and traffic is being forwarded. +- **Partial** (yellow) — The rule is partially working. For example, IPv4 forwarding may be unavailable because your ISP uses CGNAT, while IPv6 is functioning normally. +- **Paused** (orange) — The target device is offline or not reachable. +- **Error** (red) — The rule failed to apply. +- **Disabled** (grey) — The rule has been toggled off. + +## Endpoints + +The **Endpoints** column in the table shows the public addresses where each forwarded port can be reached. IPv4 endpoints display the router's public IP (or DDNS domain) with the external port. IPv6 endpoints display the device's IPv6 address with the port directly. These are useful for configuring external services or sharing access details. + +> [!NOTE] +> Port forwarding requires a public IP address. If your ISP uses CGNAT, IPv4 forwarding will not work — the rule will show a "Partial" status if IPv6 is available, or "Error" if not. Check with your ISP or use [Dynamic DNS](ddns.md) with a publicly routable IP. diff --git a/start-wrt/src/security-profiles.md b/start-wrt/src/security-profiles.md new file mode 100644 index 0000000..94f52c3 --- /dev/null +++ b/start-wrt/src/security-profiles.md @@ -0,0 +1,110 @@ +# Security Profiles + +Security Profiles are the core concept in StartWRT. Every device on the network is assigned a Security Profile that governs what it can access — LAN devices, the Internet, DNS servers, VPN tunnels, and time-of-day restrictions. Profiles replace the need to manually configure VLANs, firewall zones, subnets, and routing tables. + +## How Profiles Work + +Behind the scenes, each Security Profile creates an isolated network environment: + +- **VLAN** — Layer 2 isolation so devices on different profiles cannot see each other's traffic +- **Subnet** — A dedicated `/24` IP range with its own DHCP server and gateway +- **Firewall zone** — Rules controlling what the profile can access (LAN, Internet, specific devices) +- **DNS** — Inherited from the system, the outbound VPN, or overridden with custom servers +- **Outbound routing** — Which gateway or VPN chain handles the profile's Internet traffic +- **Schedule** — Optional time-of-day restrictions on Internet access + +You do not need to configure any of these individually. When you create a profile, StartWRT sets up all the underlying networking automatically. + +## How Devices Get Profiles + +A device's Security Profile is determined by its **point of entry** — how it connects to the network: + +- **Ethernet** — The physical port a device plugs into. Each port maps to a profile. See [Ethernet](ethernet.md). +- **WiFi** — The password a device uses to join the WiFi network. Each password maps to a profile. See [Wi-Fi](wifi.md). +- **Inbound VPN** — The WireGuard server a device connects to remotely. Each VPN server maps to a profile. See [Inbound VPNs](inbound-vpn.md). + +One SSID, multiple passwords. One router, multiple isolated networks. The profile abstraction keeps it simple. + +## Creating a Profile + +1. Navigate to `Security Profiles` and click "Add". + +1. Configure the profile: + + - **Name** — A descriptive name (e.g. "Admin", "Guest", "Children", "Smart Devices"). + + - **Subnet** — The third octet of the profile's `/24` subnet. For example, a value of `2` creates the subnet `192.168.2.0/24`. Each profile must have a unique subnet. The gateway address is always `.1` within the subnet (e.g. `192.168.2.1`). + + - **Outbound Routing** — Choose how traffic from this profile reaches the Internet. Select **WAN** for direct Internet access, or choose an [Outbound VPN](outbound-vpn.md) to route all traffic through that VPN. + + - **Custom DNS** — Override the DNS servers for this profile. When enabled, specify up to three DNS servers (Primary required, Secondary and Tertiary optional). Each server has a **Secure (DoH)** toggle for DNS-over-HTTPS encryption. When Custom DNS is off, the profile uses the outbound VPN's DNS (if routing through a VPN) or the system DNS from [WAN Settings](wan.md). + + - **LAN Access** — Controls which other profiles this profile can communicate with on the local network: + - **All** — Full access to devices on all profiles. + - **Same profile** — Only communicate with devices on this same profile. + - **Whitelist** — Select specific profiles from a list. + + - **Auto whitelist new profiles** — Shown only in Whitelist mode. When enabled, newly created profiles are automatically added to this profile's whitelist. Useful for admin profiles that should maintain access to all network segments. + + - **WAN Access** — Controls Internet access for devices on this profile: + - **Allow All** — Unrestricted Internet access. + - **Block All** — No Internet access. Devices can only reach LAN resources permitted by the LAN Access setting. + - **Whitelist** — Allow connections only to specific destination IPs or CIDR ranges (e.g. `1.1.1.1, 8.8.8.0/24`). + - **Blacklist** — Block connections to specific destination IPs or CIDR ranges, allow everything else. + +1. Click "Save". + +## Editing a Profile + +1. Navigate to `Security Profiles` and select the profile. + +1. Modify any settings and click "Save". + +> [!WARNING] +> Changing a profile's settings takes effect immediately for all devices currently assigned to that profile. + +## Deleting a Profile + +1. Navigate to `Security Profiles` and select the profile. + +1. Click "Delete". + +> [!WARNING] +> Deleting a profile disconnects all devices assigned to it. You must first remove or reassign all points of entry (Ethernet ports, WiFi passwords, VPN servers) that reference the profile. + +> [!NOTE] +> The primary LAN profile cannot be deleted. + +## WAN Schedules + +Each profile can optionally restrict Internet access during specific time periods. Schedules define **block windows** — periods when WAN access is disabled for devices on the profile. Outside of these windows, the profile's normal WAN access rules apply. + +1. Navigate to `Security Profiles`, select the profile, and click "WAN Schedule" from the actions menu. + +1. The schedule is displayed as a 7-day visual timeline grid, with one row per day of the week. + +1. Click "Add" to create a block window: + + - Set the **start** and **end** times. Times use quarter-hour granularity (15-minute increments). End time must be later than start time. + - Select which **days** of the week the window applies to. + - Click "Save". + +1. Multiple block windows per day are supported. + +> [!TIP] +> Double-click an existing window to edit or delete it. Drag windows to adjust their position on the timeline. + +> [!NOTE] +> WAN Schedules block Internet access, not LAN access. Devices can still reach LAN resources during blocked periods according to the profile's LAN Access setting. + +## Example Profiles + +Here is an example of how a household might use Security Profiles: + +| Profile | WAN Access | LAN Access | DNS | Outbound Gateway | Schedule | +|---------|------------|------------|-----|-------------------|----------| +| **Admin** | Allow All | All | System | Mullvad VPN | — | +| **Children** | Allow All | Same profile | Custom (filtering) | DNS-filtering VPN | Block 9 PM - 7 AM | +| **Guest** | Allow All | Same profile | System | Proton VPN | — | +| **Smart Devices** | Whitelist | Same profile | System | WAN | — | +| **Shared Services** | Block All | Whitelist | System | — | — | diff --git a/start-wrt/src/settings.md b/start-wrt/src/settings.md new file mode 100644 index 0000000..2ed6a1c --- /dev/null +++ b/start-wrt/src/settings.md @@ -0,0 +1,70 @@ +# Settings + +The Settings page contains system preferences, account management, and advanced tools. Navigate to `System > Settings`. The page is organized into tabs: General, Password, SSH Keys, Backup, Logs, Activity, and Advanced. See also [SSH Access](ssh.md) and [Backups](backups.md) for dedicated documentation on those tabs. + +## General + +### Preferences + +- **Theme** — System, Dark, or Light. System follows your browser or OS preference. +- **Language** — Select the language for the web interface. +- **Timezone** — Set the router's local timezone. This affects [WAN Schedules](security-profiles.md#wan-schedules), [WiFi Schedules](wifi-schedules.md), activity timestamps, and log timestamps. + +### Remote Access + +Controls whether the web interface is accessible from outside the local network. + +- **When behind NAT** (default) — Allows remote access only when the router is behind NAT (typical home network with a private IP). This is the recommended setting for most users. +- **Never** — Disables remote access entirely. The admin interface is only accessible from devices on the local network. +- **Always** — Enables remote access at all times, even with a public IP. + +> [!WARNING] +> Selecting "Always" exposes your router's admin interface to the Internet. Only use this if you understand the security implications and have a strong admin password. + +### Security + +- **Download Root CA** — Download the router's Root CA certificate. Installing this certificate on your devices allows browsers and apps to trust the router's HTTPS connections without security warnings. + +### Updates + +When a firmware update is available, a banner appears at the top of the General page showing the new version number. Expand the banner to view release notes before updating. See [Updating](updating.md) for the full update procedure. + +## Password + +Change your admin password. The admin password protects the web interface and is separate from the WiFi password. + +1. Navigate to `System > Settings > Password`. + +1. Enter your current password. + +1. Enter and confirm your new password (minimum 12 characters). + +1. Click "Save". + +## Logs + +View real-time system logs streamed from the router via WebSocket. Useful for diagnosing network issues, monitoring VPN connections, or verifying firewall behavior. + +Navigate to `System > Settings > Logs` to open the live log viewer. You can download the full log as a text file or scroll to the bottom to follow new entries in real time. + +## Activity + +View a log of administrative actions taken through the web interface. Each entry shows: + +- **Status icon** — Green check for successful actions, red X for failures. +- **Timestamp** — When the action occurred. +- **Summary** — A description of the action performed. +- **Error details** — If the action failed, the error message is shown below the summary. + +Individual entries can be deleted, or click "Clear All" to remove the entire log. The list is paginated with 10 entries per page. + +## Advanced + +The Advanced tab contains power-user tools: + +- **Launch LuCI Interface** — Opens the underlying OpenWrt LuCI admin panel in a new tab for direct access to low-level configuration. +- **Download Support Diagnostics** — Generates and downloads a diagnostic bundle for troubleshooting with Start9 support. +- **Factory Reset** — Erases all settings and reboots the router. See [Factory Reset](factory-reset.md) for details. + +> [!WARNING] +> Factory reset is irreversible. Create a [backup](backups.md) first if you want to preserve your configuration. diff --git a/start-wrt/src/ssh.md b/start-wrt/src/ssh.md new file mode 100644 index 0000000..9a36bf3 --- /dev/null +++ b/start-wrt/src/ssh.md @@ -0,0 +1,53 @@ +# SSH Access + +Access your router's command line over SSH for advanced troubleshooting, package management, or direct configuration. SSH uses public key authentication — passwords are not accepted. + +## Adding an SSH Key + +1. Navigate to `System > Settings > SSH Keys`. + +1. Click "Add Key". + +1. Paste your public key (the contents of `~/.ssh/id_ed25519.pub` or `~/.ssh/id_rsa.pub`). + +1. Give the key a name (e.g. "MacBook", "Desktop"). + +1. Click "Save". + +> [!TIP] +> If you do not have an SSH key pair, generate one: +> +> ``` +> ssh-keygen -t ed25519 +> ``` +> +> This creates a private key (`~/.ssh/id_ed25519`) and a public key (`~/.ssh/id_ed25519.pub`). Add the public key to StartWRT. Never share the private key. + +## Connecting + +Once your key is added, connect from a terminal: + +``` +ssh root@192.168.0.1 +``` + +Replace `192.168.0.1` with your router's LAN IP address if you have changed it from the default. + +## Removing an SSH Key + +1. Navigate to `System > Settings > SSH Keys`. + +1. Select the key and click "Remove". + +> [!WARNING] +> Removing all SSH keys disables SSH access entirely. Ensure you can still access the web interface before removing your last key. + +## What You Can Do Over SSH + +SSH gives you root access to the underlying OpenWrt system. Common tasks: + +- View and edit UCI configuration files in `/etc/config/` +- Install additional packages with `opkg` +- Run diagnostic commands (`ping`, `traceroute`, `nslookup`, `tcpdump`) +- Inspect firewall rules with `nft list ruleset` +- Monitor WireGuard tunnels with `wg show` diff --git a/start-wrt/src/updating.md b/start-wrt/src/updating.md new file mode 100644 index 0000000..56beb93 --- /dev/null +++ b/start-wrt/src/updating.md @@ -0,0 +1,42 @@ +# Updating + +StartWRT firmware updates are installed by booting from a microSD card. This ensures the update process is reliable and recoverable — if anything goes wrong, the router's existing firmware remains untouched until you explicitly choose to flash. + +## Check for Updates + +Navigate to `System > Settings` in the web interface. If a newer version is available, you will see a notification with the version number. + +## Perform the Update + +1. Download the latest StartWRT firmware image from the [Start9 releases page](https://github.com/Start9Labs/start-wrt/releases). + +1. Write the image to a microSD card. See [Installing StartWRT](installing.md#write-the-image-to-microsd) for platform-specific instructions. + +1. Power off the router. + +1. Insert the microSD card and power the router back on. + +1. Connect to the `StartWRT` WiFi network using your WiFi password. + +1. The captive portal will open the setup wizard. Select **Update**. + +1. Create a new admin password when prompted. + +1. When the process completes, power off the router, remove the microSD card, and power it back on. + +> [!NOTE] +> The Update path preserves your settings — security profiles, WiFi passwords, firewall rules, SSH keys, and other configuration. The admin password is always reset during an update as a security measure, since physical access to the microSD slot is sufficient authorization. + +## What Gets Preserved + +| Preserved | Not Preserved | +|-----------|---------------| +| Security Profiles | Admin password (re-created during update) | +| WiFi passwords and settings | User-installed package binaries | +| Firewall rules | | +| VPN configurations | | +| SSH keys | | +| Device names | | + +> [!TIP] +> User-installed package config files are preserved even though the binaries are wiped. After updating, reinstall any additional packages and their previous configuration will still be in place. diff --git a/start-wrt/src/wan.md b/start-wrt/src/wan.md new file mode 100644 index 0000000..4d8c9b5 --- /dev/null +++ b/start-wrt/src/wan.md @@ -0,0 +1,58 @@ +# WAN Settings + +The WAN (Wide Area Network) page configures how the router connects to the Internet through your ISP. Most users will not need to change these settings — StartWRT auto-detects your Internet connection on first boot. Navigate to `Internet > WAN Settings`. + +## IPv4 + +Configure the router's IPv4 Internet connection. The default is DHCP, which works for most ISPs. + +- **DHCP** — The router obtains an IP address automatically from your ISP. This is the default and most common setting. + +- **Static** — Manually configure a fixed IP address assigned by your ISP: + - **WAN IP** — The static IPv4 address. + - **Prefix Length** — The subnet prefix (e.g. `/24`). The equivalent subnet mask is displayed alongside (e.g. `255.255.255.0`). + - **Gateway IP** — The default gateway provided by your ISP. + +- **PPPoE** — Used by some DSL providers. Enter the credentials provided by your ISP: + - **Username** — Your ISP account username. + - **Password** — Your ISP account password. + - **Device** — (Optional) Select a specific network interface for the PPPoE connection. + +## IPv6 + +Configure IPv6 if your ISP supports it. + +- **SLAAC** — Automatic IPv6 configuration. The most common option if your ISP supports IPv6. +- **DHCPv6** — The ISP assigns an IPv6 address via DHCP. Use if SLAAC does not work with your ISP. +- **Static** — Manually configure a fixed IPv6 address, prefix length, and gateway. +- **6RD** — Tunnels IPv6 over an IPv4 connection. Required by some ISPs that do not provide native IPv6. Configuration fields: IPv6 Prefix, IPv6 Prefix Length, IPv4 Prefix Length, and Border Relay IP (the IPv4 address of the ISP's relay server). +- **Disabled** — No IPv6 on the WAN interface. This is the default. + +For SLAAC and DHCPv6, an optional **IPv6 Prefix** field lets you request a specific prefix length from your ISP for prefix delegation (e.g. `/48`, `/56`, `/64`). Leave empty to let your ISP decide automatically. + +## DNS + +Configure which DNS servers the router uses to resolve domain names. + +- **Get from ISP** (default) — Use DNS servers provided automatically by your ISP via DHCP. +- **Custom** — Specify your own DNS servers. Up to three servers are supported (Primary required, Secondary and Tertiary optional). Each server has a **Secure (DoH)** toggle to enable DNS-over-HTTPS encryption for that server. + +> [!NOTE] +> Not all DNS servers support DoH. Common servers that do include Cloudflare (`1.1.1.1`), Google (`8.8.8.8`), and Quad9 (`9.9.9.9`). + +> [!TIP] +> Using privacy-focused DNS providers can improve both privacy and performance compared to your ISP's default DNS servers. Individual [Security Profiles](security-profiles.md) can override these DNS settings with their own Custom DNS configuration. + +## MAC Address + +Some ISPs bind your Internet connection to a specific MAC address. If you are replacing an existing router, you may need to clone the old router's MAC address. + +- **Router** (default) — Use the router's built-in MAC address. +- **Custom** — Enter the MAC address of your previous router or modem. + +> [!NOTE] +> If you do not know whether your ISP requires a specific MAC address, leave this setting at its default. You only need to change it if your Internet connection does not work after switching routers. + +## Dynamic DNS + +See [Dynamic DNS](ddns.md) for full details on configuring DDNS from this tab. diff --git a/start-wrt/src/wifi-schedules.md b/start-wrt/src/wifi-schedules.md new file mode 100644 index 0000000..27ed50e --- /dev/null +++ b/start-wrt/src/wifi-schedules.md @@ -0,0 +1,35 @@ +# WiFi Schedules + +WiFi schedules let you disable the WiFi radio on a recurring timetable. During a blackout window, the radio is powered off entirely — no devices can connect over WiFi. + +## Use Cases + +- **Limit late-night usage** — Disable WiFi from 10 PM to 7 AM so household members are not online at night. +- **Reduce RF exposure** — Power off the radio during sleeping hours to minimize radiofrequency EMF in the home. +- **Energy savings** — Turn off WiFi when nobody is home during the day. + +> [!NOTE] +> WiFi schedules affect the radio hardware itself, not individual devices or profiles. When WiFi is off, all WiFi-connected devices are disconnected regardless of their profile. Ethernet-connected devices are unaffected. For per-profile time restrictions on Internet access (not WiFi connectivity), use [WAN Schedules](security-profiles.md#wan-schedules) in Security Profiles. + +## Setting a Schedule + +The schedule is displayed as a 7-day visual timeline grid, with one row per day of the week. Blackout windows appear as shaded blocks on the timeline. + +1. Navigate to `Points of Entry > Wi-Fi > Schedule`. + +1. Click "Add" to create a blackout window. + +1. Set the **start** and **end** times for the blackout period. Times use quarter-hour granularity (15-minute increments). End time must be later than start time. + +1. Select which **days** of the week the window applies to. + +1. Click "Save". + +Multiple blackout windows per day are supported. For example, you could disable WiFi from 12 AM to 6 AM and again from 10 PM to 12 AM. + +> [!TIP] +> Double-click an existing window to edit or delete it. Drag windows to adjust their position on the timeline. + +## Removing a Schedule + +To remove a blackout window, double-click it and click "Delete". Removing all blackout windows effectively disables the schedule — WiFi will remain on at all times. diff --git a/start-wrt/src/wifi.md b/start-wrt/src/wifi.md new file mode 100644 index 0000000..6e57abd --- /dev/null +++ b/start-wrt/src/wifi.md @@ -0,0 +1,72 @@ +# Wi-Fi + +StartWRT uses a single WiFi network (one SSID) with multiple passwords. Each password maps to a different [Security Profile](security-profiles.md). The password a device uses to connect determines its profile — no manual network selection or VLAN configuration required. + +## How It Works + +Traditional routers create separate WiFi networks (separate SSIDs) for different access levels. StartWRT takes a different approach: one SSID with multiple WPA2 passwords. When a device connects, the router identifies which password was used and assigns the corresponding Security Profile. This is powered by WPA2's identity PSK feature with dynamic VLAN assignment. + +From the user's perspective, everyone connects to the same network name — the password is what determines their access level. + +## The Default Password + +The WiFi password printed on the sticker on the bottom of your router is the default password. It maps to the default Security Profile (typically "Admin" with full access). This password is set during manufacturing and stored securely on the router's eMMC storage. + +> [!NOTE] +> The sticker password is never displayed in the web interface. The sticker is the source of truth. Keep it safe. + +## Adding a WiFi Password + +1. Navigate to `Points of Entry > Wi-Fi > Passwords`. + +1. Click "Add". + +1. Configure the password: + + - **Label** — A descriptive name for this password (e.g. "Home", "Guest Network", "Kids"). + - **Password** — Enter a password (minimum 8 characters) or click "Generate" to create a strong random password. + - **Security Profile** — Select the [Security Profile](security-profiles.md) this password should map to. + +1. Click "Save". + +Share this password with the people or devices that should receive that profile. They connect to the same network — the router handles the rest. + +## Removing a WiFi Password + +1. Navigate to `Points of Entry > Wi-Fi > Passwords`. + +1. Select the password from the actions menu and click "Delete". + +> [!WARNING] +> Removing a WiFi password immediately disconnects all devices using it. Those devices will need a different password to reconnect. + +## Settings + +Configure the WiFi radio hardware under `Points of Entry > Wi-Fi > Settings`: + +- **Enable Wi-Fi** — Global toggle to turn the wireless radio on or off. When disabled, no devices can connect via WiFi. + +- **SSID** — The network name that devices see when scanning for WiFi (default: `StartOS`). All passwords share this single SSID. + +- **Broadcast** — Toggle SSID visibility. When off, the network is hidden from device scans and users must manually enter the network name to connect. + +- **Frequency Band** — 2.4 GHz, 5 GHz, or Both. 2.4 GHz has better range and wall penetration. 5 GHz offers higher speeds but shorter range. Both enables dual-band operation. + +- **Broadcast Separately** — Shown only when Band is "Both". When enabled, the 5 GHz band gets a separate SSID with a `-5G` suffix (e.g. `StartOS` and `StartOS-5G`). Useful if you want to control which band a device connects to. + +- **Channel** — Separate dropdowns for each band. **Auto** (recommended) lets the router select the least congested channel. You can also select a specific channel: 1–11 for 2.4 GHz, or 36–165 for 5 GHz. + +> [!WARNING] +> Changing the SSID disconnects all WiFi clients. You will be prompted to confirm before the change is applied. + +> [!TIP] +> For 2.4 GHz, channels 1, 6, and 11 are the only non-overlapping channels. If you experience interference, try one of these. + +## Example + +| Label | Password | Profile | Who uses it | +|-------|----------|---------|-------------| +| *(sticker)* | *(sticker)* | Admin | You — full LAN and Internet access | +| Guest | `guests-welcome` | Guest | Visitors — Internet only, through Proton VPN | +| Kids | `kids-network` | Children | Your children — Internet during daytime only, with DNS filtering | +| IoT | `smart-home-99` | Smart Devices | IoT devices — limited Internet, no LAN access | diff --git a/start-wrt/theme b/start-wrt/theme new file mode 120000 index 0000000..1c50727 --- /dev/null +++ b/start-wrt/theme @@ -0,0 +1 @@ +../theme \ No newline at end of file diff --git a/versions.conf b/versions.conf index 4fe12b1..6e55c06 100644 --- a/versions.conf +++ b/versions.conf @@ -5,3 +5,4 @@ start-os=0.4.0.x start-tunnel=1.0.x packaging=0.4.0.x bitcoin-guides=1.0.x +start-wrt=0.1.0.x From 61836735ab32f33694a8f95efc1d54a520388db0 Mon Sep 17 00:00:00 2001 From: Shadowy Super Coder Date: Thu, 2 Apr 2026 15:35:30 -0600 Subject: [PATCH 2/3] add tile for start-wrt --- landing/index.html | 8 ++++++++ serve.sh | 1 + 2 files changed, 9 insertions(+) diff --git a/landing/index.html b/landing/index.html index c55bf17..2c0dce6 100644 --- a/landing/index.html +++ b/landing/index.html @@ -149,6 +149,14 @@

Bitcoin Guides

StartOS.

+ + +

StartWRT

+

+ A router operating system for home-based self-hosting, built on + OpenWrt. +

+