Windows headless client

Prev Next

Headless clients run in the background without a UI. They let unattended systems such as servers or container instances connect to AppGate ZTNA. Standalone headless clients are available for Windows, macOS, and Linux. AppGate also embeds headless clients in the Windows SSO client, always-on clients, Kubernetes Injector, and Connector.

After you apply a profile and credentials, the client immediately tries to sign in to the Controllers at boot and continues to retry.

NOTE

Always assign a valid policy to headless clients—without one, the retries can create a denial-of-service (DoS) condition on the Controllers and fill disk space with log warning messages.

After sign-in, the headless client receives its own entitlements based on its policy, granting access to permitted resources protected by AppGate ZTNA. It automatically establishes secure connections with Gateways. If the headless client is installed on a remote server, the entitlements may include down rules so AppGate ZTNA users can access it.

NOTE

Write access to TrustedCertificatePath is recommended when using the headless client.


System limitations

The Windows headless client has the following limitations:

  • You must onboard the device from the headless client for a user on a specific computer. If the device is already registered using the normal client, the headless client fails.

  • The client supports only authentication methods that work without a user present.

  • Multi-factor authentication (MFA) at sign-in is not supported on the headless client.

NOTE

Custom scripted device claims (formerly on-demand device claims) are not supported on headless clients.


Standard executables

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. Configures the headless client. Requires the AppGate ZTNA service to be running.

After you apply a configuration, the headless client tries to sign in using it and continues to retry if it cannot. Apply the configuration at any time to force the headless client to try connecting.


Installing the Windows headless client

Downloading the installer from the command line

To download the client, run CMD or PowerShell as an administrator and run the following command, replacing x.y.z in the filename and x.y in the filepath with the correct version numbers:

CMD

curl -L -o "%TEMP%\AppGate-SDP-client.exe" "https://bin.appgate-sdp.com/x.y/client/Appgate-SDP-x.y.z-Installer.exe"

PowerShell

Invoke-WebRequest -Uri "https://bin.appgate-sdp.com/x.y/client/Appgate-SDP-x.y.z-Installer.exe" -OutFile "$env:TEMP\AppGate-SDP-client.exe"

Installing the client from the command line

To install the client, run the installer with the /E or /HEADLESS switch. The /S (silent installation) switch is also recommended. Run CMD or PowerShell as an administrator. See Windows clients for a full explanation of all installation switch options.

To install the Windows headless client in silent mode, ensure the installer is in your C:\tmp folder and enter the following commands, replacing x.y.z with the correct version number:

CMD

start "" /WAIT "%TEMP%\AppGate-SDP-x.y.z-Installer.exe" /HEADLESS /S

PowerShell

Start-Process "$env:TEMP\AppGate-SDP-x.y.z-Installer.exe" -ArgumentList '/HEADLESS /S' -Wait

You do not need a client profile URL at this step. Set the profile and credentials afterward using the Configurator tool.

Optionally, add the /P switch with a profile link to set the profile at install time. You can get the profile link from Client Profiles (Identity > Client Profiles). Credentials are still required before the client can sign in to the Controller. Set them with the Configurator tool.

NOTE

User accounts must be configured in the identity provider (IdP) associated with the headless client profile before the service will connect. Use a separate client profile for headless clients, even when the same IdP is used for the full client.

Use services.msc to confirm that both appgateservice and cxdriver (AppGate ZTNA Driver Control) exist and are running.

NOTE

You can upgrade an existing full client installation to headless by running the installer with /E. The installer does not transfer any configuration set for the full client. Always provide the /E flag every time the client is installed, upgraded, or reinstalled to continue running it as the headless client.


How to set or change the client configuration

After installation, an “Appgate SDP” folder appears in the Windows Start menu. It contains several items, including a shortcut to the headless client's Configurator tool. Use the Configurator tool at any time to change the profile or credentials used by the headless client. It can also check the status of the Windows headless client, such as confirming it has signed in correctly.

To open the Configurator tool from the command line, run the following and replace <HEADLESS_USER> and <PASSWORD> with credentials from your IdP:

& 'C:\Program Files\Appgate SDP\Service\Appgate SDP Service.exe' configurator set -o "appgate://conn.example.com/headlessprofile==" -u <HEADLESS_USER> -p <PASSWORD>

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 Add or Remove Programs in Windows.

NOTE

Uninstalling the headless client removes only the client binaries—configurations are not removed.

To uninstall from the command line, run the installer with uninstall flags and replace x.y.z with the correct version number:

CMD

start "" /WAIT "%TEMP%\Appgate-SDP-x.y.z-Installer.exe" /S /UNINSTALL

PowerShell

Start-Process "$env:TEMP\Appgate-SDP-x.y.z-Installer.exe" -ArgumentList '/S /UNINSTALL' -Wait

Logs

The Windows headless client writes logs to the following files:

  • %programdata%\AppGate\driver.log

  • %programdata%\AppGate\service.log