From e4d79acc06e9830ae3ce82de10386ee8fbe27ac3 Mon Sep 17 00:00:00 2001
From: Harry Harpham <harry@tailscale.com>
Date: Fri, 9 Jan 2026 16:29:36 -0700
Subject: [PATCH] tsnet: expand instructions for running examples

TODO: figure out how to get gofmt to stop indenting my JSON...

Signed-off-by: Harry Harpham <harry@tailscale.com>
---
 .../tsnet-services-multiple-ports.go          | 42 ++++++++++++++-----
 .../example/tsnet-services/tsnet-services.go  | 40 +++++++++++++-----
 2 files changed, 61 insertions(+), 21 deletions(-)

diff --git a/tsnet/example/tsnet-services-multiple-ports/tsnet-services-multiple-ports.go b/tsnet/example/tsnet-services-multiple-ports/tsnet-services-multiple-ports.go
index 328e4cf43..925e91f94 100644
--- a/tsnet/example/tsnet-services-multiple-ports/tsnet-services-multiple-ports.go
+++ b/tsnet/example/tsnet-services-multiple-ports/tsnet-services-multiple-ports.go
@@ -1,20 +1,40 @@
 // Copyright (c) Tailscale Inc & AUTHORS
 // SPDX-License-Identifier: BSD-3-Clause
 
-// The tsnet-services example demonstrates how to use tsnet with Services.
-// TODO:
-//   - explain that a Service must be defined for the tailent and link to KB on
-//     defining a Service
-//   - recommend using an auth key with associated tags
-//   - recommend an auto-approval rule for service tags
+// The tsnet-services example demonstrates how to use tsnet with Services
+// which listen on multiple ports.
 //
-// TODO: can we provide example ACL which only allows certain user groups to hit
-// the pprof port?
+// To run this example yourself:
 //
-// To use it, generate an auth key from the Tailscale admin panel and
-// run the demo with the key:
+//  1. Define an ACL tag, an auto-approval rule, and traffic permits by adding
+//     the following to your tailnet's ACL policy file:
+//     TODO: convince gofmt to chill
+//     "tagOwners": {
+//     "tag:tsnet-demo-host": ["autogroup:member"],
+//     },
+//     "autoApprovers": {
+//     "services": {
+//     "svc:tsnet-demo": ["tag:tsnet-demo-host"],
+//     },
+//     },
+//     // Allow anybody in the tailnet to reach the demo Service.
+//     "grants": [
+//     "src": ["*"],
+//     "dst": ["tag:tsnet-demo-host"],
+//     "ip": ["*"],
+//     ],
 //
-//	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+//  2. Generate an auth key using the Tailscale admin panel. When doing so, add
+//     the tsnet-demo-host tag to your key.
+//     https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key
+//
+//  2. Define a Service. For the purposes of this demo, it must be defined to
+//     listen on TCP ports 443 and 6060. Note that you only need to follow Step
+//     1 in the following document.
+//     https://tailscale.com/kb/1552/tailscale-services#step-1-define-a-tailscale-service
+//
+//  3. Run the demo on the command line:
+//     TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
 package main
 
 import (
diff --git a/tsnet/example/tsnet-services/tsnet-services.go b/tsnet/example/tsnet-services/tsnet-services.go
index 9413344e0..2b22f084e 100644
--- a/tsnet/example/tsnet-services/tsnet-services.go
+++ b/tsnet/example/tsnet-services/tsnet-services.go
@@ -2,16 +2,38 @@
 // SPDX-License-Identifier: BSD-3-Clause
 
 // The tsnet-services example demonstrates how to use tsnet with Services.
-// TODO:
-//   - explain that a Service must be defined for the tailent and link to KB on
-//     defining a Service
-//   - recommend using an auth key with associated tags
-//   - recommend an auto-approval rule for service tags
 //
-// To use it, generate an auth key from the Tailscale admin panel and
-// run the demo with the key:
+// To run this example yourself:
 //
-//	TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
+//  1. Define an ACL tag, an auto-approval rule, and traffic permits by adding
+//     the following to your tailnet's ACL policy file:
+//     TODO: convince gofmt to chill
+//     "tagOwners": {
+//     "tag:tsnet-demo-host": ["autogroup:member"],
+//     },
+//     "autoApprovers": {
+//     "services": {
+//     "svc:tsnet-demo": ["tag:tsnet-demo-host"],
+//     },
+//     },
+//     // Allow anybody in the tailnet to reach the demo Service.
+//     "grants": [
+//     "src": ["*"],
+//     "dst": ["tag:tsnet-demo-host"],
+//     "ip": ["*"],
+//     ],
+//
+//  2. Generate an auth key using the Tailscale admin panel. When doing so, add
+//     the tsnet-demo-host tag to your key.
+//     https://tailscale.com/kb/1085/auth-keys#generate-an-auth-key
+//
+//  2. Define a Service. For the purposes of this demo, it must be defined to
+//     listen on TCP port 443. Note that you only need to follow Step 1 in the
+//     following document.
+//     https://tailscale.com/kb/1552/tailscale-services#step-1-define-a-tailscale-service
+//
+//  3. Run the demo on the command line:
+//     TS_AUTHKEY=<yourkey> go run tsnet-services.go -service <service-name>
 package main
 
 import (
@@ -27,8 +49,6 @@ var (
 	svcName = flag.String("service", "", "the name of your Service, e.g. svc:demo-service")
 )
 
-// TODO: this worked several times, then my host got stuck in 'Partially configured: has-config, config-valid'
-
 func main() {
 	flag.Parse()
 	if *svcName == "" {