# Start Tunnel configuration **URL:** \ **Category:** Guides\ **Created:** [September 14, 2026, 7:01pm UTC](https://community.start9.com/t/start-tunnel-configuration/5736 "2026-09-14T19:01:38Z")\ **Posts on this page:** 3\ **Page:** 1
**Author:** ![ruxal](https://community.start9.com/user_avatar/community.start9.com/ruxal/32/451_2.png) [@ruxal](https://community.start9.com/u/ruxal)\ **Post date:** [September 14, 2026, 7:01pm UTC](https://community.start9.com/t/start-tunnel-configuration/5736/1 "2026-09-14T19:01:38Z")
According to the guide: I just observed the following: [https://docs.start9.com/start-tunnel/1.0.x/installing.html?cloud-firewall=IONOS&ssh-auth=SSH+key+(most+providers)&tunnel-cert=Use+your+StartOS+Root+CA+(recommended)&platform=Mac](https://docs.start9.com/start-tunnel/1.0.x/installing.html?cloud-firewall=IONOS&ssh-auth=SSH+key+(most+providers)&tunnel-cert=Use+your+StartOS+Root+CA+(recommended)&platform=Mac) # Installing docs (1.0.x): two gaps found on a fresh Debian 13 VPS, v1.3.0 Ran through the Installing guide end-to-end on a clean Debian 13 VPS (minimal/Lite image, so did the `apt-get install curl iputils-ping` step first). Two things tripped me up that the docs don’t currently cover. ## 1. `start-tunnel web init` can demand `--tunnel` even on a fresh local install After the installer finished cleanly (`Service started successfully`, banner printed, etc.), running: ```auto start-tunnel web init ``` immediately returned: ```auto Invalid Request: web.enable: `--tunnel` required ``` with no prompt, no interactive setup — just the error. The CLI reference says `--tunnel` is for pointing at a _remote_ server; nothing suggests it’s ever required for a local run directly on the box. To rule out a broken install, I checked: ```auto systemctl status start-tunnel ``` which returned `Unit start-tunnel.service could not be found.` — even though the service was, in fact, already running. This sent me down the wrong path (assumed the install had silently failed). It would help if the docs stated the **actual systemd unit name** somewhere (Installing or CLI reference), since `start-tunnel` itself isn’t it. **What actually resolved it:** re-running the installer (`curl -o install.sh` then `sudo sh install.sh`, non-piped) detected the existing install and running service, offered to reinstall 1.3.0 over itself, and after confirming, the service restarted. Only after that restart did `web init` proceed normally into the interactive setup (password, cert prompt, etc.) without needing `--tunnel`. So a plain **service restart** seems to be the actual fix — the reinstall was probably incidental. Would be great to have this called out as a known first-run hiccup with the real fix (`systemctl restart `), plus the correct unit name for anyone trying to self-diagnose. ## 2. “Paste the certificate chain” — unclear that multiple blocks get pasted together Following the “Use your StartOS Root CA” path, `start-cli net ssl generate-certificate ` printed a private key followed by a `Certificate Chain:` label and **three** back-to-back `-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----` blocks (leaf, intermediate, root). The Installing page just says: > 1. Paste the certificate chain next and press Enter. First time through, it’s not obvious whether “the certificate chain” means all three blocks concatenated, or whether you’re meant to pick one. (It’s all three, concatenated, in the order printed — pasting just one certificate is not a complete chain.) Suggested one-line addition to that step: _“If multiple `BEGIN CERTIFICATE`/`END CERTIFICATE` blocks are printed under ‘Certificate Chain’, copy and paste all of them together in the order shown — that combined output is the chain.”_ * * * Happy to test a doc PR against this VPS if useful — everything above is reproducible on a stock Debian 13 image. ---
**Author:** ![StuPleb](https://community.start9.com/user_avatar/community.start9.com/stupleb/32/195_2.png) [@StuPleb](https://community.start9.com/u/StuPleb)\ **Post date:** [September 15, 2026, 2:18pm UTC](https://community.start9.com/t/start-tunnel-configuration/5736/2 "2026-09-15T14:18:40Z")
Thanks for walking the guide end to end on a clean box and writing it up so carefully. I reproduced it on a fresh Debian 13 system with StartTunnel 1.3.0. Both gaps are real, but the first one isn’t a first-run hiccup. **1. ``--tunnel` required` means `start-tunnel` wasn’t running as root** On the VPS, `start-tunnel` authenticates to the StartTunnel service with a token the service writes the moment it starts, `/run/startos/tunnel.authcookie`, and only root can read that file. As a regular user the CLI can’t read it, so the only thing left for it to try is a remote server passed with `--tunnel` — hence the error. The message is misleading; it should tell you to use `sudo`. That’s also why the reinstall seemed to fix it. You ran the installer with `sudo`, and when it finds an existing install it restarts the service and then runs `start-tunnel web init` for you, as root. That was the interactive setup you got. The restart had nothing to do with it: as a regular user, `start-tunnel` still fails the same way afterwards. So, on a regular user account: ```auto sudo start-tunnel web init ``` and `sudo` in front of any other `start-tunnel` command, or `sudo -i` once. If `id -u` prints `0` and you were root all along, the same error means the service hadn’t written that token yet — post the output of `systemctl status start-tunneld` and `journalctl -u start-tunneld -b` and we’ll dig in. Reproducing this turned up one more trap. As a regular user, the guide’s `curl -sSL https://start9.com/start-tunnel/install.sh | sh` prints “Root privileges required. Re-running with sudo.” and then exits without installing anything. Until that’s fixed, `sudo -i` before you start is the reliable path. You’re right about the unit name as well. The service is `start-tunneld`; `start-tunnel` is only the CLI: ```auto systemctl status start-tunneld journalctl -u start-tunneld ``` **2. The certificate chain: yes, all three blocks, in the order printed** You read it correctly. `start-cli net ssl generate-certificate` prints the certificate for your VPS, then the intermediate, then the root, and the prompt wants exactly that: the first certificate has to match the key you just pasted, each one after it has to be the issuer of the one before, and the prompt only finishes once it has all three. Paste just one block and there’s no error — it simply waits for the rest. So copy everything from the first `-----BEGIN CERTIFICATE-----` to the last `-----END CERTIFICATE-----` and paste it in one go. Then press Enter, and if the prompt hasn’t moved on, keep pressing Enter until it does. The prompt reads a long paste about 1 KB at a time, so a full chain (about 2.4 KB) usually takes two more presses. I’ll tackle the docs. ---
**Author:** ![system](https://community.start9.com/uploads/default/original/1X/2dcde8aa6ad3ce3d7873096ee4b3e5395e19a7b5.png) [@system](https://community.start9.com/u/system)\ **Post date:** [September 17, 2026, 2:19pm UTC](https://community.start9.com/t/start-tunnel-configuration/5736/3 "2026-09-17T14:19:40Z")
This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.