macOS 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 ZTNA users can access it.

The headless client does not support auto-update. Update using the .dmg file in the usual way, then run the headless installation step again.

NOTE

To use the macOS client, turn off Limit IP address tracking on your device. If this setting is enabled, the client ignores DNS settings. You can disable it manually or through an Apple MDM profile. To disable it manually:

  1. On your macOS device, go to Settings > Network.

  2. Select your ethernet connection or Wi-Fi.

  3. Select the Details… button.

  4. Disable Limit IP address tracking and select OK.


System limitations

The macOS headless client has the following limitations:

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

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

  • Custom scripted device claims are not supported on the headless client.


Installing the macOS headless client

Install the macOS headless client using the same .dmg as for the full client.

Downloading the installer from the command line

To manually install the client, run the following command and replace x.y.z and x.y with the correct version numbers:

curl -L -o "/tmp/AppGate-SDP-client.dmg" "https://bin.appgate-sdp.com/x.y/client/Appgate-SDP-x.y.z-Installer.dmg"

Installing the client from the command line

To install the client remotely, run the following and replace x.y.z with the correct version number:

hdiutil attach "/tmp/AppGate-SDP-x.y.z-Installer.dmg" -mountpoint /tmp/appgate
sudo installer -pkg /tmp/appgate/Appgate\ SDP\ Installer.pkg -target "/"
hdiutil detach /tmp/appgate

This creates a folder at /Library/Application Support/Appgate. It contains several files, including the headless-installer script. Run the script as root:

sudo ./headless-installer

This sets up and runs the headless LaunchDaemon and enables auto-start for the headless client service. The installer can optionally inject the credentials the client needs to connect to the Controller. If you specify them, the installer stores the username, password, and profile link in the Keychain. If you skip this step initially, run the headless-installer again to add credentials later.

The headless installer accepts the following options:

Option

Description

--username

Sets the username for sign-in with credentials.

--password

Sets the password for sign-in with credentials.

--profilelink

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

NOTE

All three options must be included at the same time.

For example:

sudo /Library/Application\ Support/Appgate/headless-installer \
  --username <HEADLESS_USER> \
  --password <PASSWORD> \
  --profilelink "<full profile URL>"

How to set or change the configuration

If the three Keychain options above are present, the headless client uses them—whether added by hand or using the installer. A fallback exists for when they are not present: the appgate.conf file in the /etc folder. Test the setup with the appgate.conf file before using the Keychain.

Configuration file for Appgate service with settings and credentials details listed.

To add credentials, edit the file sudo nano /etc/appgate.conf

After editing, reload the configuration using the Service Configurator tool. Uncomment the required items and add your configuration, for example, Password = my-password.

The appgate.conf file accepts the following settings:

Setting

Description

LogLevel

Specify log level (default: Info). Options: Dump, Trace, Debug, Info, Warn, Error, Fatal.

Username

Sets the username for sign-in with credentials.

Password

Sets the password for sign-in with credentials.

ProfileLink

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

AuthenticationCertificatePath

Sets the path to the certificate for certificate authentication.

AuthenticationCertificatePassword

Sets the password for the authentication certificate.

AuthenticationCertificateSubjectName

Fetches the certificate with that subject name from the system Keychain.

See LDAP Certificate IdP if using certificate authentication. Save the certificate in the file system, in /var/lib/appgate/, which has the correct permissions.

To protect a certificate with a password, store the password in the Keychain:

sudo security add-internet-password -a AppgateCertificatePassword -s "appgate-headless" -j "Appgate SDP" -l "appgate-headless" -w [THE_PASSWORD] -T "/Library/Application Support/AppGate/AppGate Service.app/Contents/MacOS/AppGate Service" /Library/Keychains/System.keychain

NOTE

You must include the -T option. Without it, any application can access the stored password.


Using the client

To prevent the full client from auto-starting at boot, run:

defaults write com.appgate.sdp.service autostart 0

To start and stop the headless client manually:

sudo launchctl load /Library/LaunchDaemons/com.appgate.sdp.headless.plist
sudo launchctl unload /Library/LaunchDaemons/com.appgate.sdp.headless.plist

To get the current status or configuration, use the appgate_service_configurator in /Library/Application Support/AppGate.

Using the Service Configurator tool

The appgate_service_configurator tool is in /Library/Application Support/Appgate. Enter:

sudo /Library/Application Support/Appgate/appgate_service_configurator OPTION

The Configurator tool accepts the following options:

Option

Action

getconfig

Displays the current configuration.

reload

Signs out and reconnects automatically. Useful for testing a new configuration.

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 successfully signed in and is connecting.

Connected

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

Partially Connected

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

Suspended. Full client is currently connected
(Always-on only)

Client is suspended because the full client is in operation.

None connected

Client has successfully signed in but cannot connect to any Site.

Disconnecting

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


Uninstalling the macOS headless client

See Uninstalling macOS clients.


Logs

Headless client logs are in /var/log/appgate-headless.

To watch live headless logs, run:

tail -f /var/log/appgate-headless