Install a Border0 connector

You need to install a Border0 connector to provide secure sessions between a client and a protected resource on your Tailscale network, known as a tailnet.

You can choose between installing a connector from the Border0 admin portal or by installing a connector manually.

Prerequisites

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

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

• Network reachability to Border0: Your connector must have the ability to egress its network and reach the Border0 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 socket 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 socket origins: Your connector must be able to reach the target sockets (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 socket in a different private network, this connector will not be able to establish a connection to the upstream socket.

• Third-party service authentication: Depending on the upstream configuration of your connector's sockets, you may need additional credentials or configuration to authenticate against third-party services. Specifically, if any of the sockets 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 Border0 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 Border0 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 sockets on your tailnet. How you install the connector binary depends on which platform you are using.

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 sockets, which will appear in your Tailscale client, letting your tailnet users securely access them without requiring an additional login on the client.

Install the connector binary using advanced mode

If you want to control more aspects of connector installation, you can manually create a connector and a connector token (which is different from an invite code).

1. In the Border0 admin portal, open the Connectors page.
2. Select Add New Connector.
3. Select Advanced.
4. On the Configure Connector page, provided a name. The name must contain only lowercase letters, numbers, or dashes.
5. (Optional) Provide a description for your connector.
6. (Optional) Enable the built-in SSH service for the connector, which lets you connect to the connector itself over SSH as a service from your tailnet.
7. Select Submit.

Next, create a token that you will use for authentication.

1. Select Create connector token.
2. On the New Connector Token page, provide a name for the token. The name must contain only lowercase letters, numbers, or dashes.
3. Select an expiration value.
4. Select Submit.
5. Select Copy Token to place the token value in your clipboard buffer. Keep this value secure, as it can authenticate a device to your tailnet.

At a command prompt on the device that you want to use for the connector, run the tailzero start command. You can run either a one-off connector, or run the connector as an installed service.

To run a one-off connector, run the following command:

tailzero start \
--border0-token "${<your-connector-token>}"

To run the connector as an installed service:

sudo tailzero install \
--border0-token "${<your-connector-token>}"

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 Border0 connector service:

sudo systemctl status tailzero

To stop the Border0 connector service:

sudo systemctl stop tailzero

To start the Border0 connector service:

sudo systemctl start tailzero

To restart the Border0 connector service:

sudo systemctl restart tailzero

To check the connector logs:

journalctl -fu tailzero

Manage the connector service on macOS

To stop the Border0 connector service:

sudo launchctl unload /Library/LaunchDaemons/tailzero.plist

To start the Border0 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 Border0 connectors.