Client types
There are a number of different types of Windows Client. For a quick overview of the differences refer to the Client compatibility matrix.
Designed for normal enterprise usage - including pre-installation as part of standard builds | |
Designed for third party usage - where the user may not have admin rights on their device. | |
For installation on terminal servers. Provides each user their own Appgate SDP session. | |
For installation on unattended machines such as Servers. | |
For normal enterprise usage where an always-on connection to certain (protected) hosts is required | |
Works with Windows SSO to allow users to perform a domain sign-in even when working remotely. |
Ensure the Client version is designed for use with the associated software OS version - see Download Center
Installing and running the Client
Each type of Windows Client has a page containing more specific details about how it is installed. Most use the same installer with various command line options full details of which are covered below; however the lite Client has its own installer.
It is normally best to un-install one type before changing to another type of Windows Client. Never try to partially un-install the Client such as only removing the Appgate SDP driver.
It is not un-common for end point protection softwares to interfere with or break the installation of the Client. The Client contains a number of components/executables listed below which may require to be white-listed within the end-point protection software.
Using Windows Events to check if Appgate SDP is connected
Windows logs are created by the Appgate SDP driver. These can be seen in the Event Viewer where the Source will be shown as <Appgate SDP driver>, the Event ID will be sown as <256>, and either <Connected> or <Disconnected> will be reported. These can be useful where other processes that rely on network connectivity can monitor these events, and wait for <Connected> before they attempt to send any network traffic.
Using the command line for (pre)installation and uninstallation of the Client
When the installer executable is run normally (when a user clicks it), then the full Client will be installed.
(Pre)installation of the client
You might want to pre-install the Client on standard device builds and minimize any subsequent user interactions required. One way to do this is to pre-install one or more profiles at install time using the /P switch. Client profiles include the CA fingerprint, SPA key and choice of IdP. This can be obtained from the Client Profiles UI. By example; to complete pre-installation of the Client and profile link (so the users will be ready to use the Client) run: appgate-sdp-installer.exe /S /P="appgate://Controller.myco.com/profilename..."
When the installer .exe is run from the command line then the following switches may be added (precede each with a space):
/help or /? | Lists installer usage/flags. | |
/S | Installer will run silently without any popup. Return code other than 0 indicates that an error occurred during installation. | |
/D | Will install the Client into an alternative directory (/D=C:\here). Can be used with /S. Must always be the last option given. | |
/I or /DISABLESCRIPTS | Will prevent the running of device claim scripts. | |
/A or /STARTCLIENT | Run the Client after silent install is finished. | |
/W or /AUTOSTARTALL | After this installation finishes the Client will auto-start for ALL users. (Normally it will only auto-start for the user that installed it.) This uses Windows Active Setup which has its own characteristics. It only allows settings to be applied once for OTHER users for a given piece of software. So installing 6.0.2 twice will only apply auto-start for OTHER users the first time.
| |
/Q or /SKIPAUTOSTART | Do not configure autostart for the the user that installed it. (see /W) | |
/G or /DISABLEUSERACCEPTANCE | Do not show the data usage user acceptance screen the first time the Client starts. (Not relevant in the case of Headless.) | |
/T or /ATTENTIONMODE | Pre-set the Attention level default value [0=Low, 1=Normal, 2=High] | |
/P="profile1;profile2" or | Set one or multiple profile links that will be used with fresh installs of the client. Each profile should be separated using a semicolon encapsulated in quotes ["profile1;profile2"]. i.e. /P="appgate://url1.com/abc;appgate://url2.com/def" | |
/E or /HEADLESS | Install Client as a Windows service so that it runs with no UI. | |
/O or /ALWAYSON | Install Client as both a full Client and as a headless Client so that it always runs in one mode or the other. | |
/L or /SSO | Install Client as a Windows SSO (PLAP) service so that it captures credentials from a customized Windows sign-in screen. | |
/M or /MULTIUSER | Install Client as a multi-user Client. See Multi-user Client for details of how this works. | |
/C or /CACHEPIN | Enable PIN caching when using the LDAP certificate identity provider. | |
/R or /SETSIGNEDIN | Sets the 'Keep me signed in' option as the default. | |
/N or /DISABLEUSERCHECK | Allow the Full Client to operate (pass traffic) even when the active Windows session is different from the Windows session that was used to launch the Full Client. Otherwise operation of the Client and driver will be paused when there is a mismatch preventing one session 'hijacking' another user's session. | |
/Y | Installs the client in NIAP profile protection mode. | |
/Z or /UNINSTALL | Triggers the installer to run the associated uninstaller. | |
Uninstaller
As well as triggering the uninstaller from the installer, it can be run independently. Go to the installation folder and run:
%programfiles%\appgate sdp\uninstaller.exe
When the uninstaller executable is run from the command line then the following switches may be added (precede each with a space):
/S | Uninstaller will run silently without any pop-up. Return code other than 0 indicates that an error occurred during uninstallation. |
|---|---|
/K, /KEEPSETTINGS | Will keep all the Client settings. |
NOTE
If scripting the installer using Powershell you should add an extra pair of single quotes ' ' round any double quotes " ". e.g. xxx.exe /P='"myurl"'.
Windows Clients - components/executables
Standard Executables:
Appgate SDP Service.exe - will run as USER - they handle the business logic.
%programfiles%\appgate sdp\service\appgate sdp service.exe
Appgate SDP.exe - multiple processes that run as USER - they handle the UI.
%programfiles%\appgate sdp\ui\appgate sdp.exe
appgate-driver.exe - the virtual network adapter that runs as SYSTEM - it handles connections to the Gateways.
%programfiles%\appgate sdp\driver\appgate-driver.exe
You might need to whitelist some or all of these if you are using an aggressive form of anti-virus which prevents programs from executing.
And will additionally create:
%PROGRAMDATA%\appgate\
%APPDATA%\appgate\
%PROGRAMFILES%\appgate sdp\
Upgraded Clients may retain some existing paths even though new paths are now used. This only shows the paths used in new installations.
Configuration settings
To view network adapter
Use ipconfig and look for the Appgate SDP adapter
To view local firewall rules
netsh wfp show filters (as admin, will create a file filters.xml containing the filters)
To view client settings
The user.config file for the client can be found in:
%APPDATA%\Appgate\Appgate_SDP_Service_Url_<some_random_text>\<version>\
To clean all Client settings
Simply delete the file above.
To remove Client profile links
Go to:
%APPDATA%\Appgate\
Delete the files Profiles and ProfileConfigurations.
To remove all stored passwords/Cookies/certificates
Run (Win+R) and perform a search for "certmgr.msc" – Delete certificates under ”AppGate” in the right hand pane of the below panel.
NOTE
You will need admin rights to do this.
Make sure you are using Credential Manager as the correct user (to make sure the correct Generic Credentials are visible), select and then delete the required item.
Windows network category
It is possible to set the Appgate SDP tunnel interface network category to "Private" instead of the default "Public". This is done in the registry.
Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\NetworkList\Profiles and look for one with the ProfileName of AppgateSDP. Go to the Category REG_DWORD and change the value to whichever network profile you want:
Public (0), Private (1) or Domain (2)
Then reboot and it should be set.
Windows route priority
It is possible to delay bringing up the network adapter based on certain routes being available. The following tunable parameters can be set in the registry for the driver:
Go to HKEY_LOCAL_MACHINE\SOFTWARE\Appgate\Driver
below...
"NormalDesktop"="1"
add...
"NeedRoutes"="192.168.1.2/32, 192.168.1.3/32"
"NeedRouteTimeout"="90"
"NeedRouteDelay"="3"
NeedRoutes: A comma separated list of /32 IP addresses entered in the full CIDR notation (for example: "192.168.1.2/32, 192.168.1.3/32"). We recommend to put the DNS servers in this section. Since the DNS servers are the same on all sites, this will always make the adapter to come up once those DNS routes are received.
NeedRouteDelay: A number of seconds - we recommend starting with 3. This is optional, and just adds an additional delay. Since the AD / Kerberos servers could be different based on the nearest sites, this allows some optional delay to make sure that these routes are received also. It is not sure these additional seconds are needed, but we added them for now as additional safety.
NeedRouteTimeout: A number of seconds - we recommend starting with 90. If the NeedRoutes specified are not received after this time, but other Sites are connected, then the network adapter is brought up so Site fallback could be triggered (for example).
Then restart the Client.
Windows device ID
Appgate SDP created a device ID when a Client is first installed. In the case of Windows this is done one of three ways:
Check for a registry entry (which was generated by the installer a long long time ago, if not present go to 2)
Use wmic csproduct get uuid (this can sometimes fail, if so go to 3)
Use HKLM\\SOFTWARE\\Microsoft\\Cryptography\\MachineGuid