Linux 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 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 ZTNAusers can access it.

The headless client does not support auto-update. Update it by reinstalling in the usual way.


System limitations

The Linux 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.

  • Multifactor authentication (MFA) at sign-in is not supported on the AppGate ZTNA headless client.

NOTE

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


Standard executables

The Linux headless client consists of four main components:

  • AppGate Service: The main client executable that runs in the background and handles all connections.

  • AppGate Driver: The virtual network adapter.

  • AppGate Configuration file: The settings file containing the parameters required to sign in.

  • AppGate Service Configurator: Controls the headless client. Requires the AppGate Service to be running.


Downloading the client

See the Downloads page, or use the following commands and replace x.y and x.y.z with the correct version numbers:

Ubuntu

curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp_x.y.z_amd64.deb"

Ubuntu ARM

curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp_x.y.z_arm64.deb"

Fedora

curl -L -o "/tmp/AppGate-SDP-client.rpm" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp-x.y.z-fc41.x86_64.rpm"

RHEL

curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp-6.7.3-el9.x86_64.rpm"

Installing the Linux headless client

NOTE

Remove any existing AppGate ZTNA installation before installing the headless client.

Use the command for your operating system and replace x.y.z with the correct version number:

Ubuntu

sudo apt install ./appgate-sdp-headless_x.y.z_amd64.deb

Ubuntu ARM

sudo apt install ./appgate-sdp-headless_x.y.z_arm64.deb

Fedora

sudo dnf install ./appgate-sdp-headless-x.y.z-fc41.x86_64.rpm

RHEL

sudo rpm -i appgate-sdp-headless-x.y.z-el9.x86_64.rpm

After installation, confirm that two services are running: appgatedriver.service and appgateservice.service.

Checking the installed version

To check the installed version, run:

dpkg -s appgate-headless | grep Version:

Starting and stopping the headless service

To start the headless service:

sudo systemctl start appgate-headless

To stop the headless service:

sudo systemctl stop appgate-headless

Configuring the Linux headless client

To configure the Linux headless client, run the following and replace <HEADLESS_USER> and <PASSWORD> with IdP credentials, and <full profile URL> with the client profile link. For example:

sudo /opt/appgate/headless-installer \
  --username <HEADLESS_USER> \
  --password <PASSWORD> \
  --profilelink "<full profile URL>"

How to set or change the configuration

The configuration file appgate.conf in /etc is used to set up the headless client.

Open the configuration file with a suitable editor:

sudo gedit /etc/appgate.conf

The file includes options for the following:

  • DNS: the option to specify a dns_script if required.

  • Log level and script timeout settings: default log level is Info. Options are: Dump, Trace, Debug, Info, Warn, Error, Fatal.

  • Credentials: uncomment the required lines and edit the values accordingly.

The configuration file accepts the following settings:

Setting

Description

ProfileLink

Specifies the client profile link. Can be copied from Client Profiles (Identity > Client Profiles).

Username

Sets the username for sign-in with credentials.

Password

Sets the password for sign-in with credentials.

PasswordScriptPath

Path to an executable that the headless service runs to return the password.

AuthenticationCertificatePath

Sets the path to the certificate for certificate authentication.

AuthenticationCertificatePassword

Sets the password for the authentication certificate.

See LDAP Certificate IdP if using certificate authentication. To get the current status or configuration, use the appgate_service_configurator.


Service Configurator tool

The appgateservice.service must be running to use this tool. The tool is located in /usr/sbin.

Open a command prompt and enter:

sudo appgate_service_configurator -h

This lists available commands, as does --help. Then:

sudo appgate_service_configurator OPTION

The Configurator tool accepts the following options:

Option

Action

getconfig

Displays the current configuration of the client.

reload

Signs out and reconnects automatically. Useful for testing a new configuration without restarting the client service.

status

Gets the status of the running service.

The status option returns one of the following messages:

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.

Connecting

Client has signed in and is connecting.

Connected

Client is signed in and connected. Details of entitlements, Gateways, and Sites are included.

Partially Connected

Client is signed in but can only connect to some Sites.

None connected

Client is signed in but cannot connect to any Site.

Disconnecting

Client is disconnecting and will soon try to sign in again.


Uninstalling the Linux headless client

Use the following commands to uninstall the headless client binaries but keep all configuration settings:

Operating system

Install command

Ubuntu

sudo apt remove appgate-headless

Fedora

sudo dnf remove appgate-headless

RHEL9

sudo dnf remove appgate-headless

To uninstall headless client binaries and all configuration settings, use the purge option in the above commands: remove --purge

For example: sudo apt remove --purge appgate-headless


Logs

View headless client daemon logs using:

journalctl -u appgateservice

To watch live headless logs, run:

tail -f /var/log/appgate-headless