Update or add current Tailscale terminology

[KlfJoat]

Problem/Motivation

Similar to home-assistant/core#132976, it would probably be a good idea to align the Add-On's terminology, especially documentation, with that of Tailscale.

Expected behavior

tailscale/DOCS.md to mention somewhere that "proxy" = Tailscale serve.

And maybe for the "proxy" YAML item to be named "serve".

Actual behavior

The word "serve" is nowhere on the page, nor is there a link to the Tailscale serve documentation. It links to the HTTPS stuff, and that's good.

Proposed changes

Either rename the "proxy" option to "serve", add the word "serve" or an explanation that "proxy" = "serve" somewhere.

Also, especially add a link to the Tailscale serve documentation. https://tailscale.com/kb/1312/serve

I understand that for novice users, the term "proxy" may be desirable because that's what Tailscale serve does. I also recognize that I don't know how easy it would be to change the "proxy" item in the YAML config. So I'm not going to suggest that those get removed entirely. But for those of us who know something about Tailscale, mentioning "serve" somewhere would be helpful.

For me, it was only the repeated alignment of "proxy" with "funnel", and the vague recollection I have that "serve" might have had another name in the past that made me try it out. The logs confirmed it was really Tailscale serve.

[lmagyar]

Thanks for the feedback, you are right, things has changed.

Adding the missing link is a no-brainer.

Originally both the reverse proxy and the funnel was an option for the serve command. Additionally the current 2 separate bool config option (proxy and funnel) is also, hmmm, not so good. See also #407. So I suggest to merge them, but I really struggle with a good naming (it's harder than developing this stuff). What do you think about this:

config.yaml:

-  funnel: bool?
-  proxy: bool?
+  share: list(disabled|tailnet|tailnet and internet)?
-  proxy_and_funnel_port: match(^(443|8443|10000)$)?
+  share_port: match(^(443|8443|10000)$)?

And the documentation can explain/reference serve for the tailnet option and funnel for the internet option.

Tailscale uses similar wording, like (this is a funnel log):

Available on the internet:
https://xxxx.tailxxxx.ts.net/
|-- proxy http://127.0.0.1:xxxx

And uses similar wording in the online serve/funnel documentation "You can think of this as sharing the service, ... with the rest of your tailnet." "You can use it to share a local service,"

Yeah, changing an existing config is not trivial. At the beginning of stage2_hook.sh we can convert the old config with bashio::addon.options and bashio::addon.option "xxxx" commands to the new, these commands doesn't care about the schema, so we can update the config json easily. And rewrite the logic and docs at several places... I contributed proxy and funnel mainly, so I can do it.

[KlfJoat]

Hi,

I am also not good at naming and organizing options. My suggestion for something like this, where you are providing a configuration interface to a separate tool that someone else has developed, is to copy them. They spend the time and effort to figure out how to name and organize things, so you don't have to. :-) One benefit of copying is that you have to write less documentation--just name your option the same, and users can read the other tool's documentation to learn more.

I believe that the separate configuration options are still a good idea. Tailscale themselves split them up. So as a general Tailscale user (ignoring HA), I have 3 options.

1. tailscale serve - share with the Tailnet
2. tailscale funnel - share with the entire world + the Tailnet
3. tailscale serve + sharing that device with another user - share with individuals via the Tailnet.

If I'm using the HA Tailscale Add-On, I want to see separate options to configure 1 & 2. In the documentation, maybe make a mention of 3 because it's a combo of something I configure in the Add-On + something I do on the Tailscale layer).

In my case, I wanted to use the serve option. But when I went to the Add-On, I didn't find the word "serve" anywhere, nor did I find a link. So if the option name was changed and there was a link to the Tailscale docs about serve, that would be a good start. And maybe add some of the explanation you gave, "You can think of this as sharing..." to help people understand how tailscale serve vs tailscale funnel will affect access to their HA instance.

One other note, serve is available to all plans and is stable. But funnel is only for certain plans (currently it excludes the "Starter" plan) and it is also still in Beta. So I don't think it is a good idea to make too many changes that combines them, in case Tailscale changes funnel again.

I do like that the docs link to the Tailscale HTTPS docs. IMO, it's important that users understand that enabling serve means exposing the Tailscale name (usually hostname, but can be changed in Tailscale) of their HA instance on a Certificate Transparency public ledger.

Regards,
Cliff

[lmagyar]

Yes, right, the tailnet and internet explanation is already in the docs, I go with share: list(disabled|serve|funnel)?. Sadly these are not independent things, you can't configure them independently, even if TS split them up.

[KlfJoat]

Sadly these are not independent things, you can't configure them independently, even if TS split them up.

I admit, I have never configured funnel. But that blog post I just linked says that they ARE configured independently now. It says in the past, you had to configure serve before funnel. But now the funnel command does it all.

Have you tried configuring funnel without serve (separate from the Add-On, I mean)?

[lmagyar]

Yeah, "independent"... Eg. serve reset will reset funnel also, and vice versa, you serve 2 things then funnel a 3rd, all 3 will be available on the internet (that's why in #407 a second nginx reverse proxy was needed), etc... Instead of independence, they've created a total mess (in my opinion). I've tested the "independence" a few month ago, and I haven't seen anything in the changelog that it has changed. Serve is a "full blown" reverse proxy, and funnel is only a TCP forwarder in front of it that can be enabled or disabled, all config happens inside the reverse proxy (where the https traffic ended).

Now the only thing I need is some free time to implement it...

[KlfJoat]

you serve 2 things then funnel a 3rd, all 3 will be available on the internet

I've tested the "independence" a few month ago, and I haven't seen anything in the changelog that it has changed.

That may have been true in the past. But it isn't true at all, as of today. I don't know what you're looking for in changelogs.

I have one machine currently with a serve up and running. And I just added a new machine with my first funnel. Only the funnel website was available from the Internet, not my serve website.

Serve is a "full blown" reverse proxy, and funnel is only a TCP forwarder in front of it that can be enabled or disabled, all config happens inside the reverse proxy (where the https traffic ended).

This is also not true, as evidenced by the docs and my testing. I set up a funnel as an HTTPS reverse proxy, but to an SSH port, and it did not connect.

The funnel offers an HTTPS server that has a few modes: a reverse proxy, a file server, and a static text server.

The funnel command offers a TCP forwarder to forward TLS-terminated TCP packets to a local TCP server like Caddy or other TCP-based protocols such as SSH or RDP.

So please, don't do whatever weirdness you're thinking of doing to the settings. Just copy the settings the way that Tailscale does them. That will make the most sense to users.

[lmagyar]

Who is talking about 2 different servers???

Execute (in the add-on):

/opt/tailscale serve --bg --https=8443 --set-path=/test1 text:"test1"
/opt/tailscale funnel --bg --https=8443 --set-path=/test2 text:"test2"

And you can access both test1 and test2 at https://xxxx.tailxxxx.ts.net:8443/testX

So funnel turns on the TCP forwarder, and everything is published on the internet, all serve endponts, not just funnel endpoints. Until TS implements filtering in the reverse proxy, the TCP forwarder will publish everything behind a certain port.

And don't forget to reverse the above changes, execute:

/opt/tailscale serve reset

And miraculously funel also reseted.

Case closed, they are not independent.