|
| |
| Sun Java System Portal Server Secure Remote Access 6 2005Q1 Administration Guide | |
Chapter 5
NetletThis 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 covers the following topics:
Overview of NetletSun 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. .
Note
Dynamic ports are supported only when FTP is used. To use Microsoft Exchange, use OWA (Outlook Web Access).
Netlet Components
The various components used by Netlet are shown in Figure 5-1.
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:
- The remote user logs into the Portal Server desktop.
- 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.
- Netlet listens on the local ports defined in the Netlet rules.
- 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:
- Determine whether you need to create static or dynamic rules based on the user requirements. See Types of Rules.
- Define the global options in the Netlet template from the Service Configuration tab on the Access Manager administration console. See Chapter 11, "Configuring Netlet".
- 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.
Downloading an Applet From a Remote HostSometimes 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 RulesNetlet configuration is defined by Netlet rules that are configured in the Access Manager administration console under the SRA Configuration section. 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.
Table 5-1 lists the fields in a Netlet rule.
Table 5-1 Fields in a Netlet Rule
Parameter
Description
Value
RuleName
Designates a name for this Netlet rule. You need to specify a unique name for each rule. This is useful while defining user access to specific rules. See Define Access to Netlet Rules for details.
Encryption Ciphers
Defines the encryption cipher, or specifies the list of ciphers that the user can choose from.
The ciphers that you select appear in the Netlet provider as a list. The user can choose the required ciphers from the selected list.
Default - The Default VM Native Cipher and the Default Java Plugin Cipher specified in the Netlet administration console are used.
URL
Specifies the URL that the browser opens when the user clicks the associated link in the Netlet provider. The browser opens the window for the application and connects to localhost at the local port number specified later in the rule.
You need to specify a relative URL.
URL to the application invoked by the Netlet rule. For example, telnet://localhost:30000.
Specify a URL if the application uses an applet to invoke the application.
null – Value that you set if the application is not started by a URL or controlled by the desktop. This is normally true for non-web-based applications.
Download Applet
Indicates whether it is necessary to download an applet for this rule.
False - Do not download an applet.
True - Download the applet from the Portal Server machine using the loopback port.
Specify the applet details in the format local-port:server-host:server-port where:
- local-port indicates the destination port on the client. This port must be different from the default loopback port. See Chapter 11, "Configuring Netlet" for details. Specify a unique local port for each rule.
- server-host is the name of the server from which to download the applet.
- server-port represents the port on the server used to download the applet.
If an applet is to be downloaded, and if the server is not specified, the applet is downloaded from the Portal Server host.
Extend Session
This controls the idle time-out of a Portal Server session when Netlet is active.
True - This is required to keep the portal session alive when only Netlet is active and the rest of the portal application is idle.
False - The portal session idle times out at session idle time-out even though the Netlet application is active and the rest of the portal application is idle.
Local Port
Port on the client where Netlet listens.
The value of local-port must be unique. You cannot specify a particular port number in more than one rule.
Specify multiple local ports if you are specifying multiple hosts for multiple connections. See Static Rule With Multiple Host Connections for the syntax.
For an FTP rule the local port value must be 30021.
Destination Host(s)
Recipient of the Netlet connection.
host - Name of the host to receive the Netlet connection. This is used in a static rule. Use either the simple host name such as siroe, or a fully-qualified DNS-style host name such as siroe.mycompany.com. Specify multiple hosts for the following reasons:
- to establish connection with each host specified. You need to specify the corresponding client and destination ports for each host specified. See Static Rule With Multiple Host Connections for the syntax.
- to try to connect to any available host from the list of hosts specified. See Static Rule with Multiple Host Selection for the syntax.
TARGET - Rules that specify TARGET in the syntax are dynamic rules. TARGET indicates that end-users can specify the required destination host or hosts in the Netlet provider of the desktop.
You cannot have a combination of a static host and TARGET in a single rule.
Destination Port(s)
The port on the destination host
In addition to the host and destination host, you must specify a destination port.
You can specify multiple destination ports in case of multiple destination hosts. Specify multiple ports in the format port1+port2+port3-port4+port5.
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.
Here, Netlet tries to connect to the first destination host specified using port1, port2 and port3 in order. If this fails, Netlet tries to connect to the second host using port4 and port5 in that order.
You can configure multiple ports only for static rules.
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
2. Restart the Access Manager.
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.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
ftpstatic
SSL_RSA_WITH_RC4_128_MD5
null
false
true
30021
sesta
21
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.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host
Destination Port(s)
ftpdynamic
SSL_RSA_WITH_RC4_128_MD5
null
false
true
30021
TARGET
21
Encryption Ciphers
Based on the encryption cipher, Netlet rules can be further classified as follows:
See Supported Ciphers for a list of the ciphers supported by Netlet.
See Supported Ciphers for a list of ciphers supported by Netlet.
Supported Ciphers
Table 5-2 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:
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
Telnet
telnet://localhost:30000
false
true
30000
TARGET
23
is interpreted as:
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
Telnet
Default ciphers
telnet://localhost:30000
false
true
30000
TARGET
23
This is similar to an Administrator Configured Rule with the Encryption cipher field chosen as Default. See Specify the Default Encryption Cipher for details.
Netlet Rule Examples
This section contains some examples of Netlet rules to illustrate how Netlet syntax works.
Basic Static Rule
This rule supports a Telnet connection from the client to the machine sesta.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
null
false
true
1111
sesta
23
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:
Static Rule With Multiple Host Connections
This rule supports a Telnet connection from the client to two machines, sesta and siroe.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
null
false
true
1111
sesta
23
1234
siroe
23
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.
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.
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.
Rule Name
Encryption Cipher
URL
Download Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
myrule
SSL_RSA_WITH_RC4_128_MD5
telnet://localhost:30000
false
true
30000
TARGET
23
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:
- 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.
- Choose the rule name and type the name of the destination host.
- Save the changes.
The user returns to the desktop with the new link visible in the Netlet provider section.
- Click the new link.
A new browser is launched that goes to the URL given in the Netlet rule.
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.
Rule Name
Encryption Cipher
URL
Downlaod Applet
Extend Session
Local Port
Destination Host(s)
Destination Port(s)
gojoe
SSL_RSA_WITH_RC4_128_MD5
/gojoe.html
8000:gojoeserver:8080
true
3399
TARGET
58
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 RulesTable 5-3 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.
Note
Table 5-3 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 LoggingYou can enable logging of Netlet related activities in the Gateway service. See Enable Netlet Logging. The log files are created in the directory specified in the Log Location attribute as part of the Logging section of the Access Manager Configuration attributes.
The log file name has the following convention:
srapNetlet_gateway-hostname_gateway-profile-name
The Netlet log captures the following information:
Enable Debug LoggingThe 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.
See the Access Manager Administration Guide for more information.
Running Netlet in a Sun Ray EnvironmentIf 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['key'] = 'value';
function retrieveKeyValues() {
KEY_VALUES = new Object();
var queryString = '' + this.location;
queryString = unescape(queryString);
queryString = queryString.substring((queryString.indexOf('?')) + 1);
if (queryString.length < 1) {
return false; }
var keypairs = new Object();
var numKP = 0;
while (queryString.indexOf('&') > -1) {
keypairs[numKP] = queryString.substring(0,queryString.indexOf('&'));
queryString = queryString.substring((queryString.indexOf('&')) + 1);
numKP++;
}
// Store what's 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('='));
keyValue = keypairs[i].substring((keypairs[i].indexOf('=')) + 1);
while (keyValue.indexOf('+') > -1) {
keyValue = keyValue.substring(0,keyValue.indexOf('+')) + ' ' + keyValue.substring(keyValue.indexOf('+') + 1);
}
keyValue = unescape(keyValue);
// Unescape non-alphanumerics
KEY_VALUES[keyName] = keyValue;
}
}
function getClientPort(serverPort) {
var keyName = "clientPort['" + serverPort +"']";
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('1494')
+ ">\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>
