tailzero

Tailscale PAM includes the tailzero command-line interface (CLI) to let you start and manage your Tailscale PAM connectors.

When you set up a PAM connector, tailzero is installed on the connector device.

Command Reference

tailzero provides commands for starting, installing, and uninstalling connectors, and checking and upgrading the tailzero version.

To get help for tailzero, run:

tailzero -h

To get help for a specific command, like tailzero start, run:

tailzero start -h

To get help for a specific subcommand, like tailzero version check, run:

tailzero version check -h

start

Start the connector. This is the default command.

tailzero start [flags]

Available flags:

• --acl-cap-pam=<uri> App capability URI that the policy engine reads PAM grants from. Override this when the control plane reserves the tailscale.com domain, for example border0.com/cap/pam. Defaults to tailscale.com/cap/pam.
• --border0-invite-code=<code> Border0 connector invite code. Required unless --border0-token is set.
• --border0-token=<token> Border0 connector token. Required unless --border0-invite-code is set.
• --cache-k8s-namespace=<namespace> Kubernetes namespace of the secret used to cache invite exchange credentials. Used with --border0-invite-code.
• --cache-k8s-secret-name=<name> Kubernetes secret name used to cache invite exchange credentials. Used with --border0-invite-code.
• --cache-ssm-path=<path> AWS SSM Parameter Store path used to cache invite exchange credentials. Used with --border0-invite-code.
• --config-dir=<path> Directory containing credential and secret environment files, loaded at startup.
• --debug Enable verbose per-connection logging, including policy evaluation and connection traces. You can also enable this by setting the environment variable BORDER0_VERBOSE_LOG=true.
• --hostname=<name> Hostname to use for the connector name. Defaults to the hostname of the host machine.
• --state-source=<uri> State source URI for the Tailscale node identity. This can be kube:<secret-name> for a Kubernetes secret, arn:aws:ssm:<region>:<acct>:parameter/<path> for AWS SSM Parameter Store (which survives ECS deploys), or mem: for ephemeral state. If empty, state is stored as a file under --statedir. When this is an SSM ARN and --cache-ssm-path is unset, Border0 credentials are also stored inside the same parameter.
• --statedir=<path> Directory for Tailscale state. Used for runtime files, and is also the default state file location when --state-source is unset. Defaults to /var/lib/tailzero.
• --ts-auth-key=<key> Tailscale auth key. Required unless identity federation credentials are present.
• --ts-control-url=<url> Tailscale coordination server URL. Set this for self-hosted deployments. Defaults to the public Tailscale control plane.
• --ts-id-fed-cid=<client-id> Tailscale identity federation client ID. Required when --ts-auth-key is not set.
• --ts-id-fed-token=<token> Tailscale identity federation token. Required when --ts-auth-key is not set.

install

Install the connector as a system service.

tailzero install [flags]

Available flags:

• --border0-invite-code=<code> Border0 invite code, which is exchanged for a token and an auth key.
• --border0-token=<token> Border0 connector token. Providing this directly skips the invite exchange.
• --cache-k8s-namespace=<namespace> Kubernetes namespace for credential caching.
• --cache-k8s-secret-name=<name> Kubernetes secret name for credential caching.
• --cache-ssm-path=<path> AWS SSM path for credential caching.
• --config-dir=<path> Directory for credential and secret files. Defaults to /etc/border0.
• --connector-name=<name> Connector name. Defaults to the hostname of the host machine.
• --service-user=<user> User to run the service as. Defaults to the current user.
• --state-dir=<path> Tailscale state directory. Defaults to /var/lib/tailzero.
• --ts-auth-key=<key> Tailscale auth key. Providing this directly skips the invite exchange.

uninstall

Remove the system service.

tailzero uninstall

This command has no flags.

version

Print the version, or check for and upgrade to a newer version.

tailzero version [subcommand] [flags]

Running tailzero version with no subcommand prints the installed version.

Subcommands:

• check Check for a newer version.
• upgrade Download and install a newer version.

Available flags for check:

• --track=<track> Release track to check, for example stable or unstable. Defaults to stable.

Available flags for upgrade:

• --track=<track> Release track to upgrade from, for example stable or unstable. Defaults to stable.
• --version=<version> Specific version to download, for example 1.0.0-0-gabcdef0 or latest.