Linux Headless Mode
Linux Headless Mode
The Twingate Client for Linux may be run in headless mode, allowing it to be used in environments where a graphical user interface is not available. This is particularly useful in server environments where the Client is required to run as a background service.
Twingate’s Linux Client may be used in either interactive mode or headless mode.
- Interactive mode is the default mode and is documented in our Linux Client documentation. The same platform support and installation instructions apply.
- Headless mode is accessed by passing a
--headless
parameter to thetwingate setup
command with the path to a valid Service Key specified. The Service Key is obtained from the Service configuration in the Twingate Admin console.
Prerequisites
- A Twingate account with the necessary permissions to create and manage Services. See the Services documentation for more information on how to create a Service account and Service Keys.
Working with the Linux Client in systemd
Installation & configuration
- The Linux Client is installed by following the existing installation process.
- Configure the Linux Client in headless mode by running the
twingate setup
command with the--headless
parameter.
For example:
curl https://binaries.twingate.com/client/linux/install.sh | sudo bashsudo twingate setup --headless /path/to/service_key.json
Additional command line parameters, including the ability to set the default log level, are available. More information is available by running twingate help setup
.
Starting & stopping the Client
# Start the clientsudo twingate start
# Check client statustwingate status
# Stop the clientsudo twingate stop
Troubleshooting
The Linux Client runs as a systemd
service with logs retrievable via journalctl
.
# Retrieve recent client logssudo journalctl -u twingate --since "1 hour ago"
Working with the Linux Client in Docker
The Linux Client may also be run in a Docker container. This may be useful in situations where only an individual service requires access to Twingate protected Resources.
Prior to running the Docker container, ensure that the Service Key is available on the host system. The Service Key should be mounted into the container using a volume.
Running the Client in Docker
The command below will run the Twingate Client in a Docker container, mounting the Service Key from the host system and starting the Client in headless mode. The command can be modified to suit the specific requirements of the environment, but the following parameters are required:
device /dev/net/tun
cap-add NET_ADMIN
Without these two parameters the Client running inside of the container will not be able to connect to Twingate.
Unsupported Compute Engines
Compute engines that do not support adding kernel capabilities to containers, such as AWS Fargate, are not supported at this time.
docker run -d\ -v /path/to/service-key/:/etc/twingate-service-key/ \ --device /dev/net/tun \ --cap-add NET_ADMIN \ ubuntu:latest bash -c " apt-get update && apt-get install curl -y && curl https://binaries.twingate.com/client/linux/install.sh | bash && sudo twingate setup --headless /etc/twingate-service-key/service-key.json && sudo twingate start && sleep infinity "
Alternatively, you can use Docker Compose to manage the container. An example docker-compose.yml
file is shown below:
version: "1.0"
services: tg-headless-client: image: ubuntu:latest command: > bash -c "apt-get update && apt-get install curl -y && curl https://binaries.twingate.com/client/linux/install.sh | bash && sudo twingate setup --headless /etc/twingate-service-key/service-key.json && sudo twingate start && sleep infinity" volumes: - /path/to/service-key/:/etc/twingate-service-key/ devices: - /dev/net/tun cap_add: - NET_ADMIN restart: unless-stopped
Finally, if you are using the Client to support a specific service and want it to only be available for that service, you can use a Compose file to load both containers and tie them together:
version: "1.0"
volumes: uptime-kuma: external: true
services: tg-headless-client: image: ubuntu:latest container_name: tg-headless-client command: > bash -c "apt-get update && apt-get install curl -y && curl https://binaries.twingate.com/client/linux/install.sh | bash && sudo twingate setup --headless /etc/twingate-service-key/service-key.json && sudo twingate start && sleep infinity" volumes: - /path/to/service-key/:/etc/twingate-service-key/ devices: - /dev/net/tun cap_add: - NET_ADMIN ports: - "3001:3001" restart: always uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma volumes: - uptime-kuma:/app/data network_mode: "service:tg-headless-client" depends_on: - tg-headless-client restart: always
In this example we are loading the Twingate Client in headless mode and then loading the Uptime Kuma service. Uptime Kuma is a commonly used open-source uptime monitoring and alerting system, and we want it to be able to access Resources in Remote Networks via the Twingate service. The network_mode: "service:tg-headless-client"
line ties the Uptime Kuma service to the Twingate Client service, allowing it to access the network tunnel created by the Client.
Last updated 4 months ago