Chapter 5 Working with Netlet

This chapter describes how to use Netlet to run applications securely between users’ remote desktops and the servers running applications on your intranet. To configure Netlet, see Chapter 11, Configuring Netlet.

This chapter contains the following sections:

• Overview of Netlet

• Downloading an Applet From a Remote Host

• Defining Netlet Rules

• Sample Netlet Rules

• Enabling Netlet Logging

• Enable Debug Logging

• Running Netlet in a Sun Ray Environment

Overview of Netlet

Sun Java System Portal Server software users may want to run popular or company-specific applications on their remote desktops in a secure manner. You can provide secure access to these applications by setting up Netlet on your platform.

Netlet enables users to securely run common TCP/IP services over insecure networks such as the Internet. You can run TCP/IP applications (such as Telnet and SMTP), HTTP applications, and any fixed port applications.

If an application is TCP/IP-based or it uses fixed ports, you can run the application over Netlet. .

Dynamic ports are supported only when FTP is used. To use Microsoft Exchange, use OWA (Outlook Web Access).

Ensure that you notify the users to disable the pop-up blockers options in their browser, when using Netlet.

Netlet Components

The various components used by Netlet are shown in Netlet Components.

Figure 5–1 Netlet Components

Listen Port on localhost

This is the port on the client machine on which the Netlet applet listens. The client machine is the localhost.

Netlet Applet

The Netlet applet is responsible for setting up an encrypted TCP/IP tunnel between the remote client machine and intranet applications such as Telnet, Graphon or Citrix. The applet encrypts the packets and sends them to the Gateway, and decrypts the response packets from the Gateway and sends them to the local application.

For static rules the Netlet applet is downloaded automatically when the user logs into the portal. For dynamic rules, the applet is downloaded when the user clicks on the link corresponding to the dynamic rule. See Types of Rules for details on static and dynamic rules.

To run Netlet in a Sun Ray Environment, see Running Netlet in a Sun Ray Environment.

Netlet Rules

A Netlet rule maps an application that needs to run on a client machine to the corresponding destination host. This means that Netlet operates only on packets sent to ports defined in the Netlet rule. This ensures greater security.

As an administrator, you need to configure certain rules for the functioning of Netlet. These rules specify various details such as the cipher to be used, URL to invoke, the applets to be downloaded, the destination port and the destination host. When a user on a client machine makes a request through Netlet, these rules help determine how the connection must be established. See Defining Netlet Rules for details.

Netlet Provider

This is the UI component of Netlet. The provider allows users to configure the required applications from the Portal Server desktop. A link is created in the provider, and the user clicks on this to run the required application. Users can also specify the destination host for a dynamic rule in the desktop Netlet provider. See Defining Netlet Rules.

Netlet Proxy (Optional)

The Gateway ensures a secure tunnel between the remote client machine and the Gateway. The Netlet proxy is optional and you may choose not to install this proxy during the installation. For information on the Netlet proxy, see Using a Netlet Proxy.

Netlet Usage Scenario

The following sequence of events are involved in using Netlet:

1. The remote user logs into the Portal Server desktop.

2. If a static Netlet rule has been defined for a user, role or organization, the Netlet applet is automatically downloaded to the remote client.

   If a dynamic rule has been defined for a user, role, or organization, the user needs to configure the required application in the Netlet provider. The Netlet applet is downloaded when the user clicks on the application link in the Netlet provider. See Defining Netlet Rules for details on static and dynamic rules.

3. Netlet listens on the local ports defined in the Netlet rules.

4. Netlet sets up a channel between the remote client and host over the ports specified in the Netlet rule.

Working With Netlet

For Netlet to work as required for various users across different organizations, you need to do the following:

1. Determine whether you need to create static or dynamic rules based on the user requirements. See Types of Rules.

2. Configure the options for the Netlet service from the Portal Server administration console. For information on configuring Netlet, see Chapter 11, Configuring Netlet.

3. Determine whether the rules should be organization, role, or user based and make modifications as required at each level. See the Portal Server Administration Guide for details on organization, role and user.

   ---

   Note –

   Do not localize the value for the frameset parameter in the srapNetletServlet.properties file.

   ---

