Headless clients run without a UI in the background. They enable unattended systems such as servers or container instances to connect to the AppGate ZTNA system. Standalone headless clients are available for Windows, macOS, and Linux; these are also embedded by AppGate into the Windows SSO client, always-on clients, Kubernetes Injector, and Connector.
Once a profile and credentials have been applied to the headless client, on boot-up the client will immediately try and re-try to sign in to the Controller(s). For this reason it is strongly advised to always have a valid policy for headless clients, otherwise the retries will become a DoS attack on the Controllers and consume large amounts of disk space with log warning messages.
Once signed in the headless client will get its own entitlements, based on its policy, to access permitted resources protected by AppGate ZTNA. It will automatically attempt to establish secure connections with Gateways. If the headless client has been installed on a remote server, then the entitlements might include down rules so users of the AppGate ZTNA system can access it.
System limitations for the Windows headless client
Device onboarding has to be done from the headless client for a user on a specific computer. If this device is already registered using the normal client, the headless client will fail.
Authentication options are limited. Support is provided only for methods that work without a user present.
MFA at sign-in is not supported on the headless client.
Standard executables for the Windows headless client
The Windows headless client uses the following standard executables:
Appgate SDP Service. Runs as SYSTEM (in the background).
Appgate SDP.exe. Not required.
Service Configurator. Included to configure the headless client. Requires that the AppGate ZTNA service is running.
Once a configuration is applied, the headless client will try to sign in using the configuration and continue to retry if it cannot. You can apply the configuration at any time to force the headless client to try connecting.
NOTE
Custom scripted device claims (formerly on-demand device claims) are not supported on headless clients.
Installing the Windows headless client
To install the client, the installation needs to be run with the switch /E (/HEADLESS). It is recommended to run it using the /S (silent installation) switch as well.
An existing AppGate ZTNA full client installation can be upgraded to run as headless client by simply running the installer with /E. Any existing configuration set for the full client will not be transferred to the headless client. Refer to Windows clients for a full explanation of all the installation switch options.
To install the Windows headless client in silent mode, enter:
start "" /WAIT "Appgate-SDP-x.y.z-Installer.exe" /E /S /P="appgate://url.com"
PowerShell requires slightly different syntax:
start "Appgate-SDP-x.y.z-Installer.exe" -ArgumentList ' /E /S /P="appgate://url.com" '
NOTE
The profile link included after the /P switch can be obtained from the Client Profiles UI.
Use services.msc to make sure both the Appgate SDP client service (appgateservice) and Appgate SDP Driver Control (cxdriver) exists as a service and that both are running.
NOTE
Write access to "TrustedCertificatePath" is recommended when using the headless client.
NOTE
Always provide the /E flag every time the client is installed, upgraded, or reinstalled to continue to run it as the headless client.
Once installed, there will be an “Appgate SDP” folder in the Windows start menu that contains a number of items, including a shortcut to the headless client's Configurator tool.
Installing with the /P option will set a profile for the Windows headless client. However, some credentials will also be required before it can sign in to the Controller. These should be set using the configurator tool.
The Configurator tool can be used at any time to change the profile or credentials used by the headless client. It can also be used to check the status of the Windows headless client, such as checking that it has signed in correctly. Profile links can be obtained from the Client Profiles UI.
Uninstalling the Windows headless client
You can uninstall the Windows headless client in the following ways:
Run the uninstaller from the start menu shortcut
Use the Add or Remove Programs option in Windows.
NOTE
Any configurations of the headless client will not be removed on uninstall, only the headless client binaries.
Log files
There are two log files for the headless client:
%programdata%\AppGate\driver.log%programdata%\AppGate\service.log