Join us in San Francisco for TailscaleUp!Grab your ticket ->

Install a Tailscale PAM connector

Last validated:
Tailscale PAM is currently in beta.

You need to install a Tailscale PAM connector to provide secure sessions between a client and a protected resource on your Tailscale network.

You can choose between installing a connector from the Tailscale admin console or by installing a connector manually.

Prerequisites

The following prerequisites are required for any device that you use to run as a Tailscale PAM connector.

  • Device compatibility: The device must run either Linux or macOS.

  • Network reachability to Tailscale PAM: Your connector must have the ability to egress its network and reach the Tailscale PAM API and proxies through the internet.

  • Connector authentication: Depending on your preferred installation method, you are required to create a connector token for the connector to authenticate. If you don't provide this token when required, the connector will not authenticate itself with your tailnet, preventing the connector from being online. Any service that is associated only with this connector will not be available to your tailnet users.

The following prerequisites are use-case specific.

  • Network reachability to service origins: Your connector must be able to reach the target services (at the hostname and port configured in the upstream configuration) through the network, with the exception of AWS SSM targets. For example, if you have a connector running in a private network with no way of connecting to a target service in a different private network, this connector will not be able to establish a connection to the upstream service.

  • Third-party service authentication: Depending on the upstream configuration of your connector's services, you may need additional credentials or configuration to authenticate against third-party services. Specifically, if any of the services are connected to by using the AWS EC2 Instance Connect or AWS SSM options, you need to make sure your connector's runtime has access to the appropriate AWS credentials that allow connecting with those methods.

    • For help with AWS credentials for connecting to AWS EC2 Instance Connect targets, refer to the AWS credentials topic on the Tailscale PAM site.
    • For help with AWS credentials for connecting to AWS SSM targets, refer to the AWS EC2 / ECS With SSM (Session Manager) topic on the Tailscale PAM site.

Install the connector binary

The connector binary, tailzero, is a tsnet binary with a single auto-detecting installation script. tailzero provides the connector capability to let your users securely access services on your tailnet. How you install the connector binary depends on which platform you are using.

Linux/macOSDockerKubernetesAWS EC2
  1. Open the Connectors page of the admin console.
  2. Select Add connector.
  3. Select the AWS EC2 option.
  4. Follow the instructions that are shown in the Launch New Connector page.

This starts the connector process as a system service on your operating system, ensuring it runs after reboots. In the Connectors page, your connector should appear as online.

Once installed, you can create services, which will appear in your Tailscale client, letting your tailnet users securely access them without requiring an additional login on the client.

Manage the connector service

You can use the command line to manage the connector service.

Manage the connector service on Linux

To check the current status of the PAM connector service:

sudo systemctl status tailzero

To stop the PAM connector service:

sudo systemctl stop tailzero

To start the PAM connector service:

sudo systemctl start tailzero

To restart the PAM connector service:

sudo systemctl restart tailzero

To check the connector logs:

journalctl -fu tailzero

Manage the connector service on macOS

To stop the PAM connector service:

sudo launchctl unload /Library/LaunchDaemons/tailzero.plist

To start the PAM connector service:

sudo launchctl load /Library/LaunchDaemons/tailzero.plist

Update the connector binary

You have two ways to update the connector binary.

You can run the tailzero version upgrade command:

sudo tailzero version upgrade

Alternatively, for Linux and macOS, run the same command as used to install the binary:

sh <(curl -fsSL https://tailscale.border0.com/tailzero/install.sh)

To determine which version you are running, run:

tailzero version

Configure your connector

Once you have installed and started your connector, it should show up in the Connectors page. The connector provides several built-in services that can be enabled or disabled by configuring the connector details. By default the connector is configured to run a built-in SSH server, which lets you open an SSH shell on the connector host.

For more information about connectors, refer to PAM connectors.