How does it work?
Headless clients run without a UI in the background. They enable un-attended systems such as servers or container instances to connect to the AppGate ZTNA system. Stand alone 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 to sign in to the Controller(s) (and continue to retry if it fails). For this reason it is strongly advised to always have a valid policy for headless clients, otherwise the retries will effectively 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 any permitted resources protected by AppGate ZTNA and will automatically (try to) establish secure connections with the Gateways. If the headless client has been installed on a remote server then the entitlements might include down rules so that users of the AppGate ZTNA system could access it.
The headless client does not support auto-update. This can be updated reinstalling in the usual way.
Background information
There are some system limitations which need to be taken into account:
Device on-boarding has to be done from the AppGate ZTNA headless client for a user on a specific computer. If this device is already registered (using the normal AppGate ZTNA client) the headless client will fail.
MFA at sign-in is not supported on the AppGate ZTNA headless client.
The Linux headless client consists mainly of four components:
AppGate Service - The main client executable that will run in the background and handle all connections.
AppGate Driver - The virtual network adapter.
AppGate Configuration file - Settings file for the parameters required to sign-in.
AppGate Service Configurator - Tool to control the headless client. Requires that the AppGate Service is running.
NOTE
Custom scripted device claims (formerly on-demand device claims) are not supported on headless clients.
Installation and Uninstallation
How to install
Run the same commands as for the standard Linux client but using appgate-sdp-headless_x.y.z... instead of the full client.
Once installed there should be two services running; appgatedriver.service and appgateservice.service.
NOTE
You must remove any existing AppGate ZTNA installation before installing the headless client.
How to uninstall
To uninstall the headless client binaries BUT leave all configurations and settings. Enter:
Ubuntu:
sudo apt remove appgate-headlessFedora:
sudo dnf remove appgate-headlessRHEL9
sudo dnf remove appgate-headless
To uninstall the headless client binaries and all configurations and settings. use the purge option in the above commands:
remove --purge
How to set or change the configuration
The configuration file appgate.conf located in /etc is the way to setup the headless client.
Open the configuration file using a suitable editor such as:
sudo gedit /etc/appgate.conf
DNS
The file provides the option to specify a dns_script if required.
Settings
For log level setting and script timeouts.
(Default: Info) Specify loglevel (Dump, Trace, Debug, Info, Warn, Error, Fatal)
Credentials
Un-comment the required lines and edit the values accordingly
ProfileLink | Specify the client profile link to be used. Can be copied from the Client Profiles page. |
Username | Set username to use for sign in with credentials |
Password | Set password to use for sign in with credentials |
PasswordScriptPath | Path to an executable that can be run by the headless service that will return the password |
AuthenticationCertificatePath | Set the path to the certificate to be used in certificate authentication |
AuthenticationCertificatePassword | Set any password relating to the authentication certificate |
Refer to LDAP Certificate IdP if using certificate authentication.
You can get the current status and/or configuration of the headless client by using the `appgate_service_configurator`.
Service Configurator tool
The Linux appgateservice.service must be running to use this tool.
Open a command prompt and enter:
sudo appgate_service_configurator -h
This will provide a list of available commands (as will using --help).
The configuration tool uses different options to provide specific functionality. Enter
sudo appgate_service_configurator OPTION
OPTION | Action |
|---|---|
getconfig | Displays the current configuration of the client. |
reload | Will sign out the headless client if connected and reconnect automatically. Useful to try another configuration without having to restart the client service. |
status | Used to get the status of the running service. |
Status message | Description |
Waiting for configuration | Client is waiting to be configured |
Applying the new configuration | Client is applying the configuration and trying to sign in to AppGate ZTNA. |
Connecting | Client has successfully signed in and is connecting. |
Connected | Client has successfully signed in and is connected. Details of the entitlements, Gateways, and Sites are included. |
Partially Connected | Client has successfully signed in but can only connect to some Sites. |
None connected | Client has successfully signed in but can't connect to any Site. |
Disconnecting | Client is disconnecting and will soon try to sign in again. |
The configuration tool can be found in: /usr/sbin
Logs
The headless client daemon logs can be viewed using journalctl -u appgateservice