Creating a Twingate Headless Client Gateway for IoT Environments

There are situations where installing the Twingate Client on every device in a network is impractical or impossible, such as in IoT environments or with legacy systems. In such cases, setting up a centralized gateway that manages DNS resolution, internet access, and secure remote Resource access can be a more efficient solution. This guide will walk you through creating a Twingate headless Client gateway on a Linux machine to provide secure access to remote Resources for devices that cannot have the Twingate Client installed directly.

Example Use Cases

• IoT Environments: Manage IoT devices that cannot have the Twingate Client installed, ensuring they still benefit from secure access to remote Resources.
• Legacy Systems: Provide secure internet and Resource access for older systems or devices incompatible with the Twingate Client.

Example Scenario: IoT Environment

Scenario: You manage an office with several IoT devices, including smart thermostats, security cameras, and sensors, that need secure access to remote management servers but cannot have the Twingate Client installed directly.

• Setup: Configure a Linux gateway using the provided script. Ensure all IoT devices are on the same local network and point their DNS and gateway settings to the Linux gateway.

• Operation: The Linux gateway will manage DNS resolution and act as a NAT gateway for internet access. It will also secure connections to remote management servers via Twingate.

• Benefits: Simplifies the network setup by centralizing secure access control on the Linux gateway, allowing all IoT devices to benefit from Twingate’s security features without needing individual Client installations.

Implementation Guide

Requirements

• A Linux machine running a supported Debian based distribution (e.g., Ubuntu, Debian), or Fedora
• Administrative access to the Linux machine
• Internet connection
• Twingate account and configuration details for a Service Account

Implementation Steps

• System Preparation

  • Ensure your system is up to date:
    Copy

    sudo apt update && sudo apt upgrade -y

    If necessary, install curl:
    Copy

    sudo apt install curl -y

• Download the Script

  • Download the Twingate Headless Client Gateway script to the local folder:
    Copy

    curl https://raw.githubusercontent.com/Twingate-Solutions/general-scripts/main/twingate-headless-client-gateway/twingate-headless-client-gateway.sh -o gateway_config.sh

• Configuration

  • Log in to the Twingate Admin Console, go to Teams -> Services, and create a new Service Account
  • Inside the Service Account, click the “Generate Key” button and choose an expiration period (set 0 for unlimited)
  • In the next screen, either download the Service Key Token or copy it to the clipboard
  • In your Linux machine, open a text editor, paste the token, and save the file as service_key.json in the same folder as the downloaded gateway_config.sh script
  • Alternatively, upload the file you downloaded for the token to the Linux machine and put it in the same folder as the downloaded gateway_config.sh script
  • Assign a Resource to the Service Account to use for testing - something with a public DNS name is recommended

• Run the Setup Script

  • Execute the provided setup script to configure the system:
    Copy

    sudo ./setup_gateway.sh ./service_key.json 10.0.0.0/24

  • The script requires two parameters: the path to the service key file and the local network CIDR block which are used to configure the gateway
  • The script will automatically install and configure Bind9, set up the NAT gateway, and install the Twingate headless Client using the provided token file.

• Verify the Setup

  • After the script completes, verify that the Bind9 service is running:
    Copy

    sudo systemctl status bind9

  • Check the Twingate Client status to ensure it is connected:
    Copy

    sudo twingate status

Testing

On a client device, configure its DNS and gateway to point to the IP address of your Linux gateway. Then, test the following:

• DNS Resolution
  • Test DNS resolution, using a domain name for a Resource available through Twingate:
    Copy

    nslookup twingate.resource.internal

    The response should show a CGNAT IP address assigned by Twingate.
  • Test DNS resolution for an external domain:
    Copy

    nslookup google.com

    The response should show a public IP address
• Internet Access
  • Configure the client device to use the Linux machine as its gateway.
  • Test internet connectivity by browsing the web or pinging an external server:
    Copy

    ping 8.8.8.8

• Access to Twingate Resources
  • Verify that the client device can access a Resource available through Twingate

Additional Information

For more information on the services and configurations used in this guide, refer to the following resources:

• Main Script Repository
• Linux Headless Clients
• Bind9 DNS Server on Debian
• Using IPTables for NAT