waypoint

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 1, 2026 License: MIT

README

Waypoint

Docs site: https://redoapp.github.io/waypoint/

Waypoint is a Tailscale-aware database proxy that authenticates connections using Tailscale identity and ACL capability grants. It sits between clients on a tailnet and backend databases, enforcing per-user permissions, connection limits, and bandwidth budgets — with no passwords on the client side.

Features

  • Tailscale-native auth — identifies callers via tsnet + WhoIs, checks redo.com/cap/waypoint capability grants from your ACL policy
  • Postgres mode — intercepts the PG wire protocol, dynamically provisions per-user database roles with scoped GRANT permissions, and cleans up expired users
  • MongoDB mode — provisions scoped MongoDB users or uses static backend users, and rewrites replica-set topology so clients stay on the proxy, including TLS-terminated clients
  • TCP mode — transparent L4 proxy for any TCP backend (MySQL, Redis, etc.)
  • Connection tracking — per-user limits on concurrent connections, bytes transferred, connection duration, and bandwidth budgets, all stored in Redis/Valkey
  • Mid-session revalidation — periodically re-checks Tailscale identity during long-lived connections
  • Graceful shutdown — drains active connections on SIGINT/SIGTERM

Configuration

Waypoint reads a TOML config file (default: waypoint.toml). Environment variables can be interpolated with ${VAR} syntax. See examples/waypoint.toml for a full example.

[tailscale]
hostname = "waypoint-db"
state_dir = "/var/lib/waypoint/tsnet"

[redis]
address = "localhost:6379"
key_prefix = "waypoint:"

[revalidation]
interval = "1m"

# Optional: restrict ACL grants to presets only (no raw SQL)
[provisioning]
allow_raw_sql = false

[[listeners]]
name = "pg-main"
listen = ":5432"
mode = "postgres"
backend = "10.0.1.10:5432"
# Optional independent administrative path. Defaults to backend/tls.
# provision_backend = "10.0.1.10:5432"
# provision_tls = true
tls_mode = "optional"                   # off | optional | require
use_tailscale_tls = true                # default: allow *.ts.net cert lookup
cert_file = "/etc/waypoint/server.crt"  # optional: custom-domain cert
key_file = "/etc/waypoint/server.key"

[listeners.postgres]
admin_user = "waypoint_admin"
admin_password = "${PG_ADMIN_PASSWORD}"
admin_database = "postgres"
user_prefix = "wp_"
user_ttl = "24h"
# allow_raw_sql = true  # per-listener override

[[listeners]]
name = "raw-mysql"
listen = ":3306"
mode = "tcp"
backend = "10.0.1.5:3306"

PostgreSQL listeners may use provision_backend and provision_tls when the authenticated session path terminates at another proxy. Waypoint forwards the dynamic user's session to backend using tls, but creates and reconciles that user through provision_backend using provision_tls. Each override defaults to the corresponding session setting, so existing configurations are unchanged.

Postgres listeners default to tls_mode = "optional". If a client sends a PostgreSQL SSLRequest, Waypoint now upgrades that session to TLS and serves the certificate that matches the requested server name:

  • admin-provided cert_file/key_file for custom domains such as waypoint.redo.run
  • Tailscale-managed certificates for *.ts.net names when HTTPS certificates are enabled in the tailnet

Set use_tailscale_tls = false to disable Tailscale certificate lookup and use only the configured file-based certificate.

Use tls_mode = "require" to reject plaintext Postgres clients.

MongoDB replica sets can be exposed as one logical listener with one Waypoint port per member. Set backend_via_tailscale = true when Waypoint must reach the members over Tailscale or subnet routes. For SRV-backed clusters, omit [[listeners.mongodb.members]]; Waypoint resolves the SRV record at startup and allocates consecutive listener ports starting from listen:

[[listeners]]
name = "mongo-prod"
listen = ":27017"
mode = "mongodb"
backend_via_tailscale = true
tls = true                              # optional: use TLS to MongoDB backends
tls_mode = "require"                    # off | optional | require for clients
use_tailscale_tls = true                # default: allow *.ts.net cert lookup
# cert_file = "/etc/waypoint/mongo.crt" # optional: custom-domain cert
# key_file = "/etc/waypoint/mongo.key"

[listeners.mongodb]
admin_user = "waypoint_admin"
admin_password = "${MONGO_ADMIN_PASSWORD}"
auth_database = "admin"
replica_set = "rs0"
srv = "cluster.example.com"             # resolves _mongodb._tcp.cluster.example.com
srv_max_members = 3                     # binds :27017, :27018, and :27019

[listeners.mongodb.provision]
mode = "database"                       # default: create/update MongoDB users

When combining MongoDB SRV discovery with a Tailscale Service, set advertise so topology rewrites can be built before service listeners are registered.

You can also map members explicitly when you need fixed backend/member addresses:

[[listeners]]
name = "mongo-prod"
mode = "mongodb"
backend_via_tailscale = true

[listeners.mongodb]
admin_user = "waypoint_admin"
admin_password = "${MONGO_ADMIN_PASSWORD}"
auth_database = "admin"
replica_set = "rs0"

[[listeners.mongodb.members]]
backend = "mongo1.prod.internal:27017"
listen = ":27017"
advertise = "waypoint-db:27017"

[[listeners.mongodb.members]]
backend = "mongo2.prod.internal:27017"
listen = ":27018"
advertise = "waypoint-db:27018"

[[listeners.mongodb.members]]
backend = "mongo3.prod.internal:27017"
listen = ":27019"
advertise = "waypoint-db:27019"