Downloading an Applet From a Remote Host

Sometimes a page is returned by a URL that contains an embedded applet that needs to be fetched from a remote machine. However Java security does not allow an applet to communicate with a host that it is not downloaded from. To allow the applet to communicate with the Gateway through the local network port, you need to check the Download Applet field on the Access Manager administration console and specify the following syntax:

local-port:server-host:server-port

where

local-port is the local port where Netlet listens for traffic originating from the applet

server-host is where the applet is to be downloaded from

server-port is the port used to download the applet

Defining Netlet Rules

Netlet configuration is defined by Netlet rules that are configured using the Portal Server administration console under the Secure Remote Access configuration tab. Netlet rules can be configured for organizations, roles, or users. If the Netlet rule is for a role or user, select the desired role or user after selecting the organization.

Netlet rules do not support multibyte entries. Do not specify multibyte characters for any of the fields in Netlet rules.

Netlet rules cannot contain any port number higher than 64000.

Defining Netlet Rules lists the fields in a Netlet rule.

For the Gateway to get the session notification from Portal Server, add the following:

com.iplanet.am.jassproxy.trustAllServerCerts=true

to the following property file

/etc/opt/SUNWam/config/AMConfig.instance-name.properties on the Portal Server

Types of Rules

Two types of Netlet rules are based on how the destination host is specified in the rule.

Static Rule

A static rule specifies a destination host as part of the rule. If you create a static rule, the user does not have the option to specify the required destination host. In the following example, sesta is the destination host.

You can configure multiple destination hosts and ports for static rules. See Static Rule With Multiple Host Connections for an example.

Dynamic Rule

In a dynamic rule, the destination host is not specified as a part of the rule. The user can specify the required destination host in the Netlet provider. In the following example, TARGET is the placeholder for the destination host.

Encryption Ciphers

Based on the encryption cipher, Netlet rules can be further classified as follows:

• User Configurable Cipher Rules - In this rule, you can specify a list of ciphers that users can choose from. These optional ciphers appear as a list in the Netlet provider. The user can choose the required cipher from the list. In the following example, the user can choose from multiple ciphers.

Although the Portal Server host may have various ciphers enabled, the user can choose only from the list that is configured as part of the Netlet rule.

See Supported Ciphers for a list of the ciphers supported by Netlet.

• Administrator Configured Cipher Rules - In this rule, the cipher is defined as part of the Netlet rule. The user does not have the option to choose the required cipher. In the following example, the cipher is configured to be SSL_RSA_WITH_RC4_128_MD5.

See Supported Ciphers for a list of ciphers supported by Netlet.

Supported Ciphers

Supported Ciphers lists the ciphers supported by Netlet.

Backward Compatibility

Earlier versions of Portal Server did not support ciphers as part of the Netlet rules. For backward compatibility with existing rules without ciphers, a default cipher is used by the rules. An existing rule without ciphers such as:

is interpreted as:

This is similar to an Administrator Configured Rule with the Encryption cipher field chosen as Default.

Netlet rules cannot contain any port number higher than 64000.

Netlet Rule Examples

This section contains some examples of Netlet rules to illustrate how Netlet syntax works.

• Basic Static Rule

• Static Rule With Multiple Host Connections

• Dynamic Rule to Invoke a URL

• Dynamic Rule to Download an Applet

Basic Static Rule

This rule supports a Telnet connection from the client to the machine sesta.

where

myrule is the name of the rule.

SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.

null indicates that this application is not invoked by a URL or run through the desktop.

false indicates that the client does not download an applet to run this application.

true indicates that Portal Server should not time out when the Netlet connection is active.

1111 is the port on the client where Netlet listens for a connection request from the destination host.

sesta is the name of the recipient host in the Telnet connection.

23 is the port number on the destination host for the connection, in this case the well-known port for Telnet.

The desktop Netlet provider does not display a link, but Netlet automatically starts and listens on the port specified (1111). Instruct the user to start the client software - in this case a Telnet session that connects to localhost on port 1111.

For example, to start the Telnet session, the client needs to type the following on the UNIX command line in a terminal:

telnet localhost 1111

Static Rule With Multiple Host Connections

