When the AppGate client is started, it reads its configuration from several sources, depending on which client is used.

Each user will have his own copy of the current configuration settings. On Windows systems these settings are located in the file agclient.properties in the subdirectory appgate\9.1.4 in the user's profile directory. On Unix systems agclient.properties is located in a directory called .appgate/9.1.4 in the user's home directory.

When starting the installed versions of the client it will first check whether the user has a personal configuration file, if not it will try to read a preinstalled configuration file. On Windows the preinstalled configuration file is typically located in the directory C:\Program Files\AppGate\preinstalled\. On Unix it is typically in /opt/APPGclnt/etc.

The installed client may also use preinstalled hostkeys. This is useful to gain some security and avoid the user being prompted to accept a new host key at the very first connection. On Windows any preinstalled hostkey file should typically go into the directory C:\Program Files\AppGate\preinstalled\hostkeys.

When the installed client has successfully connected to an AppGate server, the client downloads the system-wide configuration settings from the AppGate server, which are normally located in the server file /var/opt/appgate/conf/agclient.properties, and merges these settings with the user's current settings.

The Web Start clients first read the user's configuration, then the configuration file from the AppGate server that provides the Web Start client, and merges these settings with the user's current settings. The Web Start client configuration file is normally located in the file /var/opt/appgate/webroot.local/webstart/agclient.properties.

The configuration file is a plain text file, and consists of statements in the form of:

key = value

Lines starting with '#' are interpreted as comments and ignored.

The key part actually consists of three parts:

server.option.type

where server and type might be optional, depending on the context.

server is the name of the AppGate server, for instance "demo.appgate.com". In system-wide configuration files, the server part should not be specified (since the setting is for a specific system), but in the user's local configuration file the server part must be specified to differentiate settings between different servers.

option is the name of the option to set, for instance 'ag_authmethod'.

type can be empty, 'locked' or 'local'. 'local' is used by the AppGate clients to indicate that the user has changed this value locally. By using 'locked' it indicates that the value can not be changed by the user, so if one for instance uses

ag_authmethod.locked = password

in a system-wide configuration file, the user will always have the authentication method 'Password' selected by default, regardless of whether or not the user changes it temporarily.

On the other hand, if type is not used, the client treats the option from the server as a suggestion. For instance,

ag_authmethod = password

will set the authentication method to 'Password' only if the user does not already have any setting for ag_authmethod.

When the client merges the configurations from different sources, it is using these rules:

The options' values can be changed by substitution of environment variables. For example, on a Windows client machine, this line ssh_privatekey=${USERPROFILE}\\appgate\\my.key will be substituted to ssh_privatekey=C\:\\Documents and Settings\\User Name\\appgate\\my.key by an AppGate client. If the environment variable doesn't exists, the expression will be substituted with an empty string, ssh_privatekey=\\appgate\\my.key.

Using unique local IP addresses is useful if there is more than one server for a certain protocol on the inside which needs to be accessed by the client at the same time. The problem is that every IP access normally listens on 127.0.0.1 for its local port. This implies that only one port forwarding for each port number can be active at a time. However, on Windows and Linux, it is possible to listen on other IP-numbers than 127.0.0.1. These are 127.0.0.2, 127.0.0.3 and so on. This feature is only available on Windows and Linux, and clients will use it by default if available. It is possible to turn this off by setting the option ag_useuniqueips to 'no'.

For this to be useful, the client must be able to write to the hosts file. The client checks this automatically and will not use the feature if it can not write to the hosts file.

The client can be configured to automatically close when the last port forward on a given set of ports is closed. This can be used to automatically close the client when the user for example closes the Citrix client.

Normally when this triggers the client shows a dialog that it is about to close and lets the user have a chance to not close the client. The dialog will time out after a configurable number of seconds and the client will close if the user did not make any choice. It is also possible to configure this so that the dialog is not shown or that the dialog has no timeout.

This feature only works if IP-tunneling is not used. This is because the client does not keep track of the users connections when using IP-tunneling. The feature is also poorly suited to applications which make many short connections to the server, like web browsers. To be useful this feature needs to watch a service where the TCP tunnel is open all the time, like Citrix.

