Windows Headless Mode

Headless mode requires a Service Key

See the Services documentation for information on how to create a Service account and Service Keys.

Twingate’s existing Windows client may also be used in headless mode.

• Headless mode is enabled by installing the Client from the command line using the service_secret switch with the path to a valid Service Key. The Service Key is obtained from the Service configuration in the Twingate Admin console.
• The Client is controlled from Windows Services by starting and stopping the Twingate Service.

Working with the Windows Client in headless mode

Installation & configuration

The Windows Client is installed by running the installation from the command line and specifying the path to a Service Key. The latest Windows Client EXE installer can be downloaded from our public changelog.

The following command line options are available, which can also be set in the headless.conf file (see below):

• (Required) service_secret: Supply a path to a valid Service Key file
• (Optional) log_level: Set the log level. Defaults to info; available levels are documented in the headless.conf configuration file.
• (Optional) /quiet: Silent installation switch. Useful for automated deployment.

Some examples are shown below.

# Silently install the client in headless mode
TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json /quiet

# (Optional) Set the log level at installation time
# Note: log_level=info is the default log level
TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json log_level=debug /quiet

Additional optional configuration options, including the log level setting, are available at the following path:

C:\Program Files\Twingate\headless.conf

The Service Key is securely stored and managed by the Client. There’s no need to keep the original Service Key file in its original location. However, a valid Service Key is required when updating or reinstalling the Client.

Starting & stopping the Client

The Twingate Service service can be controlled directly from Windows Services. The Client will not start automatically by default, but the Windows service settings can be modified directly to set the desired behavior.

Troubleshooting

While running in headless mode, Client logs are output to the following path:

C:\ProgramData\Twingate\logs

Key rotation and Upgrades

Updating the Service Key

There are two ways to update the Service Key. One option is to run the sc command with Administrator permissions to stop the service and restart it with a new Service Key:

sc stop twingate.service
sc start twingate.service --config --service_secret C:\path\to\service\secret.json

The other option is to re-run the installation command with the service_secret switch pointing to the path of the new Service Key:

TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json

For all of the above options, you must restart the service for changes to take effect.

If you have previously installed the Client without a Service Key, you must perform a fresh installation with the service_secret switch pointing to a valid Service Key. You cannot simply run the sc command to update the Service Key in this case.

Deleting the Service Key

The stored Service Key may be deleted by running the following with Administrator permissions:

sc start twingate.service --config --reset

Deleting the Service Key will disconnect the Client from Twingate and require a new Service Key to be stored, either via the directions above or by running the installation command once more.

Upgrading the Client

To upgrade the client, run the installation command again with the service_secret switch pointing to a valid Service Key.

Last updated 2 days ago