This rule supports a Telnet connection from the client to two machines, sesta and siroe.

where

23 is the port number on the destination host for the connection– reserved port for Telnet.

1111 is the port on the client where Netlet listens for a connection request from the first destination host sesta.

1234 is the port on the client where Netlet listens for a connection request from the second destination host siroe.

The first six fields in this rule are the same as in Basic Static Rule. The difference is that three more fields identify the second destination host.

When you add additional targets to a rule, you must add three fields, local port, destination host, and destination port, for each new destination host.

You can have multiple sets of three fields describing the connection to each destination host. Listen port numbers which are less than 2048 must not be used if the remote client is UNIX-based because low numbered ports are restricted and you must be root to start a listener.

This rule works the same as the previous rule. The Netlet provider does not display any link, but Netlet automatically starts and listens on the two ports specified (1111 and 1234). The user needs to start the client software, in this case a Telnet session that connects to localhost on port 1111 or the localhost on port 1234 to connect to the host in the second example.

Static Rule with Multiple Host Selection

Use this rule to specify multiple alternative hosts. If connection to the first host in the rule fails, Netlet tries to connect to the second host specified and so on.

where

10491 is the port on the client where Netlet listens for a connection request from the destination host.

Netlet tries to establish connection with siroe on port 35, port 26 and port 491 in the same order, depending on which one is available.

If connections to siroe are not possible, Netlet tries to connect to sesta on port 35 and 491 in the same order.

The plus (+) sign between hosts indicates alternative hosts.

The plus (+) sign between ports numbers indicates the alternative ports for a single destination host.

The minus (-) sign between port numbers is the separator between the port numbers for different destination hosts.

Dynamic Rule to Invoke a URL

This rule enables a user to configure the destination host required, enabling the user to telnet to various hosts over Netlet.

where

myrule is the name of the rule.

SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.

telnet://localhost:30000 is the URL invoked by the rule.

false indicates that no applets are to be downloaded.

Extend Session(true) indicates that the Portal Server should not time out when the Netlet connection is active.

30000 is the port on the client where Netlet listens for connection requests for this rule.

TARGET indicates that the destination host needs to be configured by the user using the Netlet provider.

23 is the port on the destination host opened by Netlet, in this case the well-known port for Telnet.

To Run Netlet After a Rule is Added

After this rule is added, the user must complete some steps to get Netlet running as expected. The user needs to do the following on the client side:

1. Click Edit in the Netlet provider section of the standard Portal Server desktop.

   The new Netlet rule is listed under Rule Name in the Add New Target section.

2. Choose the rule name and type the name of the destination host.

3. Save the changes.

   The user returns to the desktop with the new link visible in the Netlet provider section.

4. Click the new link.

   A new browser is launched that goes to the URL given in the Netlet rule.

   ---

   Note –

   You can add more than one destination host for the same rule by repeating these steps. Only the last link selected is active.

   ---

Dynamic Rule to Download an Applet

This rule defines a connection from the client to hosts that are dynamically allocated. The rule downloads a GO-Joe applet from the server on which the applet is located, to the client.

where

gojoe is the name of the rule.

SSL_RSA_WITH_RC4_128_MD5 indicates the cipher to be used.

/gojoe.html for example is the path of the HTML page containing the applet, the path should be relative to the documentation root of the web container on which portal is deployed.

8000:server:8080 indicates that port 8000 is the destination port on the client to receive the applet, gojoeserve is the name of the server providing the applet, and 8080 is the port on the server from which the applet is downloaded.

Extended Session (true) indicates that the Portal Server should not time out when the Netlet connection is active.

3399 is the port on the client where Netlet listens for connection requests of this type.

TARGET indicates that the destination host needs to be configured by the user using the Netlet provider.

58 is the port on the destination host opened by Netlet, in this case the port for GoJoe. Port 58 is the port that the destination host listens to for its own traffic. Netlet passes information to this port from the new applet.

Sample Netlet Rules

Sample Netlet Rules lists sample Netlet rules for some common applications.

The table has 7 columns corresponding to the following fields in a Netlet rule: Rule Name, URL, Download Applet, Local Port, Destination Host, Destination Port. The last column includes a description of the rule.

