Start Tunnel configuration

[ruxal]

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

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:

start-tunnel web init

immediately returned:

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:

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 <real-unit-name>), 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 <HOST> 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:

4. 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.

[StuPleb]

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:

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:

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.