macOS headless Client

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 SDP 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 SDP 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 SDP system could access it.

The headless Client does not support auto-update. This can be updated using the dmg file in the usual way - then run the headless installation step again.

Background information

There are some system limitations which need to be taken into account:

• Device on-boarding has to be done from the Appgate SDP headless Client for a user on a specific computer. If this device is already registered (using the full Appgate SDP Client) the headless Client will fail.

• MFA at sign-in is not supported on headless Client.

• Custom on-demand device Claims are not supported on headless Client.

Installation

Install using the same .dmg as for the full Client.

If you do not have access to the machine then to remotely install the Client do:

hdiutil attach "$INSTALLER_FILE_NAME" -mountpoint $TMPMOUNT
cd $TMPMOUNT/; installer -pkg Appgate\ SDP\ Installer.pkg -target "/"; cd /;
hdiutil detach $TMPMOUNT

A folder /Library/Application Support/Appgate is created containing various files including the script headless-installer. Run this as root by doing sudo ./headless-installer. This will setup and run the headless LaunchDaemon, and will enable autostart for the headless Client service. The installer can optionally be used to inject the required credentials the Client needs to connect to the Controller. If these are specified then the three items: username, password and profile link will be stored in the Keychain. If you skip this option initially, you can run the headless-installer again to add these later.

NOTE

All three options must be included at the same time.

How to set (or change) the configuration

The headless Client will always use the three options above if they are present in the Keychain (whether inserted by hand or using the installer). However there is a fall back mechanism for when they are not present; in this situation the appgate.conf file found in the folder /etc will be used.

We recommend first testing the setup with the appgate.conf file before trying to use the Keychain.

To add credentials, you can edit this file and add the required settings here:

sudo nano /etc/appgate.conf

Once done you will need to reload the configuration using the service configurator tool (see below).

Using appgate.conf

Un-comment the required items and add your configuration. i.e.

Password = my-password

Refer to LDAP Certificate IdP if using certificate authentication. The certificate should be saved in the file system - we suggest /var/lib/appgate/ as this has the correct permissions. If you need to protect the certificate then a certificate password should be used - and this can be stored in the keychain using the following command:

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

The -T option to the security command is very important, otherwise any application will be able to access the stored password.

Using the Client

To prevent the full Client auto-starting on boot do: defaults write com.appgate.sdp.service autostart 0

Normally the Client will autostart however you can start and stop the headless Client by doing:

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

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

You can get the current status and/or configuration of the headless client by using the `appgate_service_configurator` located in `/Library/Application Support/AppGate`.

Using the Service Configurator tool

In the folder /Library/Application Support/Appgate there is also the appgate_service_configurator tool.

The configuration tool uses different options to provide specific functionality. Enter:

sudo /Library/Application Support/Appgate/appgate_service_configurator OPTION

Logs

Logs for the headless Client are found in /var/log/appgate-headless