This feature is configured by a couple of client configuration options. The first autoclose_ports is a list of local port numbers to watch. In the case of RDP traffic the local port is not known beforehand so the keyword RDP should be used instead of port number. The feature will trigger when the last open connection over any of these ports is closed. That is if there are no more open connections on any of the watched ports. The second option autoclose_delay controls the timeout. Positive values give the timeout in seconds. A value of 0 means that the dialog will never time out. And a negative value makes the feature disconnect immediately without showing the dialog at all.

The labels of the various authentication data fields presented during login is by default the name of the relevant authentication method.

For example, if the password authentication method is named "Password" then the label for the password field in the login window will be "Password". But if the method is renamed (in the AppGate console) to "Magic Cookie" then the label will also change to "Magic Cookie".

These labels can also be customized with the gui_clientstrings configuration option. The syntax for doing this is:

gui_clientstrings=auth.<auth_method_name>.prompt\=<Custom Label>

Where auth_method_name is the name of the authentication method in lower case with non-alphanumeric characters replaced with '_'.

If there are more than one authentication method label that should be customized then they have to be separated by a newline character (\n) like this:

gui_clientstrings=auth.<auth_method_name_1>.prompt\=<Custom Label 1>\nauth.<auth_method_name_2>.prompt\=<Custom Label 2>...

For example: If there is a authentication method named "Magic Cookie" and the label for the authentication field should read "Passcode", then the following configuration option is needed:

gui_clientstrings=auth.magic_cookie.prompt\=Passcode

When AppGate Applet runs, it pops up its own window but it actually resides in the page in the browser that launched it (the page with the <APPLET> section). This web page must remain 'active' and viewed in the browser for the duration of the AppGate session. If the user changes this page to browse to another page, like pressing the Back button or go to another URL, the applet will immediately be killed by the Java engine of the browser.

To avoid having this web page occupy a seemingly unused browser window, the applet can be embedded into a frame within a frameset. The frameset can then contain two frames: one which is used to view the protected web pages, and one very small where the applet runs.

To accomplish this, the option starturl_frame specifying the name of the frame in which the web page specified by starturl_url will be opened, must be added to the file applet.properties.

Note that the applet will terminate if a web page is opened in the same frame in which the applet is running. The main applet may also be configured to hide itself by adding the gui_hideafterconnect option to the applet.properties file.

One very important link in the AppGate security mechanism is the hostkey system. Hostkeys are used by the AppGate server to prove its identity to the client. This is needed so that the client knows that it is communicating with the correct server, not an imposter. That the hostkeys must be stored on the client machine is a vulnerability. Normally, we recommend that the server hostkeys are included in the client installation packages. However, that does not apply to AppGate Applet, since it has no installation package.

Instead, AppGate Applet has been made so that it can download the needed hostkeys from the server. This method still leaves the problem of trusting the hostkeys it downloaded from the server, since there could be an imposter waging a man-in-the-middle attack during the download. The solution to this is to use HTTPS with a server certificate. Unfortunately, it is not enough to be able to talk HTTPS to the web server. One must also be able to verify the identity of the web server. The only way to do this is for the web browser to trust the root Certificate Authority (CA), which has issued the certificate of the web server.

There are two ways of obtaining a certificate for the web server in the AppGate server. One is to build your own with a toolkit such as OpenSSL. The problem with this approach is that you have to sign it yourself and import that signing certificate manually in all web browsers accessing your site. The other solution is to buy a commercial web server certificate from a publicly recognized CA, such as Verisign, which already has its CA-key in the browsers. In this case, the browser already has the root CA certificate and can verify that the server is who it claims to be.

It is important to consider that web pages may be cached on the local computer by the web browser. This means that sensitive information may be left in the browser cache. This applies for all web-based services (e.g web mail). This is of even higher importance when sensitive information is accessed by using AppGate Applet on a public computer.

It is possible to configure AppGate Applet to clear the Internet Explorer cache on Windows when the AppGate session ends. This is done by creating a client command which uses the agstart special command with command line 'agstart atend clearcache'.

The applet will run as long as the web page that launched it is visible. What happens when the user leaves the web page depends on the browser. Most browsers will terminate the applet immediately, others may wait a little while. The web pages installed by default on the AppGate server display a warning about this. The administrator may choose to use these pages as a template.

Using the starturl_url configuration option in the applet configuration file, the applet may be forced to open a new browser window with a specified URL as soon as the connection to the AppGate server has been established.