Sample Netlet Rules does not list the Cipher and Extend Session fields of the Netlet rule. Assume these to be "SSL_RSA_WITH_RC4_128_MD5" and "true" for the samples provided.

Enabling Netlet Logging

You can enable logging of Netlet related activities in the Gateway service. . The log files are created in the directory specified in the Log Location attribute as part of the Logging section of the Portal Server administration console.

The log file name has the following convention:

srapNetlet_gateway-hostname_gateway-profile-name

The Netlet log captures the following information:

• Start time

• Source address

• Source port

• Server address

• Server port(s)

• Stop time

• Status (start or stop)

Enable Debug Logging

The location of the debug information depends on the setting of the com.iplanet.services.debug.directory attribute in the AMConfig-instance-name.properties file on the Portal Server node.

For example, if the value of the com.iplanet.services.debug.directory attribute is:

/var/opt/SUNWam/debug/

Then the debug information for Netlet is available in the srapNetlet file in the /var/opt/SUNWam/debug directory.

Running Netlet in a Sun Ray Environment

If you want to run an application which requires the applet to be downloaded to the client machine on a Sun Ray environment, you need to change the HTML file. Here is a sample file showing you the necessary modifications that need to be done.

New HTML File

<!-- @(#)citrix_start.html 2.1
98/08/17 Copyright (c) 1998 i-Planet, Inc., All rights reserved.-->
<html>
<script language="JavaScript">
var KEY_VALUES;  // KEY_VALUES[\qkey\q] = \qvalue\q;
function retrieveKeyValues() {
      KEY_VALUES = new Object();
      var queryString  = \q\q + this.location;
      queryString = unescape(queryString);
      queryString = queryString.substring((queryString.indexOf(\q?\q)) + 1);
      if (queryString.length < 1) {
          return false; }
      var keypairs = new Object();
      var numKP = 0;
      while (queryString.indexOf(\q&\q) > -1) {
        keypairs[numKP] = queryString.substring(0,queryString.indexOf(\q&\q));
        queryString = queryString.substring((queryString.indexOf(\q&\q)) + 1);
        numKP++;
      }
      // Store what\qs left in the query string as the final keypairs[] data.
      keypairs[numKP++] = queryString;
      var keyName;
      var keyValue;
      for (var i=0; i < numKP; ++i) {
        keyName = keypairs[i].substring(0,keypairs[i].indexOf(\q=\q));
        keyValue = keypairs[i].substring((keypairs[i].indexOf(\q=\q)) + 1);
        while (keyValue.indexOf(\q+\q) > -1) {
          keyValue = keyValue.substring(0,keyValue.indexOf(\q+\q)) + \q \q
           + keyValue.substring(keyValue.indexOf(\q+\q) + 1);

        }
        keyValue = unescape(keyValue);
          // Unescape non-alphanumerics
        KEY_VALUES[keyName] = keyValue;
      }
}
function getClientPort(serverPort) {
    var keyName = "clientPort[\q" + serverPort +"\q]";
    return KEY_VALUES[keyName];
}
function generateContent() {
    retrieveKeyValues();
    var newContent =
        "<html>\\n"
          + "<head></head>\\n"
          + "<body>\\n"
          + "<applet code=\\"com.citrix.JICA.class\\" archive=\\
               "JICAEngN.jar\\" width=800 height=600>\\n"
          + "<param name=\\"cabbase\\" value=\\"JICAEngM.cab\\">\\n"
          + "<param name=\\"address\\" value=\\"localhost\\">\\n"
          + "<param name=ICAPortNumber value="
          + getClientPort(\q1494\q)
          + ">\\n"
          + "</applet>\\n"
          + "</body>\\n"
          + "</html>\\n";
    document.write(newContent);
}
</script>
<body onLoad="generateContent();">
</body>
</html>

Deprecated HTML File

<html>
<body>
<applet code="com.citrix.JICA.class" archive=
   "JICAEngN.jar" width=800 height=600>
<param name="cabbase" value="JICAEngM.cab">
<param name="address" value="localhost">
<param name=ICAPortNumber value=1494>
</applet>
</body></html>