cClient 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 ZTNA 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 uninstall one type before changing to another type of Windows client. Never try to partially uninstall the client such as only removing the AppGate ZTNA driver.
It is not uncommon 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 given access within the end-point protection software.
Using Windows events to check if AppGate ZTNA is connected
Windows logs are created by the AppGate ZTNA driver. These can be seen in the Event Viewer where the Source will be shown as <AppGate ZTNA 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 client settings. |
NOTE
If scripting the installer using PowerShell you should add an extra pair of single quotes ' ' around any double quotes " ". e.g. xxx.exe /P='"myurl"'.
Windows client - Components/Executables
Standard Executables
Appgate SDP Service.exe Will run as USER - they handle the business logic. |
|
Appgate SDP.exe Multiple processes that run as USER - they handle the UI. |
|
appgate-driver.exe The virtual network adapter that runs as SYSTEM - it handles connections to the Gateways. |
|
NOTE
You might need to give access to some or all of these if you are using an aggressive form of antivirus which prevents programs from executing.
These 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
View the network adapter | Use
|
View local firewall rules | Use |
View client settings | The user.config file for the client can be found in: |
Clean all client settings | Simply delete the user.config file. |
Remove client profile links | Go to |
Remove all stored passwords, cookies, and certificates | With admin rights, run (Win+R) and perform a search for "certmgr.msc". Delete certificates under ”AppGate” in the right hand-pane of the below panel.
Make sure you are using Credential Manager as the correct user (to ensure the correct generic credentials are visible), then select and delete the required item. |
Set Windows network category to Private |
|
Set Windows route priority |
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 putting 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. The delay in seconds. We recommend starting with 3. This is an optional, additional delay. Since the AD/Kerberos servers could be different based on the nearest Sites, this adds an optional delay to ensure these routes are also received. NeedRouteTimeout. Timeout in 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 to trigger Site fallback. |
Find Windows device ID | AppGate ZTNA creates a device ID when a client is first installed. For Windows this is done one of three ways:
|
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 ZTNA 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 ZTNA 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 given access within the end-point protection software.
Using Windows Events to check if AppGate ZTNA is connected
Windows logs are created by the AppGate ZTNA driver. These can be seen in the Event Viewer where the Source will be shown as <AppGate ZTNA 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 client settings. |
NOTE
If scripting the installer using PowerShell you should add an extra pair of single quotes ' ' around any double quotes " ". e.g. xxx.exe /P='"myurl"'.
Windows client - Components/Executables
Standard Executables
Appgate SDP Service.exe Will run as USER - they handle the business logic. |
|
Appgate SDP.exe Multiple processes that run as USER - they handle the UI. |
|
appgate-driver.exe The virtual network adapter that runs as SYSTEM - it handles connections to the Gateways. |
|
NOTE
You might need to give access to some or all of these if you are using an aggressive form of antivirus which prevents programs from executing.
These 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
View the network adapter | Use
|
View local firewall rules | Use |
View client settings | The user.config file for the client can be found in: |
Clean all client settings | Simply delete the user.config file. |
Remove client profile links | Go to |
Remove all stored passwords, cookies, and certificates | With admin rights, run (Win+R) and perform a search for "certmgr.msc". Delete certificates under ”AppGate” in the right hand-pane of the below panel.
Make sure you are using Credential Manager as the correct user (to ensure the correct Generic Credentials are visible), then select and delete the required item. |
Set Windows network category to Private |
|
Set Windows route priority |
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 putting 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. The delay in seconds. We recommend starting with 3. This is an optional, additional delay. Since the AD/Kerberos servers could be different based on the nearest Sites, this adds an optional delay to ensure these routes are also received. NeedRouteTimeout. Timeout in 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 to trigger Site fallback. |
Find Windows device ID | AppGate ZTNA creates a device ID when a client is first installed. For Windows this is done one of three ways:
|