- 3.2.1. Installation on Windows
- 3.2.2. Installation on Mac OS X
- 3.2.3. Installation on Solaris
- 3.2.4. Installation on Linux
- 3.2.5. Installation From the Web Server
- 3.2.6. AppGate IP Tunneling Driver Installation
- 3.2.7. AppGate Hosts File Writer Installation
- 3.2.8. Repackaging the AppGate clients
- 3.2.9. Over the air provisioning of mobile clients
The AppGate clients are GUI applications written mostly in Java, with some native code components which handle interfacing with the local operating system, PKI authentication, fast encryption, and compression. The AppGate Client is the most advanced and configurable client program available for use with the AppGate server. The AppGate Client has many options which are configurable by the user. AppGate Connect is a less configurable client and easier to use. The AppGate Applet can be used for system-wide client uniformity and does not require installation, which makes administration easier. This section describes the issues related to the installation of AppGate Client and AppGate Connect.
The following Windows operating systems are supported:
Windows 2000, XP, 2003 or Vista
The AppGate clients can be installed using normal user privileges (administrator rights are not necessary), except on Windows 2000 SP1 (or later) and Windows XP, where administrator privileges are required if the 'Write to hosts file' feature is needed.
To start the installation, run
agclient.exe or similar, depending on which
type of client is to be installed.
These files can be found either on the AppGate USB delivered
with your server, or on the built-in web server on the AppGate
server.
The installer uses a graphical dialog which should be familiar
to most users. If anything goes wrong during the installation, the
installation log can give useful information about the problem.
The log is viewed with the button 'Show details' during installation,
and is saved as install.log in the installation
directory.
An alternative method is to use Java Web Start. Java Web Start requires that Java version 1.3.x or higher is already installed on the client computer. In order for the 'Write to hosts file' feature to work, the user must be administrator. The AppGate Client Web Start link is found on the built-in web server.
Usually when AppGate clients are installed, a number of dialogs are presented to the user, enabling the user to choose such things as where to install the AppGate clients. To further simplify things for the end user, the installation can be run silently by adding the option /S to the installation program:
agclient.exe /S
The Windows AppGate client installation includes a complete Java Runtime Environment that is solely intended to be used with and by the AppGate clients. For this purpose, the JRE has been modified so that it does not read or modify the registry.
This modification ensures that no conflict with other versions of JRE installed on the system, past or future, will occur. Other unmodified versions of JRE can use the registry entries relevant to JRE for their own purposes without affecting the AppGate clients.
It is not recommended to use the JRE included with the AppGate client for other purposes than running the AppGate clients.
The AppGate clients for Mac OS X are distributed as disk images. To install one, open the disk image and install the meta package in the top level directory. This will install the client and the AppGate Local Forwarder. The default installation path for the client is the system-wide Applications directory, but it is possible to select another path during installation.
Administrator privileges are required to install the meta packages, since they include the AppGate Local Forwarder. If the AppGate Local Forwarder should not be installed, it is possible to install the client package from the 'packages' directory. This does not require administrator privileges, but automatic hosts file writing and forwarding of privileged ports will not be available.
AppGate Local Forwarder installs the program
/usr/local/libexec/appgatefwd ,
which runs with root privileges ("setuid root"). This is used by
the AppGate clients to forward privileged ports and update the local
hosts file. When this program is installed, any user who can log
on to the system can add entries to
/etc/hosts which redirect traffic to the
local host, and it is possible to listen to privileged TCP
ports.
Warning
Security considerations: By using these features, any user who has access to an account on the machine can, for instance, redirect all connections to a specified web server to a malicious program. The malicious program may try to convince the local user to enter his password. Depending on how the Mac OS X client is used, the administrator should decide whether AppGate Local Forwarder should be installed or not.
If AppGate Local Forwarder has been installed, its features can be disabled by executing the following command as root from a terminal window:
chmod u-s
/usr/local/libexec/appgatefwd
and it can later be enabled again with the following command:
chmod u+s
/usr/local/libexec/appgatefwd
AppGate Local Forwarder writes to the file
/etc/hosts in order to transparently
redirect connections through encrypted SSH tunnels. This file is
normally not read by the system after reboot, but the
installation of AppGate Local Forwarder modifies the lookup
order to take advantage of this file. This is achieved by
creating the file /etc/lookupd/hosts to use
the /etc/hosts file before consulting DNS and
NetInfo. If the Mac OS X client is configured not to use the
files in /etc/lookupd , this will not be
effective and the administrator must make the appropriate
modifications by hand.
NOTE: The modification of the lookup order tries to be
conservative so as not to break the existing configuration. If
the file /etc/lookupd/hosts already exists,
it will not be overwritten, and if NetInfo is used, the files in
/etc/lookupd should be ignored. Some versions
of Mac OS X do not honor this, and the existence of the
/etc/lookupd directory disables other NetInfo
lookups. This may cause systems with local modifications to
change their behavior. In this case, the administrator should
back out the changes made by the installation of AppGate Local
Forwarder.
All AppGate clients require that Java is installed on the client machine to be able to run.
The client software for the Solaris platform is found on
the USB in the AppGate/client/SunOS directory.
The directory contains several packages with manual pages and executables.
For instance, to install the AppGate Client package, run
cd /usb_mountpoint/appgate/AppGate/client/SunOS/`uname -p`
cp APPGclnt.pkg.gz /tmp
cd /tmp
gunzip APPGclnt.pkg.gz
pkgadd -d APPGclnt.pkg APPGclnt
Installing the client places the files of this package in
/opt/APPGclnt. A bin
directory and a man
directory will be created to hold the executables and the manual
pages. Start the AppGate Client by executing
/opt/APPGclnt/bin/agclient.
No further configuration of this package should be necessary.
To pre-configure a Solaris installation, create a file
named agclient.properties with the desired properties in the
/opt/APPGclnt/bin directory. See Section 3.4, “Client configuration”
for configuration options.
All AppGate clients require that Java is installed on the client machine to be able to run.
The client software for the Linux platform is found on the
USB in the AppGate/client/Linux directory. The
AppGate Client can be extracted/installed by executing the
following command:
bzip2 -cd /path_to/agclient.i386.tar.bz2 | tar xf -
A subdirectory structure called opt/APPGclnt
will then be created in the current directory. Start the AppGate Client by
executing the file opt/APPGclnt/bin/agclient
The AppGate client may be distributed to users through the AppGate web server. If this method is used, each user needs to connect to the AppGate server with a web browser. Once connected, the user will be presented with a screen similar to the following.
The user may then click on the platform they are installing on. A File Download dialog box will then appear asking whether the user would like to run agclient.exe from its current location or save the file to disk. The user must select one of the two options and click OK for the download and installation to begin.
If the user chooses to run agclient.exe from its current location, the executable will automatically self-extract the package and begin the installation. If the user saves the file to disk, he must double-click on agclient.exe after it has finished downloading in order for the extraction and installation to begin.
From that point onward, the installation will behave identically to a generic USB installation (or a distributed installation package with no pre-configuration).
The AppGate IP Tunneling Driver can only be installed on computers running Windows XP or later, Linux, Mac OS X or Solaris. Administrator privileges are required for the installation.
If the AppGate IP tunneling driver should be upgraded, the previous version has to be uninstalled first.
The AppGate Hosts File Writer can only be installed on
computers running Windows 2000, Windows XP or Windows 2003.
Administrator privileges are required for the installation. The
installation file is named aghostsd.exe.
It is possible to wrap the AppGate clients for Windows into a new installation package. This is usually done to achieve one of the following goals:
Make a single installation package containing any or all of the clients, Device Firewall and IP Tunneling Driver.
Distribute host keys to avoid the first time connection vulnerability.
Install a modified agclient.properties file along with the client.
Please refer to the AppGate Support Web for detailed instructions regarding the necessary components.
Over the air provisioning is a way to install and configure the AppGate client on a mobile phone over the air. The administrator can make the AppGate server send SMSes to the mobile phone. The first SMS contains a link to the client installation package and once installed the client will use the second SMS to configure itself. It is also possible to automatically setup email accounts on the phone.
The net effect is making it easy for the mobile phone user to get started. They just need to press Ok a couple of times and enter their password before they are set up and can read their email. The whole goal of this is to make it as easy as possible for users to get started using Appgate to access their email from a mobile phone.
The first step is that the administrator triggers provisioning for the user. This is done on the local user management screen. Once the user's mobile phone number has been entered the administrator just needs to press the provision button.
Pressing the provision button causes the AppGate server to send two SMSes to the phone. The first SMS will contain a short text and a hypertext link back to the AppGate server. Pressing the link will cause the mobile phone to download the appropriate client installation package (the server uses the web request to figure out which phone model the user has). Once downloaded the client installation will start automatically (on all platforms but SonyEricsson).
The default behavior of the Appgate server is to send the SMSes through a gateway at appgate.com. Any firewall between the AppGate server and the Internet must allow the AppGate to establish a TCP connection to port 443 on provisioning.appgate.com. This gateway will allow all customers with a valid support contract to send a certain number of SMSes per month (currently 50). Customers wishing to send more need to have a separate contract for SMS sending.
When the client starts for the first time it will look for the second SMS which contains the information needed to know where to get the actual configuration. The client will then use this information to download the actual configuration from the AppGate server. The downloaded configuration includes things like name of Appgate server, authentication method and user name. The only thing the users need to enter is their passwords or other authentication data.
Once connected the client downloads the list of services as usual. But there are a couple of new client commands which may help with the user experience in this situation. There is one which creates an ordinary email account. It is also possible to create an Exchange account on Windows Mobile phones.
There is also support for downloading the exchange client for Sony Ericsson and Nokia phones.
This section covers various actions which the AppGate administrator may have to perform to set up over the air provisioning.
The basic configuration is done in the AppGate console under "Clients/Mobile Client Configuration". Here it is possible to configure which addresses the clients should use when contacting the server, the text of the SMS and other things related to provisioning.
Life for the end user becomes really easy if the administrator sets up client commands to configure and launch the email client. This done with the following client command:
mailaccount [-domain MAILDOMAIN] [-launch]
This client command should normally be set on the
*.*.mobile platform. The -domain and
-launch sections are optional. -domain will help with the
configuration and -launch will start the email client. This
client command will check to see if the email account already
exists, if not it is created. Finally, if -launch is provided
the email client is launched.
The situation is more complex if the email server is running Exchange. Both Nokia and Sony Ericsson make Exchange clients for their phones available on their web sites. AppGate may not, for legal reasons, redistribute those clients but we can redirect users to them. The redirection can be configured in the AppGate console. The administrator may either enter the relevant URLs manually or configure the AppGate server to automatically download the URLs from appgate.com once a day.
The client command which downloads the Exchange client is:
browse http://appgate_server_addr/agmobile?asclient
But this command should only be run if the client is not already installed. Fortunately a client check can check if the client is already installed. Create the following two client checks:
| Attribute | activesync_client_installed |
| Platform | symbian.s60e3.mobile |
| Command | check.exe |
| Arguments | -application easapp.exe |
| Attribute | activesync_client_installed |
| Platform | symbian.uiq3.mobile |
| Command | check.exe |
| Arguments | -application roadsync.exe |
Once that is done the following access rule will check if the Exchange client is installed:
| Name | symbian_without_activesync |
| Expression | attribute{activesync_client_installed="no"} and attribute{platform="^symbian\.[^.]*\..*"} |
use this access rule to give access to the Exchange client download command.
To configure an Exchange account for the user use the following command on a windows mobile phone:
syncaccount [-domain MAILDOMAIN] [-launch]
Set the platform to windowsce.*.*.
Both cases above causes the email client to connect to the localhost. There must also be an IP-access component available which forwards this port to the appropriate mail server. In the exchange case local port 80 must be forwarded to port 80 on the exchange server. For IMAP/SMTP ports 25 and 443 must be forwarded to the mail server.