mirror of
https://github.com/Start9Labs/start-os.git
synced 2026-03-26 02:11:53 +00:00
3c27499795
* refactor status info * wip fe * frontend changes and version bump * fix tests and motd * add registry workflow * better starttunnel instructions * placeholders for starttunnel tables --------- Co-authored-by: Aiden McClelland <me@drbonez.dev>
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# StartTunnel
|
|
|
|
A self-hosted WireGuard VPN optimized for creating VLANs and reverse tunneling to personal servers.
|
|
|
|
You can think of StartTunnel as "virtual router in the cloud".
|
|
|
|
Use it for private remote access to self-hosted services running on a personal server, or to expose self-hosted services to the public Internet without revealing the host server's IP address.
|
|
|
|
## Features
|
|
|
|
- **Create Subnets**: Each subnet creates a private, virtual local area network (VLAN), similar to the LAN created by a home router.
|
|
|
|
- **Add Devices**: When you add a device (server, phone, laptop) to a subnet, it receives a LAN IP address on that subnet as well as a unique WireGuard config that must be copied, downloaded, or scanned into the device.
|
|
|
|
- **Forward Ports**: Forwarding a port creates a "reverse tunnel", exposing a specific port on a specific device to the public Internet.
|
|
|
|
## Installation
|
|
|
|
1. Rent a low cost VPS. For most use cases, the cheapest option should be enough.
|
|
|
|
- It must have a dedicated public IP address.
|
|
- For compute (CPU), memory (RAM), and storage (disk), choose the minimum spec.
|
|
- For transfer (bandwidth), it depends on (1) your use case and (2) your home Internet's _upload_ speed. Even if you intend to serve large files or stream content from your server, there is no reason to pay for speeds that exceed your home Internet's upload speed.
|
|
|
|
1. Provision the VPS with the latest version of Debian.
|
|
|
|
1. Access the VPS via SSH.
|
|
|
|
1. Run the StartTunnel install script:
|
|
|
|
curl -fsSL https://start9labs.github.io/start-tunnel | sh
|
|
|
|
1. [Initialize the web interface](#web-interface) (recommended)
|
|
|
|
## Updating
|
|
|
|
Simply re-run the install command:
|
|
|
|
```sh
|
|
curl -fsSL https://start9labs.github.io/start-tunnel | sh
|
|
```
|
|
|
|
## CLI
|
|
|
|
By default, StartTunnel is managed via the `start-tunnel` command line interface, which is self-documented.
|
|
|
|
```
|
|
start-tunnel --help
|
|
```
|
|
|
|
## Web Interface
|
|
|
|
Enable the web interface (recommended in most cases) to access your StartTunnel from the browser or via API.
|
|
|
|
1. Initialize the web interface.
|
|
|
|
start-tunnel web init
|
|
|
|
1. If your VPS has multiple public IP addresses, you will be prompted to select the IP address at which to host the web interface.
|
|
|
|
1. When prompted, enter the port at which to host the web interface. The default is 8443, and we recommend using it. If you change the default, choose an uncommon port to avoid future conflicts.
|
|
|
|
1. To access your StartTunnel web interface securely over HTTPS, you need an SSL certificate. When prompted, select whether to autogenerate a certificate or provide your own. _This is only for accessing your StartTunnel web interface_.
|
|
|
|
1. You will receive a success message with 3 pieces of information:
|
|
|
|
- **<https://IP:port>**: the URL where you can reach your personal web interface.
|
|
- **Password**: an autogenerated password for your interface. If you lose/forget it, you can reset it using the start-tunnel CLI.
|
|
- **Root Certificate Authority**: the Root CA of your StartTunnel instance.
|
|
|
|
1. If you autogenerated your SSL certificate, visiting the `https://IP:port` URL in the browser will warn you that the website is insecure. This is expected. You have two options for getting past this warning:
|
|
- option 1 (recommended): [Trust your StartTunnel Root CA on your connecting device](#trusting-your-starttunnel-root-ca).
|
|
- Option 2: bypass the warning in the browser, creating a one-time security exception.
|
|
|
|
### Trusting your StartTunnel Root CA
|
|
|
|
1. Copy the contents of your Root CA (starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----).
|
|
|
|
2. Open a text editor:
|
|
|
|
- Linux: gedit, nano, or any editor
|
|
- Mac: TextEdit
|
|
- Windows: Notepad
|
|
|
|
3. Paste the contents of your Root CA.
|
|
|
|
4. Save the file with a `.crt` extension (e.g. `start-tunnel.crt`) (make sure it saves as plain text, not rich text).
|
|
|
|
5. Trust the Root CA on your client device(s):
|
|
|
|
- [Linux](https://staging.docs.start9.com/device-guides/linux/ca.html)
|
|
- [Mac](https://staging.docs.start9.com/device-guides/mac/ca.html)
|
|
- [Windows](https://staging.docs.start9.com/device-guides/windows/ca.html)
|
|
- [Android/Graphene](https://staging.docs.start9.com/device-guides/android/ca.html)
|
|
- [iOS](https://staging.docs.start9.com/device-guides/ios/ca.html)
|