For MongoDB listeners, tls = true enables TLS from Waypoint to each backend member. tls_mode controls client-facing TLS using the same values as Postgres: off, optional, or require. When MongoDB clients connect over TLS with SNI, Waypoint rewrites replica-set topology hosts to that SNI hostname while preserving the advertised listener/member ports.

MongoDB provisioning supports two modes. mode = "database" is the default and uses admin_user/admin_password to create or update backend MongoDB users. For MongoDB Atlas or other environments where user-management commands are not available, mode = "static" selects from pre-created backend users:

[listeners.mongodb.provision]
mode = "static"

[[listeners.mongodb.provision.static_users]]
name = "app-readwrite"
username = "atlas_app_rw"
password = "${MONGO_APP_RW_PASSWORD}"
auth_database = "admin"
database = "app"
permissions = ["readwrite"]

[[listeners.mongodb.provision.static_users]]
name = "readonly"
username = "atlas_readonly"
password = "${MONGO_READONLY_PASSWORD}"
auth_database = "admin"
permissions = ["readonly"]              # matches any all-readonly grant set

Static users must already have the matching roles in MongoDB or Atlas. When database is set, Waypoint matches the exact expanded database role set; when only permissions is set, it matches grants where every database has that same preset. You only need to configure the static users you want to allow. If an authorized client requests a grant set with no matching static user, Waypoint returns a MongoDB authentication error to that client and does not connect to the backend.

Tailscale ACL grants

Access is controlled by Tailscale ACL capability grants. The permissions field accepts named presets:

Preset Grants
readonly USAGE on schema, SELECT on all tables and sequences
readwrite Everything in readonly + INSERT, UPDATE, DELETE on tables, USAGE on sequences
admin ALL PRIVILEGES on tables and sequences, USAGE + CREATE on schema

By default, presets apply to the public schema. Use schemas to target other schemas.

Postgres clients can lower the effective preset for one connection with the waypoint_presets query parameter:

postgres://ignored:ignored@waypoint-db/myapp?sslmode=require&waypoint_presets=readonly

The value can be readonly, readwrite, or admin. Comma-separated values are accepted, with the strongest listed preset treated as the maximum. This cannot elevate beyond the ACL grant; for example, a readonly ACL grant remains readonly even if the connection asks for admin. When the parameter is set, Waypoint provisions a scoped backend role for that effective preset and skips raw SQL grants for that connection.

Example policy snippet:

{
  "grants": [{
    "src": ["group:backend"],
    "dst": ["tag:waypoint"],
    "cap": {
      "redo.com/cap/waypoint": [{
        "limits": {
          "max_conns": 10,
          "max_conn_duration": "1h"
        },
        "backends": {
          "pg-main": {
            "pg": {
              "databases": {
                "myapp": {
                  "permissions": ["readwrite"],
                  "schemas": ["public", "app"]
                },
                "*": { "permissions": ["readonly"] }
              }
            }
          }
        }
      }]
    }
  }]
}

For advanced use cases (specific tables, REVOKE, ALTER DEFAULT PRIVILEGES), use the sql field with Go templates:

{
  "databases": {
    "myapp": {
      "permissions": ["readonly"],
      "sql": [
        "GRANT INSERT ON public.audit_log TO {{.Role}}",
        "GRANT USAGE ON SCHEMA analytics TO {{.Role}}",
        "GRANT SELECT ON ALL TABLES IN SCHEMA analytics TO {{.Role}}"
      ]
    }
  }
}

The sql field can be disabled server-side with allow_raw_sql = false in the [provisioning] config section.

Observability

Waypoint exports OpenTelemetry metrics and traces to any OTLP-compatible collector.

[metrics]
endpoint = "http://otel-collector:4318"
protocol = "http"                        # "http" (default) or "grpc"
interval = "30s"
temporality = "delta"                    # "delta" (default, recommended for Datadog) or "cumulative"
tracing_sample_rate = 1.0                # 0 = disabled, 1.0 = trace all requests

[metrics.enable]
"waypoint.conn.active"   = ["listener", "mode"]
"waypoint.conn.total"    = ["listener", "mode"]
"waypoint.auth.attempts" = ["listener"]
"waypoint.bytes.read"    = ["listener", "user"]
"waypoint.bytes.written" = ["listener", "user"]

Metrics are opt-in per metric name via [metrics.enable]. The value array controls which attribute tags are allowed (use ["*"] for all).

Tracing is enabled when tracing_sample_rate > 0 and an endpoint is configured. Traces cover:

  • Connection setup (auth, slot acquisition, backend dial, PG provisioning)
  • Redis operations (lock, counters, bandwidth)
  • Mid-session revalidation checks
  • Connection close (final byte counts, duration)

Long-lived connections use linked spans rather than holding a single span open — the setup span ends once the relay begins, and revalidation/close events link back for correlation.

Usage

waypoint [-config path/to/waypoint.toml]

Set TS_AUTHKEY to authenticate the tsnet node on first run.

Development

Requires devenv:

direnv allow   # or: devenv shell --impure
go build ./cmd/waypoint/
test           # runs go test ./...
coverage       # runs tests with coverage report

Integration tests use testcontainers and require Docker.

License

MIT — see LICENSE.

Directories

Path Synopsis
cmd
covreport command
waypoint command
internal
tsdns
Package tsdns provides DNS resolution through the Tailscale local API.
Package tsdns provides DNS resolution through the Tailscale local API.
test
e2e

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL