Run as a Tailscale service

Synapse instances can be configured to automatically join your tailnet and host a Tailscale service.

Prerequisites

  • In your Tailscale configuration, define a new tag to apply to the Synapse hosts.

  • Define a new Tailscale service. Set the port to 443 and the ACL tag to the tag you created above.

  • Define an ACL to allow your tailnet users to access the service.

    Assuming that you named the service cerbos-synapse and the tag synapse-host, the following sample ACL allows everyone on your tailnet access to the service. Modify it as necessary to suit your requirements.

    {
    "tagOwners": {
        "tag:synapse-host": ["autogroup:member"],
    },
    "autoApprovers": {
        "services": {
            "svc:cerbos-synapse": ["tag:synapse-host"],
        },
    },
    "grants": [
        "src": ["*"],
        "dst": ["svc:cerbos-synapse"],
        "ip": ["*"],
    ]
}

  • Generate an auth key. Enable tags and assign the tag created above. Enabling ephemeral mode is recommended as well.

Launch Synapse into the tailnet

Once the above prerequisites are complete, launch Synapse with TS_AUTHKEY environment variable set to the auth key. Synapse will automatically join the tailnet and register as a host of the service (assuming it’s named cerbos-synapse). See Synapse logs or the Tailscale services console to obtain the address that can be used to access the service.

Customizing the configuration

You can customize the service name, service port and the host name on the tailnet by changing the Synapse configuration file.

server:
  tailscale:
    authKey: ${TS_AUTHKEY} # AuthKey to use to register the service. Defaults to environment variable TS_AUTHKEY.
    disabled: false # Disabled prevents the Tailscale service from being launched even if TS_AUTHKEY is defined in the environment.
    hostName: cerbos-001 # HostName overrides the host name of this instance on the tailnet. Defaults to system host name.
    serviceName: svc:cerbos-synapse # ServiceName sets the name of the Tailscale service. Defaults to svc:cerbos-synapse.
    servicePort: 443 # ServicePort sets the port of the Tailscale service. Defaults to 443.