--- title: "Linux headless client" slug: "linux-headless-client-v7-0" description: "Explore AppGate ZTNA's headless clients for Windows, macOS, and Linux, enabling secure, unattended connections without a UI." tags: ["Client Management", "Linux Headless Client", "Linux Client"] updated: 2026-11-03T21:03:37Z published: 2026-11-03T21:03:37Z canonical: "support.appgate.com/linux-headless-client-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # Linux headless client 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] > 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] > 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](/v1/docs/downloads) page, or use the following commands and replace `x.y` and `x.y.z` with the correct version numbers: #### Ubuntu For the latest version, run: ```bash curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/latest/ubuntu/AppGate-SDP-client.deb" ``` For a specific version, run the following command and replace `x.y` and `x.y.z` with the correct version numbers: ```bash 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 For the latest version, run: ```bash curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/latest/ubuntu/AppGate-SDP-client.deb" ``` For a specific version, run the following command and replace `x.y` and `x.y.z` with the correct version numbers: ```bash curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp_x.y.z_arm64.deb" ``` #### Fedora For the latest version, run: ```bash curl -L -o "/tmp/AppGate-SDP-client.rmp" "https://bin.appgate-sdp.com/latest/fedora/AppGate-SDP-client.deb" ``` For a specific version, run the following command and replace `x.y` and `x.y.z` with the correct version numbers: ```bash 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 For the latest version, run: ```bash curl -L -o "/tmp/AppGate-SDP-client.rpm" "https://bin.appgate-sdp.com/latest/rhel9/AppGate-SDP-client.rpm" ``` For a specific version, run the following command and replace `x.y` and `x.y.z` with the correct version numbers: ```bash 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] > 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 ```bash sudo apt install ./appgate-sdp-headless_x.y.z_amd64.deb ``` #### Ubuntu ARM ```bash sudo apt install ./appgate-sdp-headless_x.y.z_arm64.deb ``` #### Fedora ```bash sudo dnf install ./appgate-sdp-headless-x.y.z-fc41.x86_64.rpm ``` #### RHEL ```bash 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: ```shell dpkg -s appgate-headless | grep Version: ``` ### Starting and stopping the headless service To start the headless service: ```bash sudo systemctl start appgate-headless ``` To stop the headless service: ```bash 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: ```bash sudo /opt/appgate/headless-installer \  --username \  --password \  --profilelink "" ``` --- ## How to set or change the configuration The configuration file `appgate.conf` in `/etc` is used to set up the headless client. ![](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag60-conf_file_linux.png?sv=2026-02-06&spr=https&st=2026-11-21T21%3A39%3A38Z&se=2026-11-21T22%3A39%3A38Z&sr=b&sp=r&sig=OAfxzw%2BkLlyNVLvPUjVgMpW7ZoYrUlxfttehUq26x1k%3D) Open the configuration file with a suitable editor: ```bash 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 Profile**s (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](/v1/docs/ldap-certificate-provider-v7-0) 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: ```bash sudo appgate_service_configurator -h ``` This lists available commands, as does `--help`. Then: ```bash 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: ```bash journalctl -u appgateservice ``` To watch live headless logs, run: ```bash tail -f /var/log/appgate-headless ```