Part I Secure Remote Access Server Components

• Chapter 1, Introduction to Portal Server Secure Remote Access Server

• Chapter 2, Working With Gateway

• Chapter 3, Working With Proxylet

• Chapter 4, Working with Rewriter

• Chapter 5, Working with NetFile

• Chapter 6, Working with Netlet

Chapter 1 Introduction to Portal Server Secure Remote Access Server

This chapter describes the Sun Java^TM System Portal Server Secure Remote Access and the relationship between the Sun Java System Portal Server and Sun Java System Portal Server Secure Remote Access components.

This chapter covers the following topics:

• Introduction to Secure Remote Access

• Secure Remote Access Services

• Supported Applications

Introduction to Secure Remote Access

Secure Remote Access enables remote users to securely access their organization’s network and its services over the Internet. Additionally, it gives your organization a secure internet portal, providing access to content, applications, and data to any targeted audience such as employees, business partners, or the general public.

Secure Remote Access offers browser-based secure remote access to portal content and services from any remote device. Secure Remote Access is a secure access solution that is accessible to users from any device with a Java™ technology-enabled browser, eliminating the need for client software. Integration with Portal Server ensures that users receive secure encrypted access to the content and services that they have permission to access.

Secure Remote Access software is targeted toward enterprises deploying highly secure remote access portals. These portals emphasize security, protection, and privacy of intranet resources. The architecture of Secure Remote Access is well suited to these types of portals. Secure Remote Access software enables users to securely access intranet resources through the Internet without exposing these resources to the Internet.

Portal Server can function in two modes, Open Mode and Secure Mode as described in the following sections.

Open Mode

In open mode, Portal Server is installed without Secure Remote Access. Although HTTPS communication is possible in this mode, secure remote access is not possible. Users therefore cannot access secure remote file systems and applications.

The main difference between an open portal and a secure portal is that the services presented by the open portal typically reside within the demilitarized zone (DMZ) and not within the secured intranet. A DMZ is a small protected network between the public Internet and a private intranet, usually demarcated with a firewall on both ends.

If the portal does not contain sensitive information both of either deploying public information and allowing access to free applications, then responses to access requests by a large number of users is faster than using secure mode.

In Open Mode, Portal Server is installed on a single server behind the firewall. Multiple clients access Portal Server across the Internet through the single firewall.

Figure 1–1 Portal Server in Open Mode with Secure Remote Access

Secure Mode

Secure mode provides users with secure remote access to required intranet file systems and applications.

The Gateway resides in the demilitarized zone (DMZ). The Gateway provides a single secure access point to all intranet URLs and applications, thus reducing the number of ports to be opened in the firewall. All other Portal Server services such as Session, Authentication, and the standard Portal Desktop reside behind the DMZ in the secured intranet. Communication from the client browser to the Gateway is encrypted using HTTP over Secure Sockets Layer (SSL). Communication from the Gateway to the server and intranet resources can be either HTTP or HTTPS.

In Secure Mode, SSL is used to encrypt the connection between the client and the Gateway over the Internet. SSL can also be used to encrypt the connection between the Gateway and the server. The presence of the Gateway between the intranet and the Internet extends the secure path between the client and the Portal Server.

Figure 1–2 Portal Server in Secure Mode with Secure Remote Access

Additional servers and gateways can be added for site expansion. Secure Remote Access software can be configured in various ways based on the business requirement. For more information on how to accommodate your business requirements, see Sun Java System Portal Server 7.2 Deployment Planning Guide.

Secure Remote Access Services

Secure Remote Access software has five major components:

• Gateway

  The SRA Gateway provides the interface and security barrier between remote user sessions originating from the Internet and a corporate intranet. The gateway presents content securely from internal web servers and application servers through a single interface to a remote user.

  Web servers use web-based resources such as HTML, JavaScript and XML to communicate between the client and the Gateway. Rewriter is the Gateway component used to make web content available.

  Application servers use binary protocol such as telnet and FTP to communicate between the client and Gateway. Netlet, which resides on the Gateway, is used for this purpose. See Chapter 2, Working With Gateway for more detail.

• Rewriter

  Rewriter enables end users to browse the intranet and makes links and other URL references on those pages operate correctly. Rewriter prepends the Gateway URL in the location field of the web browser, thereby redirecting content requests through the Gateway. See Chapter 4, Working with Rewriter for details.

• Netfile

  NetFile is a file manager application that enables remote access and operation of file systems and directories. NetFile includes a Java based user interface. See Chapter 5, Working with NetFile for details.

• Netlet

  Netlet facilitates the running of popular or company-specific applications on remote desktops in a secure manner. After you implement Netlet at your site, users can securely run common TCP/IP services, such as Telnet and SMTP, and HTTP-based applications such as pcANYWHERE or Lotus Notes. See Chapter 6, Working with Netlet for details.

• Proxylet

  Proxylet is a dynamic proxy server that runs on a client machine. Proxylet redirects a URL to the Gateway, by reading and modifying the proxy settings of the browser on the client machine so that they point to the local proxy server or Proxylet.

Configuring the Secure Remote Access Attributes

You configure Secure Remote Access attributes on the Portal Server administration console using the following services:

• Access Control

  This service enables you to allow or restrict access to specific URLs and to manage the single sign-on feature. For more information, see Chapter 7, Configuring the Secure Remote Access Server Access Control.

• Gateway

  Profiles (Gateway Instances) This service enables you to configure all Gateway related attributes such as enabling components, cookie management, proxy management, security settings, performance tuning, rewriter mapping management. For more information, see Chapter 8, Configuring the Secure Remote Access Gateway.

• NetFile

  This service enables you to configure all NetFile related attributes such as common hosts, MIME types, and access to different types of hosts. For more information, see Chapter 14, Configuring NetFile.

• Netlet

  This service enables you to configure all Netlet related attributes such as Netlet rules, access to required rules, organizations and hosts, and the default algorithm. For more information, see Chapter 11, Configuring the Netlet.

• Rewriter

  This service enables you to download, upload and delete all rewriter rulesets.

• Proxylet

  This service enables you to configure Proxylet related attributes such as Proxylet Applet Bind IP address and port number. For more information, see Chapter 13, Configuring Proxylet.

The Gateway does not receive notifications for attribute changes that are made while Gateway is running. Restart the Gateway for updated profile attributes (belonging to the Gateway or any other service) to take effect. For more information, see Configuring Gateway Attributes Using the Command Line Options.

Setting Conflict Resolution

To Set the Conflict Resolution Level

1. To Login to the Management Console in Sun Java System Portal Server 7.2 Administration Guide

2. Select the Secure Remote Access tab and click the required service tab: Netlet, Netfile, or Proxylet.

3. Select the Organization or Role from the Select DN drop-down menu.

4. Select the required Conflict Resolution Level from the COS Priority drop-down box.

5. Click Save to complete.

Supported Applications

SRA supports the following applications:

• Sun Java System Calendar Server Release 5.1.1 and later

• Sun Java System Messenger Express 6 2005Q1 - Sun Java System Messaging Server 5.2 and later

• Sun Java System Communications Express 6 2005Q1

Before You Begin

To Enable SRA for a Portal

1. Switch SRA status by using the command PortalServer_base/psadmin switch-sra-status -u amadmin -f <passwordfile> on.

2. Provision the SRA status by using the command PortalServer_base/psadmin provision-sra -u amadmin -f <passwordfile> -p <portal-id> --gateway-profile <profile-name> --enable.

Chapter 2 Working With Gateway

This chapter describes Gateway related concepts. For information on managing the gateway, see Chapter 16, Managing the Gateway. For information about configuring the Gateway, see Chapter 8, Configuring the Secure Remote Access Gateway.

This chapter covers the following topics:

• Introduction to Gateway

• Understanding the platform.conf File

• Using Web Proxies

• Using Automatic Proxy Configuration

• Using a Netlet Proxy

• Using a Rewriter Proxy

• Using a Reverse Proxy with the Gateway

• Obtaining Client Information

• Using Authentication Chaining

• Using Wild Card Certificates

• Disabling Browser Caching

• Customizing the Gateway Service User Interface

Introduction to Gateway

The Gateway provides the interface and security barrier between remote user sessions originating from the Internet and your corporate intranet. The Gateway presents content securely from internal web servers and application servers through a single interface to a remote user.

For each Gateway instance you must complete the following tasks:

• Creating a Gateway Profile

• Creating Multiple Instances of a Gateway

• Chapter 8, Configuring the Secure Remote Access Gateway.

Other gateway related topics include the following:

• Restarting the Gateway

• Configuring the Gateway Watchdog

• Specifying a Virtual Host

• Specifying a Proxy to Contact Access Manager

Creating a Gateway Profile

A gateway profile contains all the information related to gateway configuration, such as the port on which the Gateway listens, SSL options, and proxy options. When you install a Gateway, if you choose the default values, a default gateway profile called "default" is created. A configuration file corresponding to the default profile exists at: /etc/opt/SUNWportal/platform.conf.default.

Where /etc/opt/SUNWportal is the default location for all the platform.conf.* files. For more information on the platform.conf file, see Understanding the platform.conf File.

When working with profiles, you can perform the following tasks:

• Create multiple profiles, define attributes for each profile, and assign these profiles to different Gateways as required.

• Assign a single profile to Gateway installations on different machines.

• Assign different profiles to instances of a single Gateway running on the same machine.

Do not assign the same profile to different instances of the Gateway running on the same machine. This setup causes a conflict because the port numbers are the same.

Do not specify the same port numbers in the different profiles created for the same Gateway. Running multiple instances of the same Gateway with the same port causes a conflict.

Creating Multiple Instances of a Gateway

To create multiple instances of a gateway, see Chapter 4, Installing and Configuring a Gateway With Portal Server, in Sun Java System Portal Server 7.2 Installation and Configuration Guide

Creating Multi-homed Gateway Instances

Multi-homed gateway instances are multiple gateways on one Portal Server. To create these instances, modify the platform.conf file as follows:

gatewaybindipaddress = 0.0.0.0

Creating Gateway Instances Using the Same LDAP

If you are creating multiple gateway instances that use the same LDAP, after creating the first Gateway on all subsequent Gateways:

In /etc/opt/SUNWam/config/, modify the following areas in AMConfig-instance-name.properties to be consistent with the first installed instance of the Gateway.

See To Create Gateway Instances Using the Same LDAP

Restarting the Gateway

Normally, you do not need to restart the Gateway. You need to restart only if any of the following events occur:

• You have created a new profile and need to assign the new profile to the Gateway.

• You have modified some attributes in the existing profile and need the changes to take effect.

• Gateway crashes due errors such as OutOfMemory error.

• Gateway stops responding and does not service any requests.

Configuring the Gateway Watchdog

You can configure the time interval at which the watchdog monitors the status of the Gateway. To start or to stop the watchdog, run the command;./psadmin sra-watchdog -u amadmin -f <password-file> -t <type> on|off. This time interval is set to 60 seconds by default. To change this value, edit the following line in the crontab utility:

0-59 * * * * gateway-install-root/SUNWportal/bin/
/var/opt/SUNWportal/.gw. 5 > /dev/null 2>&1

See the crontab man page to configure the crontab entries.

Specifying a Virtual Host

A virtual host is an additional host name that points to the same machine IP and a host name. For example, if a host name abc points to the host IP address 192.155.205.133, you can add another host name cde which points to the same IP address.

Specifying a Proxy to Contact Access Manager

You can specify a proxy host to be used by the Gateway to contact SRA Core (RemoteConfigServlet) that is deployed over the Portal Server. This proxy is used by the Gateway to reach the Portal Server and Access Manager. See, To Specify a Proxy.

Understanding the platform.conf File

The platform.conf file is located by default at: /etc/opt/SUNWportal.

The platform.conf file contains the details that the Gateway needs. This section provides a sample platform.conf file and describes all the entries.

The advantage of including all the machine-specific details in the configuration file is that a common profile can be shared by Gateways running on multiple machines.

The following is a sample of the platform.conf file.

Tue May 30 11:51:23 IST 2006
debug.com.sun.portal.rewriter.original.level=INFO
gateway.favicon=
gateway.bindipaddress=10.12.154.236
debug.com.sun.portal.sra.rproxy.toFromServer.handler.java.util.logging.FileHandler.pattern=
/var/opt/SUNWportal/logs/sra/default/Gateway.toFromServer.%u.%g.log
gateway.port=443
rewriterproxy.jvm.flags=-ms64m -mx128m
portal.server.instance=default
debug.com.sun.portal.handler.java.util.logging.FileHandler.filter=
gateway.jdk.dir=/usr/jdk/entsys-j2se
gateway.ignoreURIList=/MSOffice/cltreq.asp,/_vti_bin/owssvr.dll
debug.com.sun.portal.rewriter.rest.level=INFO
gateway.trust_all_server_certs=true
debug.com.sun.portal.handler.java.util.logging.FileHandler.append=true
gateway.cdm.cacheCleanupTime=300000
gateway.httpurl=
debug.com.sun.portal.handler.java.util.logging.FileHandler.count=1
gateway.jvm.classpath=
debug.com.sun.portal.setserverlogs=false
gateway.protocol=https
debug.com.sun.portal.sra.rproxy.toFromServer=java.util.logging.FileHandler
rewriterproxy.jvm.classpath=
gateway.enable.customurl=false
debug.com.sun.portal.sra.rproxy.toFromBrowser=java.util.logging.FileHandler
debug.com.sun.portal.handler.java.util.logging.FileHandler.formatter=com.sun.portal.
log.common.PortalLogFormatter
debug.com.sun.portal.sra.rproxy.toFromBrowser.handler.java.util.logging.FileHandler.pattern=
/var/opt/SUNWportal/logs/sra/default/Gateway.toFromBrowser.%u.%g.log
debug.com.sun.portal.level=INFO
debug.com.sun.portal.rewriter.unaffected.separatefile=true
gateway.enable.accelerator=false
debug.com.sun.portal.rewriter.original.separatefile=true
gateway.virtualhost=nicp236.india.sun.com 10.12.154.236
debug.com.sun.portal.stacktrace=true 
gateway.host=nicp236.india.sun.com
debug.com.sun.portal.handler.java.util.logging.FileHandler.pattern=
/var/opt/SUNWportal/logs/sra/default/%logger.%sraComponentType.%u.%g.log
gateway.certdir=/etc/opt/SUNWportal/cert/default
gateway.sockretries=3
gateway.allow.client.caching=true
debug.com.sun.portal.rewriter.unaffected.level=INFO
debug.com.sun.portal.rewriter.uriinfo.separatefile=true
log.config.check.period=2000
debug.com.sun.portal.rewriter.rewritten.level=INFO
gateway.userProfile.cacheSize=1024
debug.com.sun.portal.rewriter.rulesetinfo.level=INFO
netletproxy.jvm.classpath=
gateway.userProfile.cacheSleepTime=60000
debug.com.sun.portal.rewriter.uriinfo.level=INFO
debug.com.sun.portal.rewriter.rest.separatefile=true
gateway.notification.url=notification
debug.com.sun.portal.rewriter.rulesetinfo.separatefile=true
gateway.logdelimiter=&&
gateway.ignoreServerList=false
gateway.jvm.flags=-ms64m -mx128m
debug.com.sun.portal.handler.java.util.logging.FileHandler.limit=5000000
gateway.dsame.agent=http\://sunone216.india.sun.com\:8080/portal/RemoteConfigServlet
gateway.httpsurl=
gateway.retries=6
gateway.userProfile.cacheCleanupTime=300000
gateway.logging.password=X03MO1qnZdYdgyfeuILPmQ\=\= UX9x0jIua3hx1YOVRG/TLg\=\=
netletproxy.jvm.flags=-ms64m -mx128m
debug.com.sun.portal.rewriter.rewritten.separatefile=true
gateway.user=noaccess
gateway.external.ip=10.12.154.236
debug.com.sun.portal.handler=java.util.logging.FileHandler
gateway.cdm.cacheSleepTime=60000
rewriterproxy.accept.from.gateways=
rewriterproxy.checkacl=false

The following table lists and describes all the fields in the platform.conf file.

Using Web Proxies

You can configure the Gateway to contact HTTP resources using third party web proxies. Web proxies reside between the client and the Internet.

Web Proxy Configuration

Different proxies may be used for different domains and subdomains. These entries tell the Gateway which proxy to use to contact specific subdomains in specific domains. The proxy configuration specified in the Gateway works as follows:

• Creates a list of domains and subdomains along with the required proxies in the Proxies for Domains and Subdomains field in the Gateway service.

• With the Use Proxy option enabled:

  • The proxies specified in the Proxies for Domains and Subdomains field are used for the specified hosts.

  • To enable direct connections for certain URLs within the domains and subdomains specified in the Proxies for Domains and Subdomains list, specify these URLs in the Do Not Use Web Proxy URLS field.

  With the Use Proxy option disabled:

  • To ensure that proxies are used for certain URLs within the domains and subdomains specified in the Proxies for Domains and Subdomains field, specify these URLs in the Use Webproxy URLs list.

    Although the Use Proxy option is disabled, a proxy is used to connect to the URLs listed under Use Webproxy URLs. The proxies for these URLs are obtained from the Proxies for Domains and Subdomains list.

    The following illustration shows how the web proxy information is resolved based on the proxy configuration in the Gateway service.

    

    In Web Proxy Configuration, if Use Proxy is enabled, and the requested URL is listed in the Do Not Use Webproxy URLs list, the Gateway connects to the destination host directly.

    If Use Proxy is enabled, and the requested URL is not listed in the Do Not Use Webproxy URLs list, the Gateway connects to the destination host through the specified proxy. The proxy, if specified, is looked up in the Proxies for Domains and Subdomains list.

    If Use Proxy is disabled, and the requested URL is listed in the Use Webproxy URLs list, the Gateway connects to the destination host using the proxy information in the Proxies for Domains and Subdomains list.

    If Use Proxy is disabled, and the requested URL is not listed in the Use Webproxy URLs list, the Gateway connects to the destination host directly.

    If none of the above conditions are met, and a direct connection is not possible, the Gateway displays an error saying that connection is not possible.

If you are accessing the URL through the Bookmark channel of the standard Portal Desktop, and none of the above conditions are met, the Gateway sends a redirect to the browser. The browser accesses the URL using its own proxy settings.

Syntax

domainname [web_proxy1:port1]|subdomain1 [web_proxy2:port2]|

Example

sesta.com wp1:8080|red wp2:8080|yellow|* wp3:8080

* is a wild card that matches everything

where,

sesta.com is the domain name and wp1 is the proxy to contact on port 8080.

red is a subdomain and wp2 is the proxy to contact on port 8080.

yellow is a subdomain. Since no proxy is specified, the proxy specified for the domain is used, that is, wp1 on port 8080.

* indicates that for all other subdomains wp3 needs to be used on port 8080.

Port 8080 is used by default if you do not specify a port.

Processing the Web Proxy Information

When a client tries to access a particular URL, the host name in the URL is matched with the entries in the Proxies for Domains and Subdomains list. The entry that matches the longest suffix of the requested host name is considered. For example, suppose that the requested host name is host1.sesta.com. The following searches occur in order until a match is found.

• The Proxies for Domains and Subdomains is scanned for host1.sesta.com. If a matching entry is found, the proxy specified against this entry is used to connect to this host.

• Else, the list is scanned for *.sesta.com. If an entry is found, the corresponding proxy is used.

• Else, the list is searched for sesta.com. If an entry is found, the corresponding proxy is used.

• Else, the list is searched for *.com. If an entry is found, the corresponding proxy is used.

• Else the list is searched for com. If an entry is found, the corresponding proxy is used.

• Else the list is searched for *. If an entry is found, the corresponding proxy is used.

• If no matching centers are found, a direct connection is attempted.

Consider the following entries in the Proxies for Domains and Subdomains list:

com p1| host1 p2 | host2 | * p3
sesta.com p4 | host5 p5 | * p6
florizon.com | host6
abc.sesta.com p8 | host7 p7 | host8 p8 | * p9
host6.florizon.com p10
host9.sesta.com p11
siroe.com | host12 p12 | host13 p13 | host14 | * p14
siroe.com | host15 p15 | host16 | * p16
* p17

The Gateway internally maps these entries into a table as shown in the following table.

Instead of separating the proxy entries in the Proxies for Domains and Subdomains list with the | symbol, you can place individual entries on separate lines in the list. For example, instead of an entry such as:

sesta.com p1 | red p2 | * p3

you can specify this information as:

sesta.com p1
red.sesta.com p2
*.sesta.com p3

This list format makes it easier to track repeated entries or any other ambiguities.

Rewriting Based on the Proxies for Domains and Subdomains List

The entries in the Proxies for Domains and Subdomains list are also used by Rewriter. Rewriter rewrites all URLs whose domains match the domains listed in the Proxies for Domains and Subdomains list.

The * entry in the Proxies for Domains and Subdomains list is not considered for rewriting. For example, entry 24 is not considered.

For information on Rewriter, see Chapter 4, Working with Rewriter .

Default Domain and Subdomain

When the destination host in the URL is not a fully qualified host name, the default domain and subdomain are used to arrive at the fully qualified name.

Assume that the entry in the Default Domains field of the administration console is:

red.sesta.com

You need to have the corresponding entry in the Proxies for Domains and Subdomains list.

In the example above, sesta.com is the default domain and the default subdomain is red.

If the requested URL is host1, this entry is resolved to host1.red.sesta.com using the default domain and subdomain. The Proxies for Domains and Subdomains list is then checked for host1.red.sesta.com.

Using Automatic Proxy Configuration

To ignore the information in the Proxies for Domains and Subdomains list, enable the Automatic Proxy Configuration feature.

When using a Proxy Auto Configuration (PAC) file:

• Portal Server, Gateway, Netlet, and Proxylet use Rhino software to parse the PAC file. You can install the SUNWrhino package from the Java Enterprise System Accessory CD.

  This package contains the js.jar file which must be present in the /usr/share/lib directory. Add this directory to the webserver/appserver class path on the Gateway and Portal Server machine, otherwise the Portal Server, Gateway, Netlet, and Proxylet cannot parse the PAC file.

• The js.jar must be present in the $JRE_HOME/lib/ext directory on the Gateway machine, otherwise the Gateway cannot parse the PAC file.

• The Gateway fetches the PAC file at bootup from the location specified in the gateway profile Automatic Proxy Configuration File location field.

• The Gateway uses the URLConnection API to reach this location. If the proxy needs to be configured to reach the Gateway, the proxy needs to be configured in the following way:

  1. From the command-line, edit the following file:

     /etc/opt/SUNWportal/platform.conf.gateway-profile-name

  2. Add the following entries:

     http.proxyHost=web-proxy-hostname

     http.proxyPort=web-proxy-port

     http.proxySet=true

  3. Restart the Gateway to use the specified proxy:

     ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

• If PAC file initialization fails, then the Gateway uses the information in the Proxies for Domains and Subdomains list.

• If "" (empty string) or "null" is returned from the PAC file, then the Gateway assumes that the host does not belong to the intranet. This is similar to the host not being in the Proxies for Domains and Subdomains list.

  If you want the Gateway to use a direct connection to the host, return "DIRECT". See Example with Either DIRECT or NULL Return.

• Gateway only uses the first proxy returned when multiple proxies are specified. It does not try to failover or loadbalance among the various proxies specified for a host.

• Gateway ignores SOCKS proxies and attempts a direct connection and assumes that the host is part of the intranet.

• To specify a proxy to be used to reach any host not part of the intranet, use the proxy type STARPROXY. This proxy type is an extension of the PAC file format and is similar to the entry * proxyHost:port in Proxies for Domains and Subdomains section of the gateway profile. See Example with STARPROXY Return

Sample PAC File Usage

The following examples show the URLs listed in the Proxies for Domains and Subdomains list and the corresponding PAC file.

Example with Either DIRECT or NULL Return

If these proxies are used for domains and subdomains:

*intranet1.com proxy.intranet.com:8080

intranet2.com proxy.intranet1.com:8080

the corresponding PAC file is:

// Start of the PAC File
function FindProxyForURL(url, host) {
         if (dnsDomainIs(host, ".intranet1.com")) {
             return "DIRECT";
         }
          if (dnsDomainIs(host, ".intranet2.com")) {
              return "PROXY proxy.intranet1.com:8080";
          }
          return "NULL";
}
//End of the PAC File

Example with STARPROXY Return

If these proxies are used for domains and subdomains:

intranet1.com

intranet2.com.proxy.intranet1.com:8080

internetproxy.intranet1.com:80

the corresponding PAC file is:

// Start of the PAC File
function FindProxyForURL(url, host) {
          if (dnsDomainIs(host, ".intranet1.com")) {
              return "DIRECT";
          }
          if (dnsDomainIs(host, ".intranet2.com")) {
              return "PROXY proxy.intranet1.com:8080;" +
                  "PROXY proxy1.intranet1.com:8080";
          }
          return "STARPROXY internetproxy.intranet1.com:80";
}
//End of the PAC File

In this case, if the request is for a host in .intranet2.com domain, the Gateway contacts proxy.intranet1.com:8080. If proxy.intranet1.com:8080 is down, the request fails. The Gateway does not failover and contacts proxy1.intranet1.com:8080.

Specifying PAC File Location

The format for specifying the location of the PAC file depends upon it’s location as follows:

• If the PAC file resides on a Web server, the PAC URL is:

  http://hostname/pacfile_name.pac

• If the pacfile is a local file (for example, c:\\pacfile\\sample.pac), for Java 1.4.1_x, enter the PAC URL as:

  file://c:/pacfile/sample.pac

• If the PAC file is a local file (for example, c:\\pacfile\\sample.pac), for Java 1.4.2_x, enter the PAC URL as:

  file:///c:/pacfile/sample.pac

Adding Services in Separate Sessions

When you add Portal Server services in separate sessions:

• List Portal Servers under Gateway > Core in the Portal Server administration console.

• List Portal Server URLs in the Non-authenticated URLs under Gateway > Security.

Using a Netlet Proxy

Netlet packets are decrypted at the Gateway and sent to the destination servers. However, the Gateway needs to access all Netlet destination hosts through the firewall between the demilitarized zone (DMZ) and the intranet. This setup requires opening a large number of ports in the firewall. The Netlet proxy can be used to minimize the number of open ports in the firewall.

The Netlet proxy enhances the security between the Gateway and the intranet by extending the secure tunnel from the client, through the Gateway to the Netlet proxy that resides in the intranet. With the proxy, Netlet packets are decrypted by the proxy and then sent to the destination.

The advantages of using Netlet proxy are:

• Adds an additional layer of security.

• Minimizes the use of extra IP addresses and ports from the Gateway through an internal firewall in a significantly sized deployment environment.

• Restricts the number of open ports between the Gateway and the Portal Server to 1. This port number can be configured during installation.

• Extends the secure channel between the client and the Gateway, up to the Portal Server as shown in the "With a Netlet Proxy Configured" section of Using a Netlet Proxy. The Netlet proxy offers improved security benefits through data encryption but may increase the use of system resources. See the Sun Java System Installation Guide for information on installing the Netlet proxy.

You can perform the following tasks:

• Install the Netlet proxy on the Portal Server node or on a separate node.

• Install multiple Netlet proxies and configure them for a single Gateway using the administration console. This is useful in load balancing.

• Configure multiple instances of the Netlet proxy on a single machine.

• Point multiple instances of the Gateway to a single installation of the Netlet proxy.

• Tunnel Netlet through a web proxy.

Shows three sample implementations of the Gateway and the Portal Server with and without a Netlet proxy installed. The components include a client, two firewalls, the Gateway that resides between the two firewalls, Portal Server, and Netlet destination servers.

The first scenario shows the Gateway and Portal Server without a Netlet proxy installed. The data encryption extends only from the client to the Gateway. A port is opened in the second firewall for each Netlet connection request.

The second scenario shows the Gateway and Portal Server with a Netlet proxy installed on Portal Server. The data encryption extends from the client all the way to the Portal Server. Since all Netlet connections are routed through a Netlet proxy, only one port needs to be opened in the second firewall for Netlet requests.

The third scenario shows the Gateway and the Portal Server with a Netlet proxy installed on a separate node. Installing a Netlet proxy on a separate node reduces the load on the Portal Server node. Again, only two ports need to be opened in the second firewall. One port services requests to the Portal Server, and the other port routes Netlet requests to the Netlet proxy server.

Figure 2–1 Implementation of Netlet Proxy

Enabling a Netlet Proxy

You enable a Netlet proxy through the Gateway service using the Portal Server administration console.

Restarting a Netlet Proxy

You can configure a Netlet proxy to restart whenever the proxy is killed accidentally. You can schedule a watchdog process to monitor a Netlet proxy and restart it if it goes down.

You can also restart a Netlet proxy manually. See To Restart a Netlet Proxy for steps.

To Configure a Netlet Proxy Watchdog

You can configure the time interval at which the watchdog monitors the status of a Netlet proxy. This time interval is set to 60 seconds by default. To change this interval, add the following line to the crontab file:

0-59 * * * * netlet-install-dir/bin/checkgw /var/opt/SUNWportal/.gw 5 > /dev/null 2>&1

To start or to stop the watchdog, run the command;./psadmin sra-watchdog -u amadmin -f <password-file> -t <type> on|off.

Using a Rewriter Proxy

The Rewriter proxy is installed in the intranet. Instead of trying to retrieve the contents directly, the Gateway forwards all requests to the Rewriter proxy which fetches and returns the contents to the Gateway.

The advantages of using a Rewriter proxy are:

• If a firewall exists between the Gateway and server, the firewall needs to open only two ports - one between the Gateway and Rewriter proxy, and another between the Gateway and the Portal Server.

• HTTP traffic is secure between the Gateway and the intranet even if the destination server only supports the HTTP protocol and not HTTPS.

If you do not specify a Rewriter proxy, the Gateway component makes a direct connection to intranet computers when a user tries to access one.

If you are using the Rewriter proxy as a load balancer, be sure that the platform.conf.instance_name for Rewriter points to the load balancer URL. Also specify the load balancer host in the Portal Servers list.

If you have multiple instances of Rewriter proxies for each Gateway instance, which are not necessarily on the portal node, provide the details for each Rewriter proxy in the form of host-name:port in the platform.conf file, rather than a single port entry for the Rewrite proxy.

Creating Instances of a Rewriter Proxy

Use the rwpmultiinstance script to create a new instance of a Rewriter proxy on the Portal Server node. Run this script after the gateway profile has been created.

See To Create a Rewriter Proxy Instance.

Enabling a Rewriter Proxy

Enable a Rewriter proxy through the Gateway service under SRA Configuration in the Access Manager administration console.

Restarting a Rewriter Proxy

You can configure to restart Rewriter proxy whenever the proxy is killed accidentally. You can schedule a watchdog process to monitor and restart it if this happens.

You can also restart a Rewriter proxy manually.

See To Restart a Rewriter Proxy.

Configuring a Rewriter Proxy Watchdog

You can configure the time interval at which the watchdog monitors the status of the Rewriter proxy. This time interval is set to 60 seconds by default. To to change the time interval, add the following line in the crontab file:

0-59 * * * * rewriter-proxy-install-root/bin/checkgw /var/opt/SUNWportal/.gw 5 > /dev/null 2>&1

To start or to stop the watchdog, run the command;./psadmin sra-watchdog -u amadmin -f <password-file> -t <type> on|off.

Using a Reverse Proxy with the Gateway

A proxy server serves Internet content to the intranet, while a reverse proxy serves intranet content to the Internet. You can configure deployments of reverse proxies to achieve load balancing and caching.

If the deployment has a third-party reverse proxy in front of the Gateway, the response has to be rewritten with the reverse proxy's URL instead of the Gateway's URL. For this, the following configurations are needed.

See To Enable a Reverse Proxy.

Obtaining Client Information

When the Gateway forwards a client request to any internal server, it adds HTTP headers to the HTTP request. You can use these headers to obtain additional client information and detect the presence of the Gateway.

To view the HTTP request headers, set the entry in the platform.conf file to gateway.error=message. And, then use the request.getHeader() from the servlet API. The following table lists the information in the HTTP headers.

Using Authentication Chaining

Authentication chaining provides a higher level of security than the regular mechanism of authentication. You can enable users to be authenticated against more than one authentication mechanism.

The procedure described in this is only for enabling authentication chaining along with a Personal Digital Certificate (PDC) authentication at the Gateway. For information on authentication chaining without PDC authentication at the Gateway, see the Access Manager Administration Guide.

For example, if you chain the PDC and Radius authentication modules, the user will have to authenticate against all three modules to access the standard Portal Desktop.

See To Add Authentication Modules to an Existing PDC Instance for steps.

When enabled, PDC is always the first authentication module to be presented to the user.

Using Wild Card Certificates

A wild card certificate accepts a single certificate with a wild card character in the fully-qualified DNS name of the host.

With the certificate multiple hosts within the same domain are secured. For example, a certificate for *.domain.com can be used for abc.domain.com, and abc1.domain.com. This certificate is valid for any host in the domain.com domain.

Disabling Browser Caching

Because the Gateway component provides secure access to back end corporate data from any location using just a web browser, the information should not be cached locally by the client.

You can disable caching of pages redirected through the Gateway by modifying the attribute in the platform.conf file of the specific Gateway.

Disabling this option can have an impact on the Gateway performance. Every time the standard Portal Desktop is refreshed, the Gateway has to retrieve everything referenced by the page, such as images that might have been previously cached by the browser. However, enabling this feature, means that remotely accessing secure content will not leave a cached footprint on the client site. This factor could outweigh performance implications if the corporate network is being accessed from an Internet cafe or similar remote location that is not under corporate IT control.

See To Disable Browser Caching.

Customizing the Gateway Service User Interface

This section discusses the various Gateway property files that can be edited.

Modifying the srapGateway.properties File

You can edit this file for the following purposes:

• Customize the error messages that might appear when the Gateway is running.

  • HTML-CharSets=ISO-8859-1 specifies the character set that was used to create this file.

  • The number in braces (for example, {0}) indicates that the value displayed at run time. You can change the label associated with this number, or rearrange the labels as required. Ensure that the label corresponds to the message that to be displayed since the number and the message are associated.

  Customize the log information.

  By default the srapGateway.properties file is located under the portal-server-install-root/SUNWportal/locale directory. All messages that appear on the Gateway machine are located in this file, irrespective of the language of the messages.

  To change the language of the messages that appear on the client standard Portal Desktop, copy this file into the respective locale directory, for example portal-server-install-root/SUNWportal/locale_en_US.

Modifying the srapgwadminmsg.properties File

You can edit this file for the following reasons:

• Customize the labels that appear on buttons for the Gateway service on the administration console.

• Customize the status messages and error messages that appear when you are configuring the Gateway.

Sharing LDAP Directories

When two instances of Portal Server and Access Manager servers share the same LDAP directories, it shares the same LDAP directories for all subsequent instances of Portal Servers, Access Managers, and Gateways. See To Share LDAP Directories.

Chapter 3 Working With Proxylet

This chapter describes Proxylet which enables users to access intranet web pages through the Gateway without parsing the web pages.

Working with Proxylet

Overview of Proxylet

Proxylet is a Java applet that sets itself as a proxy server on the client machine. Proxylet reads and modifies the proxy settings in the Proxy Auto Config (PAC) file on the client machine so that the proxy settings point to the local proxy server (Proxylet).

Proxylet inherits the transport mode from the Gateway. If the Gateway is configured to run on SSL, Proxylet establishes a secure channel between the client machine and the Gateway or destination server. For encryption, Proxylet uses the JSSE API if the client JVM is 1.4 or higher or if the required jar files reside on the client machine. Otherwise it uses the KSSL API. Decryption occurs on the client machine.

The domain and subdomain for URLs that are to be directed to the Gateway are specified in the gateway profile. If a URL is not part of a domain that the gateway handles, the request is directed to the Internet. If a particular URL domain is listed in the gateway profile, then Proxylet resets the client proxy settings to point to the Gateway.

Proxylet supports client-side authentication if a Personal Digital Certificate (PDC) is enabled at the Gateway. To check whether PDC is enabled, see Obtaining Client Information.

Proxylet is enabled from the Portal Server administration console where the client IP address or proxy host name and port are specified. If Proxylet is enabled, it checks the client machine for the following information:

• Appropriate browser permissions

• Whether the browser is IE 6.0 sp2, IE 7, and Firefox 2.0

• Whether the machine or device can run a server application

If all the requirements are satisfied, an applet is downloaded and launched on the client machine. When the client does not have JRE 1.4.2 or later installed, then JRE is automatically downloaded with Proxylet if you have both internet connectivity and administration privileges.

When Proxylet is used, the proxy settings are retrieved from the Proxy Auto Configuration (PAC) file or from the proxy configuration list.

Make sure users know that when using the Proxylet applets, browser pop-up blockers must be disabled.

HTTPS Support

Proxylet supports HTTPS with the following results:

• Decryption is done at the client server.

• Destination servers can accessed when running in SSL mode.

• Client certificates are directly presented to the destination server.

• Basic authentication single-sign (SSO) is not supported at the gateway. (The Gateway can not insert SSO information in http headers.)

• URL-based access control is not supported, only host-based access control.

• External accelerators and external Reverse proxies in front of the gateway are not currently supported.

  ---

  Note –

  This support is not for Proxylet when Portal Server uses HTTPS.

  ---

Advantages of Using Proxylet

Unlike Rewriter, Proxylet requires little or no postinstallation changes. Integration with third party software such as Microsoft Exchange Server is easy. Also the performance of the Gateway increases because Proxylet does not touch web content. Because Proxylet does not modify content or change the data, users can download any type of content, such as tar and gzip files.

Configuring Proxylet

For information on enabling and configuring, Proxylet, see Chapter 13, Configuring Proxylet.

If the user does not have the appropriate Java Virtual Machine (JVM) to run Proxylet, the browser connects to the sun web site to download the Java Runtime Environment. If the user's browser settings do not contain the correct values or if the user is using direct proxy settings without access to the Internet, then Proxylet cannot be downloaded.

Chapter 4 Working with Rewriter

The Rewriter component of Secure Remote Access enables users to access intranet web pages through the Gateway by parsing the web pages.

This Chapter covers the following topics:

• Character Set Encoding

• Rewriter Usage Scenarios

• Writing Rulesets

• Public Interface (RuleSet DTD)

• Troubleshooting Using Debug Logs

• Public Interface (RuleSet DTD)

• Working Samples

• Case Study

• Mapping of 6.x RuleSet with 3.0

Introduction to Rewriter

The Rewriter component of Secure Remote Access enables end users to browse the intranet by modifying Uniform Resource Identifier (URI) references on web pages so that they point to the Gateway. A URI defines a way to encapsulate a name in any registered name space, and labels it with the name space. The most common kinds of URIs are Uniform Resource Locators (URLs). Rewriter supports only HTTP or HTTPS. This support is regardless of the capitalization of the protocol. Rewriter only supports backslashes when they are part of a relative URL.

Example 4–1 Rewriting URLs

http://abc.sesta.com\\index.html is rewritten.

These URLs are not rewritten: http:\\\\abc.sesta.com. http:/abc.com

Character Set Encoding

HTTP standards require that HTTP headers or HTML meta tags specify a character set for web pages. However, sometimes this information is not available. The character set must be known so that encoding for the data is set and the data is displayed as intended by the creator.

To detect the character sets, install the SUNWjchdt package from the Java Enterprise System Accessory CD. If this product is installed, Rewriter will detect it and use it if necessary.

Using this product can affect performance, so you should install it only when required. See the jcharset_readme.txt for details on installation, configuration and usage.

Rewriter Usage Scenarios

When a user tries to access intranet web pages through the Gateway, web pages are made available by using Rewriter. Rewriter is used by the URLScraper and the Gataway.

URLScraper

The URL Scraper provider gets content from configured URIs. Before sending these URIs to the browser, it expands all relative URIs to absolute URIs.

For example, if a user is trying to access a site as:

<a href="../mypage.html">

Rewriter translates this to:

<a href="http://yahoo.com/mypage.html">

where http://yahoo.com/test/ is the base URL of the page.

See the Sun Java SystemPortal Server Administration Guide for details about the URLScraper provider.

Gateway

The Gateway obtains content from internet portals. Before sending the content to the browser, it prefixes the Gateway URI to the existing URI so that subsequent URI requests from the browser can reach the Gateway.

For example, a user who is trying to access an HTML page on an internet machine as:

<a href="http://mymachine.intranet.com/mypage.html>"

Rewriter prefixes this URL with a reference to the Gateway as follows:

<a href="https://gateway.company.com/http://mymachine.intranet.com/ mypage.html>"

When the user clicks a link associated with this anchor, the browser contacts the Gateway. The Gateway fetches the content of mypage.html from mymachine.intranet.com.

The Gateway uses several rules to determine the elements of a fetched web page that will be rewritten.

Writing Rulesets

For more information about defining a ruleset, see the Portal Server Administration Guide. After creating a new ruleset, you need to define the required rules.

This section covers the following topics:

• Public Interface (RuleSet DTD)

• Sample XML DTD

• Procedure to Write Rules

• Ruleset Guidelines

• Defining the RuleSet Root Element

• Using the Recursive Feature

• Rules for HTML Content

• Rules for JavaScript Content

• Rules for XML Content

• Rules for Cascading Style Sheets

• Rules for WML

Public Interface (RuleSet DTD)

RuleSet DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!--
The following constraints are not represented in DTD, but taken care of programmatically
    1. In a Rule, All Mandatory attributes cannot be "*".
    2. Only one instance of the below elements is allowed, but in any order.
    1)HTMLRules
    2)JSRules
    3)XMLRules
    3. ID should always be in lower case.
-->
<!ENTITY % eURL ’URL’>
<!ENTITY % eEXPRESSION ’EXPRESSION’>
<!ENTITY % eDHTML ’DHTML’>
<!ENTITY % eDJS ’DJS’>
<!ENTITY % eSYSTEM ’SYSTEM’>

<!ENTITY % ruleSetElements ’(HTMLRules | JSRules | XMLRules)?’>
<!ENTITY % htmlElements ’(Form | Applet | Attribute)*’>
<!ENTITY % jsElements ’(Variable | Function)*’>
<!ENTITY % xmlElements ’(Attribute | TagText)*’>

<!ELEMENT RuleSet (%ruleSetElements;,%ruleSetElements;,%ruleSetElements;)>
<!ATTLIST RuleSet
    id ID #REQUIRED
    extends CDATA "none"
>

<!-- Rules for identifying rules in HTML content -->
<!ELEMENT HTMLRules (%htmlElements;)>
<!ELEMENT Form EMPTY>
<!ATTLIST Form
    name CDATA #REQUIRED
    field CDATA #REQUIRED
    valuePatterns CDATA ""
    source CDATA "*"
>

<!ELEMENT Applet EMPTY>
<!ATTLIST Applet
    code CDATA #REQUIRED
    param CDATA "*"
    valuePatterns CDATA ""
    source CDATA "*"
>

<!-- Rules for identifying rules in JS content -->
<!ELEMENT JSRules (%jsElements;)>
<!ELEMENT Variable EMPTY>
<!ATTLIST Variable
    name CDATA #REQUIRED
    type (%eURL; | %eEXPRESSION; | %eDHTML; | %eDJS; | %eSYSTEM;) "EXPRESSION"
    source CDATA "*"
>

<!ELEMENT Function EMPTY>
<!ATTLIST Function
    name CDATA #REQUIRED
    paramPatterns CDATA #REQUIRED
    type (%eURL; | %eEXPRESSION; | %eDHTML; | %eDJS;) "EXPRESSION"
    source CDATA "*"
>

<!-- Rules for identifying rules in XML content -->
<!ELEMENT XMLRules (%xmlElements;)>
<!ELEMENT TagText EMPTY>
<!ATTLIST TagText
    tag CDATA #REQUIRED
    attributePatterns CDATA ""
    source CDATA "*"
>

<!ELEMENT Attribute EMPTY>
<!ATTLIST Attribute
    name CDATA #REQUIRED
    tag CDATA "*"
    valuePatterns CDATA ""
    type (%eURL; | %eDHTML; | %eDJS; ) "URL"
    source CDATA "*"
>

You can use * as a part of rule value except that mandatory attribute values cannot be just *. Such rules are ignored, but the message is logged in the RuleSetInfo log file. For information on this log file, see Debug File Names.

Sample XML DTD

This section contains a sample rule set. The “Case Study,” on page 140 is used to illustrate how these rules are interpreted by Rewriter.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
Rules for integrating a mail client with the gateway.
-->
<!DOCTYPE RuleSet SYSTEM "jar://rewriter.jar/resources/RuleSet.dtd">
<RuleSet type="GROUPED" id="owa">
<HTMLRules>
<Attribute name="action" />
<Attribute name="background" />
<Attribute name="codebase" />
<Attribute name="href" />
<Attribute name="src" />
<Attribute name="lowsrc" />
<Attribute name="imagePath" />
<Attribute name="viewClass" />
<Attribute name="emptyURL" />
<Attribute name="draftsURL" />
<Attribute name="folderURL" />
<Attribute name="prevMonthImage" />
<Attribute name="nextMonthImage" />
<Attribute name="style" />
<Attribute name="content" tag="meta" />
</HTMLRules>
<JSRules>
<!-- Rules for Rewriting JavaScript variables in URLs -->
<Variable name="URL"> _fr.location </Variable>
<Variable name="URL"> g_szUserBase </Variable>
<Variable name="URL"> g_szPublicFolderUrl </Variable>
<Variable name="URL"> g_szExWebDir </Variable>
<Variable name="URL"> g_szViewClassURL </Variable>
<Variable name="URL"> g_szVirtualRoot </Variable>
<Variable name="URL"> g_szBaseURL </Variable>
<Variable name="URL"> g_szURL </Variable>
<Function name="EXPRESSION" name="NavigateTo" paramPatterns="y"/>
</JSRules>
<XMLRules>
<Attribute name="xmlns"/>
<Attribute name="href" tag="a"/>
<TagText tag="baseroot" />
<TagText tag="prop2" />
<TagText tag="prop1" />
<TagText tag="img" />
<TagText tag="xsl:attribute"
attributePatterns="name=src" />
</XMLRules>
</RuleSet>

Procedure to Write Rules

The general procedure to write rules is:

• Identify the directories that contain the HTML pages whose content needs to be rewritten.

• In these directories, identify the pages that need to be rewritten.

• Identify the URLs that need to be rewritten on each page. An easy way identify most of the URLs is to search for "http" and "/".

• Identify the content type of the URL: HTML, JavaScript or XML.

• Write the rule required to rewrite each of these URLs by editing the required ruleset in the Rewriter service under Portal Server Configuration in the Access Manager administration console.

• Combine all the rules into a ruleset for that domain.

Ruleset Guidelines

When creating a ruleset, keep the following in mind:

• The order of precedence for specific hosts is based on the longest URI match. For example for the following rulesets

  mail1.central.abc.com|iplanet_mail_ruleset
  *.sfbay.abc.com|sfbay_ruleset
  *.abc.com|generic_ruleset

  sfbay_ruleset is used as it has the longest match.

• The rules in the ruleset are applied in order to each statement in the page until a rule matches a particular statement.

  While writing the rules, keep in mind the order of the rules. Rules are applied to the statements in a page, in the order in which they occur in the ruleset. If you have specific rules, and general rules that contain a "*", define the specific rules first, then the general rules. Otherwise, the general rule is applied to all statements, even before the specific rule is encountered.

• All rules need to be enclosed within the <RuleSet> </RuleSet> tags.

• Include all rules that need to rewrite HTML content in the <HTMLRules> </HTMLRules> section of the ruleset.

• Include all rules that need to rewrite JavaScript content in the <JSRules> </JSRules> section of the ruleset.

• Include all rules that need to rewrite XML content in the <XMLRules> </XMLRules> section of the ruleset.

• In your intranet pages, identify the URLs that need to be rewritten, and include the required rules in the appropriate sections (HTML, JSRules, or XMLRules) of the ruleset.

• Assign the ruleset to the required domain.

• Restart the Gateway to affect any changes:

  gateway-install-root/SUNWportal/bin/gateway -n gateway-profile-name start

Defining the RuleSet Root Element

The ruleset root element has two attributes:

• RuleSetName, for example, default_ruleset. This name is referenced in RuleSet to URI mapping.

• Extends. This attribute refers to the inheritance feature of rulesets. The value points to the ruleset from which you would like to derive a ruleset.

  Use the value none to signify that this new, independent ruleset does not depend on any other ruleset, or specify the RuleSetName to signify that your ruleset depends on another ruleset.

Using the Recursive Feature

Rewriter uses the recursive feature to search to the end of the matched string pattern for the same pattern.

For example, when Rewriter parses the following string:

<a href="src=abc.jpg,src=bcd.jpg,src=xyz.jpg>

the rule

<Attribute name="href" valuePatterns="*src=**"/>

rewrites only the first occurrence of the pattern, which would look like this:

<a href="src=http://jane.sun.com/abc.jpg>

If you use the recursive option

<Attribute name="href" valuePatterns="REC:*src=**"/>;

Rewriter searches to the end of the matched string pattern for the same pattern, so the output would be:

<a href="src=http://jane.sun.com/abc.jpg,src=http://jane.sun.com/bcd.jpg,src=http://jane.sun.com/xyz.jpg>

Defining Language Based Rules

Rules are based on the following languages:

• HTML

• JavaScript

• XML

Rules for HTML Content

HTML content in web pages can be further classified into attributes, forms and applets. Accordingly, the rules for HTML content are classified as:

• Attribute Rules for HTML Content

• Form Rules for HTML Content

• Applet Rules for HTML Content

Attribute Rules for HTML Content

This rule identifies the attributes of a tag whose value needs to be rewritten. The attribute values can be a simple URL, JavaScript, or DHTML content. For example:

• src attributes of an "img" tag point to an image location (simple URL)

• onClick attribute of a href attributes that handles on clicking of the link (DJS)

This section describes the following:

• Attribute Rule Syntax

• Attribute Rule Example

• DJS Attribute Example

Attribute Rule Syntax

<Attribute name="attributeName" [tag="*" valuePatterns="" source=”*” type=”URL|DHTML|DJS”]/>

where,

attributeName is the name of the attribute (mandatory)

tag is the tag to which the attribute belongs (optional, default * , meaning any tag)

valuePatterns See Using Pattern Matching in Rules.

source specifies the URI of the page in which this attribute is defined ( optional, default * , meaning in any page)

type specifies the type of the value (optional). They can be:

URL - a simple URL (default value).

DHMTL - DHTML content. This kind of content is seen in standard HTML content and is used in Microsoft’s HTC format files.

DJS - JavaScript content. All HTML event handlers such as onClick and onMouseover have JavaScript inlined with the HTML attribute.

Attribute Rule Example

Assume the base URL of the page is:

http://mymachine.intranet.com/mypage.html

Page Content:

<a href="http://mymachine.intranet.com/mypage.html">

Rules

<Attribute name="href"/>
or
<Attribute name="href" tag="a"/>

Output

<a href=gateway-URL/http://mymachine.intranet.com/myhome.html>

Description

Because the URL to be rewritten is already an absolute URL, only the Gateway URL is prefixed to the URL.

DJS Attribute Example

Assume the base URL of the page is:

http://abc.sesta.com/focus.html

Page Content:

<Form>

<input TYPE=TEXT SIZE=20 value=focus onClick="Check(\q/focus.html\q,\qfocus\q);return;">

</Form>

Rules

<Attribute name=”onClick” type=”DJS”/>
<Function type="URL" name="Check" paramPatterns="y,"/>

Output

<Form>

<INPUT TYPE=TEXT SIZE=20 value=focus onClick="Check(\q
gateway-URL
/http://abc.sesta.com/focus.html\q,\qfocus\q);return;">

</Form>

Description

Two rules are required to rewrite the specified page content. The first rule identifies the onClick JavaScript token. The second rule identifies the parameter of the check function that needs to be rewritten. In this case, only the first parameter is rewritten because paramPatterns has the value y in place of first parameter.

The Gateway URL and the base URL of the page on which the JavaScript tokens appear are prefixed to the required parameter.

Form Rules for HTML Content

The HTML pages that a user browses may contain forms. Some form elements may take a URL as the value.

This section is divided into the following parts:

• Form Rule Syntax

• Form Rule Example

Form Rule Syntax

<Form name="form1" field="visit" [valuePatterns="" source="*"]/>

where

name is the name of the form (mandatory)

field is the field in the form whose value needs to be rewritten (mandatory)

valuePatterns See Using Pattern Matching in Rules

source is the URL of the html page where this form definition is present (optional, default *, meaning in any page)

Form Rule Example

Assume the base URL of the page is:

http://test.siroe.com/testcases/html/form.html

Page Content

Assume the page URI is form.html and is located in the root directory of the server.

<form name=form1  method=POST action=
"http://test.siroe.com/testcases/html/form.html">
<input type=hidden name=abc1 value="0|1234|/test.html">
</form>

To rewrite /text.html present in the value of hidden field named abc1 which is part of form1. The following rules are needed.

Rules

<Form source="*/form.html" name="form1" 
field="abc1" valuePatterns="0|1234|"/>
<Attribute name="action"/>

Output

<FORM name=”form1” 
method=”POST” action="gateway-URL/
http://test.siroe.com/testcases/html/form.html">
<input type=hidden name=abc1 
value="0|1234|gateway-URL/
http://test.siroe.com/test.html">
</FORM>

Description

The action tag is rewritten using some defined HTML attribute rule.

The input tag attribute value’s value is rewritten as shown in the output. The specified valuePatterns is located, and all content following the matched valuePatterns is rewritten by prefixing the Gateway URL, and the base URL of the page. See Using Pattern Matching in Rules.

Applet Rules for HTML Content

A single web page may contain many applets, and each applet may contain many parameters. Rewriter matches the values specified in the rule with the HTML definition of the applet and modifies the URL values present as a part of the applet parameter definition. This replacement is carried out at the server and not when the user is browsing the particular web page. This rule identifies and rewrites the parameters in both the applet and object tags of the HTML content.

This section is divided into the following parts:

• Applet Rule Syntax

• Applet Rule Example

Applet Rule Syntax

<Applet code="ApplicationClassName/ObjectID
" param="parametername" [valuePatterns="" source="*"] />

where

code is the name of the applet or object class (mandatory)

param is the name of the parameter whose value needs to be rewritten (mandatory)

valuePatterns See Using Pattern Matching in Rules.

source is the URL of the page that contains the applet definition (optional, default is *, meaning, in any page)

Applet Rule Example

Assume the base URL of the page is:

http://abc.siroe.com/casestudy/test/HTML/applet/rule1.html

Page Content:

<applet codebase=”appletcode” code=”
RewriteURLinApplet.class” archive=”/test.jar”>
<param name=Test1 value="/index.html">
</applet>

Rules

<Applet source="*/rule1.html" code=
"RewriteURLin*.class" param="Test*"/>

Output

<APPLET codebase=”gateway-URL
/http://abc.siroe.com/casestudy/test/HTML/
applet/appletcode” code=”RewriteURLinApplet.class”
 archive=”/test.jar”><param name=”Test1” value="
gateway-URL/http:
//abc.siroe.com/index.html">
</APPLET>

Description

The codebase attribute is rewritten because <Attribute name="codebase"/> is a defined rule in the default_gateway_ruleset.

All parameters whose names begin with Test are rewritten. The base URL of the page on which the applet code displays and the Gateway URL are prefixed to the value attribute of the param tag.

Using Pattern Matching in Rules

You can use the valuePatterns field to achieve pattern matching and identify the specific parts of a statement that need to be rewritten.

If you have specified valuePatterns as part of a rule, all the content that follows the matched pattern is rewritten.

Consider the sample form rule below.

<Form source="*/source.html
" name="form1" field="visit
" [valuePatterns="0|1234|"]/>

where

source is the URL of the html page where the form displays.

name is the name of the form.

field is the field in the form whose value needs to be rewritten.

valuePatterns indicates the portion of the string that needs to be rewritten. All content appearing after valuePatterns is rewritten (optional, default "" means the full value needs to be rewritten).

Specifying Specialized Characters in valuePatterns

You can specify specialized characters by escaping them with a backslash. For example:

<Form source="*/source.html" name="form1" field="visit" [valuePatterns="0|1234|\\;original text|changed text”]/>

Using Wild Cards in valuePatterns

You can use the wildcard asterisk (*) character to achieve pattern matching for rewriting.

You cannot specify just an * in the valuePatterns field. Because * indicates a match with all text, no text follows the valuePattern. Therefore, Rewriter has no text to rewrite. You must use * in conjunction with another string such as *abc. In this case, all content that follows *abc is rewritten.

An asterisk (*) can be used as a wildcard in any of the fields of the rule. However, all the fields in the rule cannot contain an *. If all fields contain a *, the rule is ignored. No error message is displayed.

You can use a * or ** along with the separation character (a semicolon or comma) that displays in the original statement to separate multiple fields. One asterisk (*) matches any field that is not to be rewritten, and two asterisks (**) to match any field that needs to be rewritten.

Using Wild Cards in valuePatterns lists some sample usages of the * wildcard.

Rules for JavaScript Content

JavaScript can contain URLs in various locations. Rewriter cannot directly parse the JavaScript and determine the URL portion. A special set of rules need to be written to help the JavaScript processor to identify and translate the URL.

JavaScript elements with type URL are classified as follows:

• Variables

• Function Arguments

Variables

The generic syntax for variables is:

<Variable name=”variableName“ [type="URL|EXPRESSION|DHTML|DJS|SYSTEM" source=”*”]>

JavaScript variables can be subclassified into 5 categories depending on the type of value they hold:

• URL Variables

• EXPRESSION Variables

• DHTML(Dynamic HTML) Variables

• DJS (Dynamic JavaScript) Variables

• SYSTEM Variables

URL Variables

The variable value is a simple string which can be treated as a URL.

This section is divided into the following parts:

• URL Variable Syntax

• URL Variable Example

URL Variable Syntax

<Variable name=”variableName“ type="URL" [source=”*”]>

where

variableName is the name of the variable. The value of the variableName is rewritten (mandatory).

type is the URL variable (mandatory, and the value must to be a URL)

source is the URI of the page in which this JavaScript variable is found (optional, default is *, meaning in any page)

URL Variable Example

Assume the base URL is:

http://abc.siroe.com/tmp/page.html

Page Content

<script LANGUAGE="Javascript">
<!--
//URL Variables
var imgsrc1="/tmp/tmp.jpg";
var imgsrc2="http://srap.sesta.com/tmp/tmp.jpg";
var imgsrc3=imgsrc2;
//-->
</SCRIPT>

Rules

<Variable name=”imgsrc*” type="URL"/>

Output

<script LANGUAGE="Javascript">
<!--
//URL Variables
var imgsrc="gateway-URL/http://abc.siroe.com/tmp/tmp.jpg";
var imgsrc="gateway-URL/http://srap.sesta.com/tmp/tmp.jpg";
var imgsrc3=imgsrc2;
//-->
</SCRIPT>

Description

All variables of type URL and name beginning with imgsrc are rewritten. For the first line of the output, the Gateway URL and the base URL of the page on which the variable displays are prefixed. The second line already contains the absolute path, and hence only the Gateway URL is prefixed. Third var imagsrc2 would not be rewritten as it’s value is not a string but another JavaScript value.

EXPRESSION Variables

Expression variables have an expression on the right hand side. The result of this expression is a URL. Rewriter appends a JavaScript function (psSRAPRewriter_convert_expression) to the HTML page as it cannot evaluate such expressions on the server. This function takes the expression as a parameter and evaluates it to the required URL at the client browser.

If you are not sure whether a statement contains a simple URL or an EXPRESSION URL, use EXPRESSION rules because it can handle both scenarios.

This section is divided into the following parts:

• EXPRESSION Variable Syntax

• EXPRESSION Variable Example

EXPRESSION Variable Syntax

<Variable name=”variableName” [type="EXPRESSION" source=”*”]/>

where

variableName is the name of the JavaScript variable whose value is a expression (mandatory)

type is the type of JavaScript variable (optional, default value is EXPRESSION)

source is the URI of the pages (optional, default is *, meaning any source)

EXPRESSION Variable Example

Assume the base URL of the page is:

http://abc.siroe.com/dir1/dir2/page.html

Page Content

<script LANGUAGE="Javascript">
<!--
//Expression variables
var expvar= getURIPreFix() + "../../images/graphics"+".gif";
document.write("<A HREF="+expvar+">Link to XYZ content</A><P>")
var expvar="../../images/graphics"+".gif";
//-->
</SCRIPT>

Rules

<Variable name=”expvar” type="EXPRESSION"/>
or
<Variable name=”expvar”/>

Output

var expvar=psSRAPRewriter_convert_expression(getURIPreFix()
 + "../../images/graphics"+".gif");document.write("<a href="+expvar+">>
Link to XYZ content</A><P>")var expvar=”gateway-URL/http://abc.siroe.com/images/graphics"+".gif";

Description

The function psSRAPRewriter_convert_expression is prefixed to the right side of the expression variable expvar in the first line. This function processes the expression and rewrites the content at runtime. In the third line the value is rewritten as a simple URL.

DHTML(Dynamic HTML) Variables

These are JavaScript variables that contain HTML content.

This section is divided into the following parts:

• DHTML Syntax

• DHTML Example

DHTML Syntax

<Variable name=”variableName” type="DHTML" [source=”*”]/>

where

variableName is the name of the JavaScript variable with DHTML content (mandatory)

type is the type of the variable (mandatory, the value must be DHTML)

source is the URL of the page (optional, the default is *, meaning in any page)

DHTML Example

Assume the base URL of the page is:

http://abc.sesta.com/graphics/set1/
graphics/jsscript/JSVAR/page.html

Page Content

<script LANGUAGE="Javascript">
<!--
//DHTML Var
var dhtmlVar="<a href=../../images/test.html>"
var dhtmlVar="<a href=/images/test.html>"
var dhtmlVar="<a href=images/test.html>"
//-->
</SCRIPT>

Rules

<Variable name=”dhtmlVar” type="DHTML"/>
<Attribute name="href"/>
or
<Attribute name="href" tag="a"/>

Output

<script LANGUAGE="Javascript">
<!--
//DHTML Var
var dhtmlVar="<a href=gateway-URL
/http://abc.sesta.com/graphics/
set1/graphics/images/test.html>"
var dhtmlVar="<a href=gateway-URL/
http
://abc.sesta.com/images/test.html>"
var dhtmlVar="<a href=gateway-URL/
http://abc.sesta.com/graphics/set1/
graphics/jscript/JSVAR/images/test.html>"
//--></SCRIPT>

Description

The JavaScript parser reads the value of dhtmlVar as HTML content and sends the content through the HTML parser. The HTML parser applies the HTML rules where the href attribute rules are matched and hence the URL is rewritten.

DJS (Dynamic JavaScript) Variables

These are JavaScript variables that contain JavaScript content.

This section is divided into the following parts:

• DJS Syntax

• DJS Example

DJS Syntax

<Variable name=”variableName” type="DJS" [source=”*”]/>

where

variable is the JavaScript varible whose value is javascript.

DJS Example

Assume the base URL of the page is:

http://abc.sesta.com/dir1/dir2/dir3/jscript/dir4/page.html

Page Content

//DJS Var
var dJSVar="var dJSimgsrc=\q/tmp/tmp.jpg\q;"
var dJSVar="var dJSimgsrc=\q../tmp/tmp.jpg\q;"
var dJSVar="var dJSimgsrc=
\qhttp://abc.sesta.com/tmp/tmp.jpg\q;"

Rules

<Variable name="DJS">dJSVar/>
<Variable name="URL">dJSimgsrc/>

Output

//DJS Var - need 2 rules
var dJSVar="var dJSimgsrc=\qgateway-URL
/http://abc.sesta.com/tmp/tmp.jpg\q;"var dJSVar="var dJSimgsrc=\q
gateway-URL/http
://abc.sesta.com/dir1/dir2/dir3/jscript/tmp/tmp.jpg\q;"
var dJSVar="var dJSimgsrc=\qgateway-URL/
http://abc.sesta.com/tmp/tmp.jpg\q;"

Description

Two rules are required here. The first rule locates the dynamic JavaScript variable dJSVar. The value of this variable is again a JavaScript of type URL. The second rule is applied to rewrite the value of this JavaScript variable.

SYSTEM Variables

These are variables are not declared by the use and have limited support. They are available as a part of the JavaScript standard. For example, window.location.pathname.

This section is divided into the following parts:

• SYSTEM Variable Syntax

• SYSTEM Variable Example

SYSTEM Variable Syntax

<Variable name=”variableName” type="SYSTEM" [source=”*”]/>

where

variableName is the JavaScript system variable (mandatory and the values could be ones that match these patterns: document.URL, document.domain, location, doument.location, location.pathname, location.href, location.protocol, location.hostname, location.host and location.port. All these are present in the generic_ruleset. Do not modifiy these system var rules .

type specifies system type values (mandatory and value is DJS)

source is the URI of this pages (optional, default value is *, meaning in any page)

SYSTEM Variable Example

Assume the base URL of the page is:

http://abc.siroe.com/dir1/page.html

Page Content

<script LANGUAGE="Javascript">
<!--
//SYSTEM Var
alert(window.location.pathname);
//-->
</SCRIPT>

Rules

<Variable name=”window.location.pathname” type="SYSTEM"/>

Output

</SCRIPT>
<SCRIPT LANGUAGE="Javascript">
<!--
//SYSTEM Var
alert(psSRAPRewriter_convert_pathname(window.location.pathname));
//-->
</SCRIPT>

Description

Rewriter locates the system variable which matches the rule, then the psSRAPRewriter_convert_system function is prefixed. This function processes the system variable at runtime and rewrites the resulting URL accordingly.

Function Arguments

Function parameters whose value needs to be rewritten are classified into 4 categories:

• URL Parameters

• EXPRESSION Parameters

• DHTML Parameters

• DJS Parameters

Generic Syntax

<Function name="functionName" paramPatterns="y,y," [type="URL|EXPRESSION|DHTML|DJS" source=”*”]/>

where

name is the name of the JavaScript function (mandatory)

paramPatterns specifies the parameters that need to be rewritten (mandatory)

y the position of y indicates the parameter that the needs to be rewritten. For example, in the syntax, the first parameter needs to be rewritten, but the second parameter should not be rewritten.

type specifies the kind of value this parameter needs (optional, default is EXPRESSION type)

source page source URI (optional, default is *, meaning in any page)

URL Parameters

Function takes this parameter as a string and this string could be treated as URL.

This section is divided into the following parts:

• URL Parameter Syntax

• URL Parameter Example

URL Parameter Syntax

<Function name="functionName" paramPatterns="y,," type="URL" [source=”*”]/>

where

name is the name of the function with a type parameter of URL (mandatory)

paramPatterns specifies the parameters that need to be rewritten (mandatory)

y the position of y indicates the parameter that needs to be rewritten. For example, in the syntax, the first parameter needs to be rewritten, but the second parameter should not be rewritten.

type is the type of the function (mandatory, and the value must be URL)

source is the URL of the page which has this function call (optional, default is *, meaning in any URL)

URL Parameter Example

Assume the base URL of the page is:

http://abc.sesta.com/test/rewriter/test1/jscript/test2/page.html

Page Content

<script language="JavaScript">
<!--
function test(one,two,three){
alert(one + "##" + two + "##" +three);
}
test("/test.html","../test.html","123");
window.open("/index.html","gen",width=500,height=500);
//-->
</SCRIPT>

Rules

<Function name="URL" name="test" paramPatterns="y,y,"/>
<Function name="URL" name="window.open" paramPatterns="y,,,"/>

Output

<SCRIPT language="JavaScript">
<!--
function test(one,two,three) {
alert(one + "##" + two + "##" +three);
}
test("gateway-URL/http://abc.sesta.com/test.html","
gateway-URL/http://abc.sesta.com/test/rewriter/
test1/jscript/test.html","123");window.open("gateway-URL/
http://abc.sesta.com/index.html","gen",width=500,height=500);
//-->
</SCRIPT>

Description

The first rule specifies that the first two parameters in the function with name test need to be rewritten. Hence the first two parameters of the test function are rewritten. The second rule specifies that the first parameter of the window.open function needs to be written. The URL within the window.open function is prefixed with the Gateway URL and the base URL of the page that contains the function parameters.

EXPRESSION Parameters

These parameters take an expression value, which when evaluated, results in a URL.

This section is divided into the following parts:

• EXPRESSION Parameter Syntax

• EXPRESSION Parameter Example

EXPRESSION Parameter Syntax

<Function name="functionName" paramPatterns="y" [type="EXPRESSION" source=”*”]/>

where

name is the name of the function (mandatory).

paramPatterns specifies the parameters that need to be rewritten (mandatory)

y the position of y indicates the function parameter that needs to be rewritten. In the syntax above, only the first parameter is rewritten.

type specifies the value EXPRESSION (optional)

source URI of the page where this function is called.

EXPRESSION Parameter Example

Assume the base URL of the page is:

http://abc.sesta.com/dir1/dir2/page.html

Page Content

<script language="JavaScript">
<!--
function jstest2(){
return ".html";
}
function jstest1(one){
return one;
}
var dir="/images/test"
var test1=jstest1(dir+"/test"+jstest2());
document.write("<a HREF="+test1+">TEST</a>");
alert(test1);
//-->
</SCRIPT>

Rules

<Function type="EXPRESSION" name="jstest1" paramPatterns="y"/>
or
<Function name="jstest1" paramPatterns="y"/>

Output

<script language="JavaScript">
<!--
function jstest2(){
return ".html";
}
function jstest1(one){
return one;
}
var dir="/images/test"
var test1=jstest1(psSRAPRewriter_convert_expression(dir+"/test"+jstest2()));
document.write("<a HREF="+test1+">TEST</a>");
alert(test1);
//-->
</SCRIPT>

Description

The rule specifies that the first parameter of the jstest1 function needs to be rewritten by considering this as an EXPRESSION function param. In the sample page content, the first parameter is an expression that will be evaluated only at runtime. Rewriter prefixes this expression with the psSRAPRewriter_convert_expression function. The expression is evaluated, and the psSRAPRewriter_convert_expression function rewrites the output at runtime.

In the above example, the variable test1 is not required as a part of the JavaScript variable rule. The function rule for jstest1 takes care of the rewriting.

DHTML Parameters

Function parameter whose value is HTML

Native JavaScript methods such as document.write() that generate an HTML page dynamically fall under this category.

This section is divided into the following parts:

• DHTML Parameter Syntax

• DHTML Parameter Example

DHTML Parameter Syntax

<Function name="functionName" paramPatterns="y" type="DHTML" [source=”*”]/>

where

name is the name of the function.

paramPatterns specifies the parameters that need to be rewritten (mandatory)

y the position of y indicates the function parameter that needs to be rewritten. In the syntax above, only the first parameter is rewritten.

DHTML Parameter Example

Assume the base URL of the page is:

http://xyz.siroe.com/test/rewriter/test1/jscript/JSFUNC/page.html

Page Content

<script>
<!--
document.write(\q<a href="/index.html">write</a><BR>\q)
document.writeln(\q<a href="index.html">writeln</a><BR>\q)
document.write("http://abc.sesta.com/index.html<BR>")
document.writeln("http://abc.sesta.com/index.html<BR>")
//-->
</SCRIPT>

Rules

<Function name="DHTML" name="document.write" paramPatterns="y"/>
<Function name="DHTML" name="document.writeln" paramPatterns="y"/>
<Attribute name="href"/>

Output

<SCRIPT>
<!--
document.write(\q<a href="gateway-URL/
http://xyz.siroe.com/index.html">write</a><BR>\q)
document.writeln(\q<a href="gateway-URL/
http://xyz.siroe.com/test/rewriter/test1/
jscript/JSFUNC/index.html">writeln</a><BR>\q)
document.write("http://abc.sesta.com/index.html<BR>")
document.writeln("http://abc.sesta.com/index.html<BR>")
//-->
</SCRIPT>

Description

The first rule specifies that the first parameter in the function document.write needs to be rewritten. The second rule specifies that the first parameter in the function document.writeln needs to be rewritten. The third rule is a simple HTML rule that specifies that all attributes with the name href need to be rewritten. In the example, the DHTML parameter rules identify the parameters in the functions that need to be rewritten. Then the HTML attribute rule is applied to actually rewrite the identified parameter.

DJS Parameters

Function parameters whose value is JavaScript.

This section is divided into the following sections:

• DJS Parameter Syntax

• DJS Parameter Example

DJS Parameter Syntax

<Function name="functionName" paramPatterns="y" type="DJS" [source=”*”]/>

where

name is the name of the function where one parameter is DJS (mandatory)

paramPatterns specifies which parameter in the above function is DJS (mandatory)

y the position of y indicates the function parameter that needs to be rewritten. In the syntax above, only the first parameter is rewritten.

type is DJS (mandatory)

source is the URI of the page (optional, default is *, meaning any URI)

DJS Parameter Example

Assume the base URL of the page is:

http://abc.sesta.com/page.html

Page Content

<script>
menu.addItem(new NavBarMenuItem("All Available Information","JavaScript:top.location=\qhttp://abc.sesta.com\q"));
</script>

Rules

<Function name="DJS" name="NavBarMenuItem" paramPatterns=",y"/>
<Variable name="URL">top.location</Variable>

Output

<script>
menu.addItem(new NavBarMenuItem("All Available Information",
"JavaScript:top.location=\qgateway-URL/
http://abc.sesta.com\q"));
</script>

Description

The first rule specifies that the second parameter of the function NavBarMenuItem which contains JavaScript needs is to be rewritten. Within the JavaScript, the variable top.location also needs to be rewritten. This variable is rewritten using the second rule.

Rules for XML Content

Web pages may contain XML content which in turn can contain URLs. XML content that needs to be rewritten is classified into two categories:

• Tag Text (same as PCDATA or CDATA of the tag)

• Attribute

Tag Text

This rule is for rewriting the PCDATA of CDATA of the tag element.

This section is divided into the following parts:

• Tag Text Syntax

• Tag Text Example

Tag Text Syntax

<TagText tag="tagName" 
[attributePatterns=”attribute_patterns_for_ this_tag" source=”*”]/>

where

tagName is the name of the tag

attributePatterns is the attributes and their value patterns for this tag (optional, meaning this tag has no attributes at all)

source is the URI of this xml file (optional, default is *, meaning, any xml page)

Tag Text Example

Assume the base URL of the page is:

http://abc.sesta.com/test/rewriter/test1/xml/page.html

Page Content

<xml>
<Attribute name="src">test.html</attribute>
<attribute>abc.html</attribute>
</xml>

Rules

<TagText tag="attribute" attributePatterns="name=src"/>

Output

<xml>
<Attribute name="src">gateway-URL/
http://abc.sesta.com/test/rewriter/test1/
xml/test.html</attribute><attribute>abc.html</attribute>
</xml>

Description

The first line in the page content has an Attribute Example. The second line in the page content does not contain an attribute with the attribute called name and value of attribute name to be src, and hence no rewriting is done. To rewrite this also we need to have <TagText tag="attribute"/>

Attribute

The rules for XML attributes are similar to the attribute rules for HTML. The difference is that attribute rules of XML are cases sensitive while HTML attribute rules are not. This is again due to case sensitivity built into XML and not into HTML.

Rewriter translates the attribute value based on the attribute name.

This section is divided into the following parts:

• Attribute Syntax

• Attribute Example

Attribute Syntax

<Attribute name="attributeName" [tag="*" type=”URL” valuePatterns="*" source=”*”]/>

where

attributeName is the name of the attribute (mandatory)

tag is the name of the tag, where this attribute is present (optional, deafult is * , meaning any tag)

valuePatterns See Using Pattern Matching in Rules.

source is the URI of this XML page (optional, default is *, meaning in any XML page)

Attribute Example

Assume the base URL of the page is:

http://abc.sesta.com/test/rewriter/test1/xml/page.html

Page Content

<xml>
<baseroot href="/root.html"/>
<img href="image.html"/>
<string href="1234|substring.html"/>
<check href="1234|string.html"/>
</xml>

Rules

<Attribute name="href"tag="check" valuePatterns="1234|"/>

Output

<xml>
<baseroot href="/root.html"/><img href="image.html"/>
<string href="1234|substring.html"/><check href="1234|
gateway-URL
/http://abc.sesta.com/test/rewriter/test1/xml/string.html"/></xml>

Description

In the above example, only the fourth line is rewritten because it meets all the conditions specified in the rule. See Using Pattern Matching in Rules.

Rules for Cascading Style Sheets

The Cascading Style Sheets (including CCS2) in HTML pages are translated. No rules are defined for this translation as the URL presents only in the url() functions and import syntaxes of the CSS.

Rules for WML

WML is similar to HTML and hence HTML rules are applied for WML content.Use the generic ruleset for WML content. See Rules for HTML Content.

Using the Recursive Feature

Rewriter uses the recursive feature to search to the end of the matched string pattern for the same pattern.

For example, when Rewriter parses the following string:

<a href="src=abc.jpg,src=bcd.jpg,src=xyz.jpg>

the rule

<Attribute name="href" valuePatterns="*src=**"/>

rewrites only the first occurrence of the pattern and it would look like this:

<a href="src=http://jane.sun.com/abc.jpg>

but if you use the recursive option as,

<Attribute name="href" valuePatterns="REC:*src=**"/>;

Rewriter searches to the end of the matched string pattern for the same pattern, hence the output would be:

<a href="src=http://jane.sun.com/abc.jpg,src=http://jane.sun.com/bcd.jpg,src=http://jane.sun.com/xyz.jpg>

Troubleshooting Using Debug Logs

To troubleshoot a Rewriter problem, you need to enable debug logs.

Debug Messages are classified as follows.

• Error– errors that Rewriter cannot recover from

• Warning– warnings that do not critically affect the functioning of Rewriter. Rewriter is able to recover this type of error, but some misbehavior may or may not result. Some messages shown in warnings are informational. For example “Not rewriting image content” is logged as a warning message. This is fine as Rewriter is not supposed to rewrite the images.

• Message– the highest level of information that Rewriter provides.

Setting the Rewriter Debug Level

To Set the Rewriter Debug Level

1. Log in as root to the Gateway machine and edit the following file:

   gateway-install-root/SUNWam/config/AMConfig-instance-name.properties

2. Set the debug level:

   com.iplanet.services.debug.level=

   The debug levels are:

   error - Only serious errors are logged in the debug file. Rewriter usually stops functioning when such errors occur.

   warning - Warning messages are logged.

   message - All debug messages are logged.

   off - No debug messages are logged.

3. Specify the directory for the debug files in the following property of the AMConfig-instance-name.properties file:

   com.iplanet.services.debug.directory=/var/opt/SUNWam/debug

   where /var/opt/SUNWam/debug is the default debug directory.

4. Restart the Gateway from a terminal window:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

Debug File Names

When the debug level is set to message, debug generates a set of files. Debug File Names lists the Rewriter files and the information contained within them.

In addition to the above files, Rewriter generates a file for debug messages that are not captured in the above files. This file name consists of two parts: the first part is either pwRewriter or psSRARewriter and the second part is an extension using either portal or the gateway-profile-name.

The debug files are displayed on the portal or the Gateway. These files are in the directory indicated in the AMConfig-instance-name.properties file.

The Rewriter component generates the following set of files to help in debugging,

prefix_RuleSetInfo.extension

prefix_OrginalPages.extension

prefix_RewrittenPages.extension

prefix_UnaffectedPages.extension

prefix_URIInfo.extension

where

prefix is either psRewriter for URLScraper usage logs or psSRAPRewriter for Gateway usage logs.

extension is either portal for URLScraper usage or gateway-profile-name for Gateway usage.

For example, if the Rewriter on the Gateway is used to convert pages and the default gateway profile is used, debug creates these files:

psSRAPRewriter_RuleSetInfo.default

psSRAPRewriter_OriginalPages.default

psSRAPRewriter_RewrittenPages.default

psSRAPRewriter_UnaffectedPages.default

psSRAPRewriter_URIInfo.default

psSRAPRewriter.default

Working Samples

This section includes:

• Simple HTML pages with content that needs to be rewritten

• Rules required to rewrite the content

• Corresponding rewritten HTML page

These sample pages are available in the portal-server-URL/rewriter directory. You can browse through the page before the rule is applied, and then view the file with the rewritten output through your Gateway to see how the rule works. In some samples, the rule is already a part of the default_gateway_ruleset. In some samples, you may have to include the rule in the default_gateway_ruleset. This is mentioned at the appropriate places.

Some of the statements appear in bold to indicate that they have been rewritten.

The following samples are available:

HTML

• Sample for HTML Attributes

• Sample for HTML Forms

• Sample for HTML Applets

JavaScript

• Variables

  • Sample for JavaScript URL Variables

  • Samples for JavaScript Content

  • Sample for JavaScript DHTML Variables

  • Sample for JavaScript DJS Variables

  • Sample for JavaScript SYSTEM Variables

Functions

• Sample for JavaScript URL Functions

• Sample for JavaScript EXPRESSION Functions

• Sample for JavaScript DHTML Functions

• Sample for JavaScript DJS Functions

XML

• Sample for XML Attributes

Samples for HTML Content

Sample for HTML Attributes

To Use the HTML Attributes Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/HTML/attrib/attribute.html

2. Ensure that abc.sesta.com and host1.siroe.com are defined in the Proxies for Domains and Subdomains list in the Gateway service.

   If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

   You need not add the rule specified in this sample to the default_gateway_ruleset because the rule is already defined.

HTML Before Rewriting

<html>
Rewriting starts
<head>
<title>TEST PAGE () </title>
</head>
ID-htmlattr.1
<br><br>
1.a href <a href="http://abc.sesta.com/images/logo.gif">http://..</a>
<br><br>
2. href <a href="https://host1.siroe.com">https://..</a>
<br><br>
3. href <a href="../images/logo.gif">../images/</a>
<br><br>
4. href <a href="images/logo.gif">images/..</a> <br><br>
5. href <a href="../../images/logo.gif">../../images/</a> <br><br>
Rewriting ends
</html>

Rule

<Attribute name="href"/>

HTML After Rewriting

<html>
Rewriting starts
<head>
<title>TEST PAGE () </title>
</head>
ID-htmlattr.1
<br><br>
1. a href <a href="gateway-URL/http://abc.sesta.com/images/logo.gif">http://..</a> <br>

// This URL is rewritten because the <Attrib name="href"/> rule is already defined in the default_gateway_ruleset. Because the URL is already absolute, only the Gateway URL is prefixed. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service. Otherwise, the Gateway URL is not prefixed, because a direct connection is assumed.

2. href <a href="gateway-URL/https://host1.siroe.com">https://..</a>

// Again, host1.siroe.com needs to be defined in the Proxies for Domains and Subdomains list in the Gateway service. Otherwise, the Gateway URL is not prefixed, because a direct connection is assumed.

<br><br>
3. href <a href="gateway-URL/portal-server-URL/rewriter/HTML/images/logo.gif">../images/</a>

// Because a relative path is specified, the Gateway URL and the portal-server-URL are prefixed along with the required subdirectories. This link will not work because a directory called images under the HTML directory is not specified in the sample structure provided.

<br><br>

4 href <a href="gateway-URL/portal-server-URL/rewriter/HTML/attrib/images/
logo.gif">images/..</a> <br><br>

// Because a relative path is specified, the Gateway URL and the Portal Server URL are prefixed along with the required subdirectories.

5. href <a href="gateway-URL/portal-server-URL/rewriter/images/logo.gif">
../../images/</a> <br><br>

// Because a relative path is specified, the Gateway URL and the Portal Server URL are prefixed along with the required subdirectories. This link will not work because a directory called images under the Rewriter directory is not specified in the sample structure provided

Rewriting ends</html>

Sample for HTML Dynamic JavaScript Tokens

This section discuses using the HTML JavaScript token sample

To Use the HTML JavaScript Token Sample:

1. This sample can be accessed from:

   portal-server-URL/rewriter/HTML/jstokens/JStokens.html

2. Add the rule specified in this sample to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source".

3. Edit the default_gateway_ruleset in the Rewriter service under the Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway from a terminal window:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Before Rewriting

<html>
<head>
Rewriting starts
<script language="javascript">
function Check(test,ind){
if (ind == \qblur\q)
{alert("testing onBlur")}
if (ind == \qfocus\q)
{alert("testing onFocus")}
}
</SCRIPT>
</head>
<body>
<form>
<input TYPE=TEXT SIZE=20 value=blur onAbort="Check
(\q/indexblur.html\q,\qblur\q);return;">
<input TYPE=TEXT SIZE=20 value=blur onBlur="Check
(\q/indexblur.html\q,\qblur\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onFocus="Check
(\q/focus.html\q,\qfocus\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onChange="Check
(\q/focus.html\q,\qfocus\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onClick="Check
(\q/focus.html\q,\qblur\q);return;">
<br><br>
</form>
</body>
Rewriting ends
</html>

Rule

<Attribute name=”onClick” type=”DJS”/>
<Function type="URL" name="Check" paramPatterns="y"/>

<Function name="URL" name="Check" paramPatterns="y"/> is a JavaScript function rule and is explained in detail in the JavaScript function sample.

HTML After Rewriting

<html>
<head>
Rewriting starts
<script language="javascript">
function Check(test,ind){
if (ind == \qblur\q)
{alert("testing onBlur")}
if (ind == \qfocus\q)
{alert("testing onFocus")}
}
</SCRIPT>
</head>
<body>
<form>
<input TYPE=TEXT SIZE=20 value=blur onAbort="Check
(\qgateway URL/portal-server-URL/indexblur.html\q,\qblur\q);return;">
<input TYPE=TEXT SIZE=20 value=blur onBlur="Check
(\qgateway URL/portal-server-URL/indexblur.html\q,\qblur\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onFocus="Check
(\qgateway URL/portal-server-URL/focus.html\q,\qfocus\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onChange="Check
(\qgateway URL/portal-server-URL/focus.html\q,\qfocus\q);return;">
<input TYPE=TEXT SIZE=20 value=focus onClick="Check
(\qgateway URL/portal-server-URL/focus.html\q,\qblur\q);return;">

// All the statements are rewritten in this sample. The Gateway and Portal Server URLs are prefixed in each case. This is because rules for onAbort, onBlur, onFocus, onChange, and onClick are defined in the default_gateway_ruleset file. Rewriter detects the JavaScript tokens and passes it to the JavaScript function rules for further processing. The second rule listed in the sample tells Rewriter which parameter to rewrite.

</body>
<br>

Rewriting ends

</html>

Sample for HTML Forms

To Use the Form Sample

1. Access the sample from:

   portal-server-URL/rewriter/HTML/forms/formrule.html

2. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service.

   If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

3. Add the rule specified in this sample to the default_gateway_ruleset in the section "Rules for Rewriting HTML Attributes".

4. Edit the default_gateway_ruleset in the Rewriter service under the Portal Server Configuration in the Portal Server administration console.

5. Restart the Gateway from a terminal window:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
</head>
<body>
RW_START
<p>
<form name="form1" method="Post" action=
"http://abc.sesta.com/casestudy/html/form.html">
<input type="hidden" name="name1" value="0|1234|/test.html">
<input type="hidden" name="name3" value="../../html/test.html">
<form name="form2" method="Post" action="
http://abc.sesta.com/testcases/html/form.html"><br>
<input type="hidden" name="name1" value="0|1234|
../../html/test.html"></form>
RW_END </p>
</body>
</html>

Rule

<Form source="*" name="form1" field="name1" valuePatterns="0|1234|"/>

HTML Page After Rewriting

<HTML>
<HEAD>
RW_START
</HEAD>
<BODY>
<P>
<FORM name=form1  method=POST action="gateway-URL/http://abc.sesta.com/casestudy/html/form.html">

// This URL is rewritten because <Attribute name="action"/> is defined as part of the HTML rules in the default_gateway_ruleset. Because the URL is already absolute, only the Gateway URL needs to be prefixed. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service. Else, the Gateway URL is not prefixed because a direct connection is assumed.

<input type=hidden name=name1 value=
"0|1234|gateway URL/portal-server-URL/test.html">

// Here the form name is form1, and the field name is name1. This matches the form name and field name specified in the rule. The rule states the valuePatterns as 0|1234| which matches the value in this statement. Hence the URL occurring after the valuePattern is rewritten. The Portal Server URL and the Gateway URL are prefixed. See “Using Pattern Matching in Rules for details on valuePatterns.

<input type=hidden name=name3 value="../../html/test.html">

// This URL is not rewritten because the name does not match the field name specified in the rule.

</FORM>
<FORM name=form2 method=POST action=
"gateway-URL/http://abc.sesta.com/casestudy/html/form.html"><BR>

// This URL is rewritten because <Attribute name="action"/> is defined as part of the HTML rules in the default ruleset. Because the URL is already absolute, only the Gateway URL needs to be prefixed.

<input type=hidden name=name1 value="0|1234|../../html/test.html">

// This URL is not rewritten because the form name does not match the name specified in the rule.

</FORM>
</BODY>
RW_END
</HTML>

Sample for HTML Applets

To Use the Sample for Applets

1. Obtain the applet class file. The RewriteURLinApplet.class file is present in the following location:

   portal-server-URL/rewriter/HTML/applet/appletcode

   The base URL of the page where the applet code is present is:

   portal-server-URL/rewriter/HTML/applet/rule1.html

2. Add the rule specified in this sample to the default_gateway_ruleset in the section "Rules for Rewriting HTML Attributes".

3. Edit the default_gateway_ruleset in the Rewriter service under the Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Before Rewriting

<html>
Rewriting starts
<br>
<applet codebase=appletcode code=RewriteURLinApplet.class archive=/test>
<param name=Test1 value="/index.html">
<param name=Test2 value="../index.html">
<param name=Test3 value="../../index.html">
</applet>
Rewriting ends
</html>

Rule

<Applet source="*/rule1.html" code="RewriteURLinApplet.class" param="Test*" />

HTML After Rewriting

<HTML>
Rewriting starts
<BR>
<APPLET codebase=gateway-URL/portal-server-URL
/rewriter/HTML/applet/appletcode=RewriteURLinApplet.class archive=/test>

// This URL is rewritten because the rule <Attribute name="codebase"/> is already present as part of the default_gateway_ruleset file. the Gateway and the Portal Server URLs are prefixed along with the path up to the appletcode directory.

<param name=Test1 value=
"gateway-URL/portal-server-URL/index.html">

// This URL is rewritten because the base URL of the page is rule1.html, and the param name matches the param Test* specified in the rule. Because index.html is specified to be at the root level, the Gateway and Portal Server URLs are prefixed directly.

<param name=Test2 value="gateway-URL
/portal-server-URL/rewriter/HTML/index.html">

// This URL is rewritten because the base URL of the page is rule1.html, and the param name matches the param Test* specified in the rule. The path is prefixed as required.

<param name=Test3 value="gateway-URL
/portal-server-URL/rewriter/index.html">

// This URL is rewritten because the base URL of the page is rule1.html, and the param name matches the param Test* specified in the rule. The path is prefixed as required.

</APPLET>
Rewriting ends
</HTML>

Samples for JavaScript Content

Sample for JavaScript URL Variables

To Use the JavaScript URL Variables Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/variables/url/js_urls.html

2. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service.

   If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

3. Add the rule specified in this sample to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source".

4. Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

5. If you added the rule, restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
Rewriting starts
<head>
<title>JavaScript Variable test page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//URL Variables
var imgsrc="/tmp/tmp.jpg";
var imgsrc="./tmp/tmp.jpg";
var imgsrc="../tmp/tmp.jpg";
var imgsrc="../../tmp/tmp.jpg";
var imgsrc="http://abc.sesta.com/tmp/tmp.jpg";
var imgsrc="../../../tmp/tmp.jpg";
var imgsrc="tmp/tmp.jpg";
//-->
</SCRIPT>
<br>
Testing JavaScript variables!
<br>
<img src="images/logo.gif">
<br>
Image
</body>
<br>
Rewriting ends
</html>

Rule

<Variable name=”imgsrc” type="URL"/>

HTML Page After Rewriting

<html>
Rewriting starts
<head>
<title>JavaScript Variable test page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//URL Variables
var imgsrc="gateway-URL/portal-server-URL/tmp/tmp.jpg";
var imgsrc="gateway-URL/portal-server-URL
/rewriter/JavaScript/variables/url/tmp/tmp.jpg";
var imgsrc="gateway-URL/portal-server-URL
/rewriter/JavaScript/variables/tmp/tmp.jpg";
var imgsrc="gateway-URL/portal-server-URL
/rewriter/JavaScript/tmp/tmp.jpg";
var imgsrc="gateway-URL/http://abc.sesta.com/tmp/tmp.jpg";
var imgsrc="gateway-URL/portal-server-URL/rewriter/tmp/tmp.jpg";
var imgsrc="gateway-URL/portal-server-URL
/rewriter/JavaScript/variables/url/tmp/tmp.jpg";

// All the above URLs are JavaScript variables of type URL and name imgsrc as specified in the rule. Hence they are prefixed with the Gateway and the Portal Server URLs. The path following the Portal Server URL is prefixed as required.

//-->
</SCRIPT>
<br>
Testing JavaScript variables!
<br>
<img src="gateway URL/portal-server-URL/rewriter
/JavaScript/variables/url/images/logo.gif">

// This line is rewritten because the rule <Attribute name="src"/> is defined in the default_gateway_ruleset

<br>
Image
</body>
<br>
Rewriting ends
</html>

Sample for JavaScript EXPRESSION Variables

To Use the JavaScript Expression Variables Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/variables/expr/expr.html

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source".

3. Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. If you added the rule, restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<head>
<title>JavaScript EXPRESSION Variables Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//Expression variables
var expvar1="images";
var expvar2="/logo.gif";
var expvar = expvar1 + expvar2;
document.write("<A HREF="+expvar+">EXPRESSION</A><P>")
var expvar="/images/logo"+".gif";
document.write("<A HREF="+expvar+">EXPRESSION</A><P>")
//-->
</SCRIPT>
Testing JavaScript EXPRESSION variables
</body>
</html>

Rule

<Variable type=”EXPRESSION” name="expvar"/>

HTML Page After Rewriting

<html>
<head>
<title>JavaScript EXPRESSION Variables Test Page</title>
</head>
<body>
<SCRIPT>
// Rewriter appends the wrapper function 
psSRAPRewriter_convert_expression here
</SCRIPT>
<script LANGUAGE="Javascript">
<!--
//Expression variables
var expvar1="images";
var expvar2="/logo.gif";
var expvar =psSRAPRewriter_convert_expression( expvar1 + expvar2);

// Rewriter recognizes the right hand side of this statement to be a JavaScript EXPRESSION variable. Rewriter is not able to resolve the value of this expression at the server end. Hence, the psSRAPRewriter_convert_expression function is prefixed to the expression. The expression is evaluated at the client end, and rewritten as required.

document.write("<A HREF="+expvar+">EXPRESSION</A><P>")

// The rewritten value of expvar from the previous statement is used to arrive at the value of this expression. Because the result is a valid URL (a graphic exists at this location in the sample), the link will work.

var expvar="gateway URL/portal-server-URL/images/logo"+".gif";

// Rewriter recognizes the right hand side of expvar to be a string expression. This can be resolved at the server side, and hence is rewritten directly.

document.write("<A HREF="+expvar+">EXPRESSION</A><P>")

// The rewritten value of expvar from the previous statement is used to arrive at the value of this expression. Because the result is a not a valid URL (a graphic does not exist at the resultant location), the link will not work.

//-->
</SCRIPT>
Testing JavaScript EXPRESSION variables
</body>
</html>

Sample for JavaScript DHTML Variables

To Use the JavaScript DHTML Variables Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/variables/dhtml/dhtml.html

2. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service. If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

3. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source". Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. If you added the rule, restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<head>
<title>JavaScript DHTML Variable Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//DHTML Var
var dhtmlVar="<a href=../../images/test.html>"
var dhtmlVar="<a href=/../images/test.html>"
var dhtmlVar="<a href=/images/test.html>"
var dhtmlVar="<a href=images/test.html>"
var dhtmlVar="<a href=http://abc.sesta.com/images/test.html>"
var dhtmlVar="<img src=http://abc.sesta.com/images/test.html>"
//-->
</SCRIPT>
<br><br>
Testing DHTML Variables
<br><br>
<img src="images/logo.gif">IMAGE
</body>
</html>

Rule

<Variable name="DHTML">dhtmlVar</Variable>

HTML Page After Rewriting

<html>
<head>
<title>JavaScript DHTML Variable Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//DHTML Var
var dhtmlVar="<a href=gateway-URL/portal-server-URL
/rewriter/JavaScript/images/test.html>"

// The JavaScript DHTML rule identifies the right hand side of the dhtmlVar as dynamic HTML content. Hence, the HTML rules in the default_gateway_ruleset file are applied. The dynamic HTML contains a href attribute. The default_gateway_ruleset defines the rule <Attribute name="href"/>. Hence the value of the href attribute is rewritten. But the URL is not absolute; therefore, the relative URL is replaced with the base URL of the page, and the required subdirectories. This in turn is prefixed with the Gateway URL to derive the final rewritten output.

var dhtmlVar="<a href=gateway-URL
/portal-server-URL/../images/test.html>"

// Although the base URL of the page is appended, and the Gateway URL is prefixed, the resultant URL will not work. This is because the initial URL /../images/test.html is inaccurate.

var dhtmlVar="<a href=gateway-URL
/portal-server-URL/images/test.html>"

// Here again, the JavaScript DHTML rule identifies the right hand side to be dynamic HTML content, and passes it to the HTML rules. The HTML rule <Attribute name="href"/> from the default_gateway_ruleset is applied, and the statement is rewritten as shown. The Gateway URL and Portal Server URL are prefixed.

var dhtmlVar="<a href=gateway URL/portal-server-URL/
rewriter/JavaScript/variables/dhtml/images/test.html>"
var dhtmlVar="<a href=gateway URL/http://abc.sesta.com/images/test.html>"
var dhtmlVar="<img src=gateway-URL/
http://abc.sesta.com/images/test.html>"

// The JavaScript DHTML rule identifies the dynamic HTML content on the right hand side, and passes the statement to the HTML rules. The <Attribute name="src"/> rule in the default_gateway_ruleset is applied. Because the URL is absolute, only the Gateway URL needs to be prefixed. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list for this URL to be rewritten.

//-->
</SCRIPT>
<br><br>
Testing DHTML Variables
<br><br>
<img src="gateway-URL/portal-server-URL/
rewriter/JavaScript/variables/dhtml/images/logo.gif">

// This line is rewritten because the rule <Attribute name="src"/> is defined in the default_gateway_ruleset.

<br><br>
Image
</body>
</html>

Sample for JavaScript DJS Variables

To Use the JavaScript DJS Variables Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/variables/djs/djs.html

2. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service. If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

3. Add the two rules specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source". Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<head>
<title>Dynamic JavaScript Variable Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
var dJSVar="var dJSimgsrc=\q/tmp/tmp/jpg\q;"
var dJSVar="var dJSimgsrc=\q../../../tmp/tmp/jpg\q;"
var dJSVar="var dJSimgsrc=\qhttp://abc.sesta.com/tmp/tmp/jpg\q;"
//-->
</SCRIPT>
<br>
Testing Dynamic JavaScript Variables
<br>
<img src="images/logo.gif">
<br>
Image
</body>
</html>

Rule

<Variable name=”dJSVar” type="DJS"/>
<Variable name="dJSimgsrc“ type=URL"/>

HTML Page After Rewriting

<html>
<head>
<title>Dynamic JavaScript Variable Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
var dJSVar="var dJSimgsrc=\qgateway-URL
/portal-server-URL/tmp/tmp/jpg\q;"
var dJSVar="var dJSimgsrc=\qgateway-URL
/portal-server-URL/rewriter/tmp/tmp/jpg\q;"
var dJSVar="var dJSimgsrc=\qgateway-URL
/http://abc.sesta.com/tmp/tmp/jpg\q;"

// All the above statements are rewritten with the Gateway and Portal Server URLs. The required path is prefixed as appropriate. The first rule identifies the right hand side of dJSVar as a dynamic JavaScript variable. This is then passed to the second rule which identifies the right hand side of dJSimgsrc as a JavaScript variable of type URL. This is rewritten accordingly.

//-->
</SCRIPT>
<br>
Testing Dynamic JavaScript Variables
<br>
<img src="gateway-URL/portal-server-URL
/rewriter/JavaScript/variables/djs/images/logo.gif">

// This line is rewritten because the rule <Attribute name="src"/> is defined in the default_gateway_ruleset.

<br>
Image
</body>
</html>

Sample for JavaScript SYSTEM Variables

To Use the JavaScript System Variables Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/variables/system/system.html

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source".

3. Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<head>
<title>JavaScript SYSTEM Variables Test Page</title>
</head>
<body>
<script LANGUAGE="Javascript">
<!--
//SYSTEM Var
alert(window.location.pathname);
//document.write
("<A HREF="+window.location.pathname+">SYSTEM</A><P>")
//-->
</SCRIPT>
Testing JavaScript SYSTEM Variables
<br>
This page displays the path where 
the current page is located when loaded.
</body>
</html>

Rule

<Variable name=”window.location.pathname” type="SYSTEM"/>

HTML After Rewriting

<html>
<head>
<title>JavaScript SYSTEM Variables Test Page</title>
</head>
<body>
<SCRIPT>
convertsystem function definition...
</SCRIPT>
<script LANGUAGE="Javascript">
<!--
//SYSTEM Var
alert(psSRAPRewriter_convert_system
(window.location, window.location.pathname,”window.location”));

// Rewriter identifies window.location.pathname as a JavaScript SYSTEM variable. The value of this variable cannot be determined at the server end. So the Rewriter prefixes the variable with the psSRAPRewriter_convert_pathname function. This wrapper function determines the value of the variable at the client end and rewrites as required.

//-->
</SCRIPT>
Testing JavaScript SYSTEM Variables
<br>
This page displays the path where
the current page is located when loaded.
</body>
</html>

Sample for JavaScript URL Functions

To Use the JavaScript URL Functions Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/functions/url/url.html

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source". Edit the default_gateway_ruleset in the Rewriter service under the Portal Server Configuration in the Portal Server administration console.

3. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<body>
JavaScript URL Function Test Page
<br>
<script language="JavaScript">
<!--
function test(one,two,three)
{
alert(one + "##" + two + "##" +three);
}
test("/test.html","../test.html","123");
window.open("/index.html","gen",width=500,height=500);
//-->
</SCRIPT>
</body>
</html>

Rule

<Function type="URL" name="test" paramPatterns="y,y"/>
<Function type="URL" name="window.open" paramPatterns="y"/>

HTML Page After Rewriting

<html>
<body>
JavaScript URL Function Test Page
<br>
<script language="JavaScript">
<!--
function test(one,two,three)
{
alert(one + "##" + two + "##" +three);
}
test("/test.html","../test.html","123");
window.open("gateway-URL/portal-server-URL
/index.html","gen",width=500,height=500);
//-->
</SCRIPT>
</body>
</html>

Sample for JavaScript EXPRESSION Functions

To Use the JavaScript Expressions Function Sample

1. This sample can be accessed from:

   <portal-install-location>/SUNWportal/samples/rewriter

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section Rules for Rewriting JavaScript Source.

3. Edit the default_gateway_ruleset in the Rewriter service using the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<body>
JavaScript EXPRESSION Function Test Page
<br><br><br>
<script language="JavaScript">
<!--
function jstest2()
{
return ".html";
}
function jstest1(one)
{
return one;
}
var dir="/images/test"
var test1=jstest1(dir+"/test"+jstest2());
document.write("<a HREF="+test1+">Test</a>");
alert(test1);
//-->
</SCRIPT>
</body>
</html>

Rule

<Function type="EXPRESSION" name="jstest1" paramPatterns="y"/>

HTML Page After Rewriting

<html>
<body>
JavaScript EXPRESSION Function Test Page
<br><br><br>
<script>
<!--
// various functions including psSRAPRewriter_
convert_expression appear here.//-->
</SCRIPT>
<script language="JavaScript">
<!--
function jstest2()
{
return ".html";
}
function jstest1(one)
{
return one;
}
var dir="/images/test"
var test1=jstest1(psSRAPRewriter_convert_
expression(dir+"/test"+jstest2()));

// The rule states that the first parameter in the function jstest1 which is of type EXPRESSION needs to be rewritten. The value of this expression is /test/images/test.html. This is prefixed with the Portal Server and the Gateway URLs.

document.write("<a HREF="+test1+">Test</a>");
alert(test1);
//-->
</SCRIPT>
</body>
</html>

Sample for JavaScript DHTML Functions

To Use the JavaScript DHTML Functions Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/functions/dhtml/dhtml.html

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source".

3. Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
<head>
Testing JavaScript DHTML Functions
<br>
<br>
<script>
<!--
document.write(\q<a href="/index.html">write</a><BR>\q)
document.writeln(\q<a href="index.html">writeln</a><BR>\q)
document.write("http://abc.sesta.com/index.html<BR>")
document.writeln("http://abc.sesta.com/index.html<BR>")
//-->
</SCRIPT>
</head>
<body BGCOLOR=white>
<br><br>
Testing document.write and document.writeln
</body>
</html>

Rule

<Function type="DHTML" name=" document.write" paramPatterns="y"/>
<Function type="DHTML" name=" document.writeln" paramPatterns="y"/>

HTML Page After Rewriting

<html>
<head>
Testing JavaScript DHTML Functions
<br>
<br>
<script>
<!--
document.write(\q<a href="gateway-URL
/portal-server-URL/index.html">write</a><BR>\q)

// The first rule specifies that the first parameter of the DHTML JavaScript function document.write needs to be rewritten. Rewriter identifies the first parameter to be a simple HTML statement. The HTML rules section in the default_gateway_ruleset has the rule <Attribute name="href" /> which indicates that the statement needs to be rewritten.

document.writeln(\q<a href="gateway-URL
/portal-server-URL/rewriter/JavaScript/functions/dhtml/index.html">writeln</a><BR>\q)

// The second rule specifies that the first parameter of the DHTML JavaScript function document.writeln needs to be rewritten. Rewriter identifies the first parameter to be a simple HTML statement. The HTML rules section in the default_gateway_ruleset has the rule <Attribute name="href" /> which indicates that the statement needs to be rewritten.

document.write("http://abc.sesta.com/index.html<BR>")
document.writeln("http://abc.sesta.com/index.html<BR>")

// The above statements are not rewritten although the DHTML rule identifies the functions document.write and document.writeln. This is because the first parameter in this case is not simple HTML. It could be any string, and Rewriter does not know how to rewrite this.

//-->
</SCRIPT>
</head>
<body BGCOLOR=white>
<br><br>
Testing document.write and document.writeln
</body>
</html>

Sample for JavaScript DJS Functions

To Use the JavaScript DJS Functions Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/JavaScript/functions/djs/djs.html

2. Ensure that abc.sesta.com is defined in the Proxies for Domains and Subdomains list in the Gateway service.

   If this is not defined, a direct connection is assumed, and the Gateway URL is not prefixed.

3. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting JavaScript Source". Edit the default_gateway_ruleset in the Rewriter service under Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

HTML Page Before Rewriting

<html>
Test for JavaScript DJS Functions
<br>
<script>
menu.addItem(new NavBarMenuItem("All Available
Information","JavaScript:top.location=\qhttp://abc.sesta.com\q"));
//menu.addItem(new NavBarMenuItem("All Available Information","http://abc.sesta.com"));
</script>
</html>

Rule

<Function type="DJS" name="NavBarMenuItem" paramPatterns=",y"/>
<Variable type="URL" name=”top.location”/>

HTML Page After Rewriting

<html>
Testing JavaScript DJS Functions
<br>
<script>
menu.addItem(new NavBarMenuItem
("All Available Information","javaScript:top.location=
\qgateway-URL/http://abc.sesta.com\q"));

// abc.sesta.com is an entry in the Proxies for Domains and Subdomains list in the Gateway service. Hence Rewriter needs to rewrite this URL. But because an absolute URL, the Portal Server URL need not be prefixed. The DJS rule states that the second parameter of the DJS function NavBarMenuItem needs to be rewritten. But the second parameter is again a JavaScript variable. A second rule is required to rewrite the value of this variable. The second rule specifies that the value of the JavaScript variable top.location needs to be rewritten. Because all these conditions are met, the URL is rewritten.

//menu.addItem(new NavBarMenuItem("All Available Information","http://abc.sesta.com"));

// Although the DJS rule specifies that the second parameter of the function NavBarMenuItem needs to be rewritten, it does not happen in this statement. This is because Rewriter does not recognize the second parameter as simple HTML.

</script>
</html>

Sample for XML Attributes

To Use the XML Attributes Sample

1. This sample can be accessed from:

   portal-server-URL/rewriter/XML/attrib.html

2. Add the rule specified in this sample (if it does not already exist) to the default_gateway_ruleset in the section "Rules for Rewriting XML Source".

3. Edit the default_gateway_ruleset in the Rewriter service under the Portal Server Configuration in the Portal Server administration console.

4. Restart the Gateway:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

XML Before Rewriting

<html>
RW_START
<body>
<xml>
<baseroot href="/root.html"/>
</xml>
<xml>
<img href="image.html"/>
</xml>
<xml>
<string href="1234|substring.html"/>
</xml>
<xml>
<check href="1234|string.html"/>
</xml>
</body>
RW_END
</html>

Rule

<Attribute name="href" tag="check" valuePatterns="1234|"/>

HTML After Rewriting

<html>
Rewriting starts
<br>
<br>
<body>
<xml><baseroot href="/root.html"/></xml>
<xml><img href="image.html"/></xml>
<xml><string href="1234|substring.html"/></xml>
<xml><check href="1234|gateway-URL/portal-server-URL
/rewriter/XML/string.html"/></xml>

// This statement is rewritten because it matches the conditions specified in the rule. The Attribute name is href, tag is check and the valuePatterns is 1234. The string following valuePatterns is rewritten. See Using Pattern Matching in Rules for details on valuePatterns.

</body>
Rewriting ends
</html>

Case Study

This section includes the source HTML pages for a sample mail client. This case study does not cover all possible scenarios and rules. This is just a sample ruleset to help you put together the rules for your intranet pages.

Assumptions

The following assumptions are made for this case study:

• The base URL of the mail client is assumed to be abc.siroe.com

• The Gateway URL is assumed to be gateway.sesta.com

• Relevant entries exist in the Proxies for Domains and Subdomains list in the Gateway service

Sample page 1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0053)http://abc.siroe.com/mailclient/destin/?Cmd=navbar -->
<HTML XMLNS:WM><HEAD>
<META http-equiv=Content-Type content="text/html; CHARSET=utf-8">
<META http-equiv=Pragma content=no-cache>
<META http-equiv=Expires content=0><!--Copyright (c) 2000 Microsoft Corporation.
All rights reserved.--><!--CURRENT FILE== "IE5" "WIN32" navbar -->
<STYLE>WM\\:DROPMENU {
BEHAVIOR: url(http://abc.siroe.com/mailweb/controls/dropmenu.htc)
}
</STYLE>
<LINK href="destin_files/navbar.css" type=text/css rel=stylesheet>
<SCRIPT language=javascript>
var g_szUserBase= "http://abc.siroe.com/mailclient/destin"+"/";
var g_szFolder= ".";
var g_szVirtualRoot= "http://abc.siroe.com/mailweb";
var g_szImagePath= g_szVirtualRoot + "/img/";
</SCRIPT>
<SCRIPT src="/destin_files/navbar.js"></SCRIPT>
<META content="MSHTML 6.00.2600.0" name=GENERATOR></HEAD>
<BODY oncontextmenu=return(event.ctrlKey); onselectstart=return(false);
id=outbar_mainbody style="BACKGROUND-COLOR: appworkspace" leftMargin=0
topMargin=0 scroll=no>
<TABLE class=nbTableMain id=nbTableMain style="HEIGHT: 100%" cellSpacing=0
cols=1 cellPadding=0 rows="2">
<TBODY>
<TR>
<TD class=treeBrand>
<DIV class=treeOFLOW><IMG
style="PADDING-RIGHT: 0px; PADDING-LEFT: 0px; PADDING-BOTTOM: 0px; PADDING-TOP: 0px"
src="/destin_files/logo-ie5.gif" border=0></DIV></TD></TR>
<TR height="100%">
<TD>
<TABLE class=nbTable cellSpacing=0 cols=1 cellPadding=0 rows="4">
<TBODY>
<TR>
<TD class=nbFlybar id=show_navbar onkeydown=flybar_keydown()
onclick=ToggleTab(this.id) tabIndex=0 noWrap>
<DIV class=treeOFLOW>Shortcuts</DIV></TD></TR>
<TR style="HEIGHT: 100%">
<TD id=idOutbarpane style="TEXT-ALIGN: center" vAlign=top><A
id=inbox
href="http://abc.siroe.com/mailclient/destin/Inbox/?Cmd=contents&amp;Page=1"
target=viewer alt="Go to inbox"><IMG class=nbImage alt="Go to inbox"
src="destin_files/navbar-inbox.gif"></A>
<DIV class=nbLabel>Inbox</DIV><BR><A id=calendar
href="http://abc.siroe.com/mailclient/destin/Calendar/?Cmd=contents"
target=viewer alt="Go to calendar"><IMG class=nbImage
alt="Go to calendar" src="destin_files/navbar-calendar.gif"></A>
<DIV class=nbLabel>Calendar</DIV><BR><A id=contacts
            href="http://abc.siroe.com/mailclient/destin/Contacts/?Cmd=contents"
target=viewer alt="Go to contacts"><IMG class=nbImage
alt="Go to contacts" src="destin_files/navbar-contacts.gif"></A>
<DIV class=nbLabel>Contacts</DIV><BR><A id=options
href="http://abc.siroe.com/mailclient/destin/?Cmd=options"
target=viewer alt="Go to options"><IMG class=nbImage
alt="Go to options" src="destin_files/navbar-options.gif"></A>
<DIV class=nbLabel>Options</DIV></TD></TR>
<TR style="HEIGHT: 1.5em">
<TD class=nbFlybar id=show_folders onkeydown=flybar_keydown()
onclick=ToggleTab(this.id) tabIndex=0 noWrap>
<DIV class=treeOFLOW>Folders</DIV></TD></TR>
<TR>
<TD class=nbTreeProgress id=treeProgress style="DISPLAY: none"
vAlign=top noWrap><SPAN id=idLoading
style="OVERFLOW: hidden">Loading...</SPAN>
</TD></TR></TBODY></TABLE></TD></TR></TBODY></TABLE>
</BODY></HTML>

Description

Description shows the mapping between the sample ruleset and the case study.

var g_szVirtualRoot=
"http://abc.siroe.com/mailweb";

var g_szVirtualRoot= 
"http://gateway.sesta.com
/http://abc.siroe.com/mailweb";

src="/destin_files/
logo-ie5.gif"

src="http://gateway.sesta.com/
http://abc.siroe.com/
destin_files/logo-ie5.gif

href="http://abc.siroe.com

/mailclient/destin/Inbox/
?Cmd=contents&Page=1"

href="http://gateway.sesta.com/
http://abc.siroe.com
/mailclient/destin/
Inbox/?Cmd=contents&Page=1"

The order of priority for applying the ruleset is hostname-subdomain-domain.

For example, assume that you have the following entries in the Domain-based rulesets list:

sesta.com|ruleset1
eng.sesta.com|ruleset2
host1.eng.sesta.com|ruleset3

ruleset3 is applied for all pages on host1.

ruleset2 is applied for all pages in the eng subdomain, except for pages retrieved from host1.

ruleset1 is applied for all pages in the sesta.com domain, except for pages retrieved from the eng subdomain, and from host1.

1. Click Save to complete.

2. Restart the Gateway from a terminal window:

   ./psadmin start-sra-instance –u amadmin – f <password file> –N <profile name>– t <gateway>

Ruleset for Outlook Web Access

Secure Remote Access server supports MS Exchange 2000 SP3 installation and MS Exchange 2003 of Outlook Web Access (OWA) on the Sun Java System Web Server and the IBM application server.

To Configure the OWA Ruleset

1. Log into the Portal Server administration console as administrator.

2. Select the Secure Remote Access tab, and select the Gateway profile for which you want to set the attribute.

3. In the Map URIs to RuleSets field, enter the server name where Exchange 2000 is installed followed by the Exchange 2000 Service Pack 4 OWA ruleset.

   For example:

   exchange.domain.com|exchange_2000sp3_owa_ruleset.

Using Public Folders

On the Exchange side Public Folders are configured to use NTLM Authorization. It needs to be changed to use HTTP Basic Authorization.

To do this, go to the Exchange server and select the Control Panel-->Administrative Tools, then open Internet Information Services.

Under Default Web Site there is a tab for Public Folders called Public. Right Click and select properties. Click on Directory Security Tab. Select "Edit.." on the Anonymous Access and Authentication control panel. Unselect everything else and select only Basic Authentication.

Mapping of 6.x RuleSet with 3.0

The following table lists the mapping of the Secure Remote Access server Rewriter rules with the previous releases of the Portal Server product.

Chapter 5 Working with NetFile

This chapter describes NetFile and its operation. To configure NetFile, see Chapter 14, Configuring NetFile.

• Introduction to NetFile

• Supported File Access Protocols

Introduction to NetFile

NetFile is a file manager application that enables the user to access and operate on remote file systems and directories.

The NetFile component of Secure Remote Access is available as Java2 applets. The Java2 applet has a better interface and increased ease of accessibility.

NetFile provides the following key features:

• Facility to add or remove shares or folders

• File upload and download

• Search for files and folders

• File compression using GZIP and ZIP

• Mail facility within the NetFile environment

• Save the current NetFile session information

• Drag and Drop of files

Supported File Access Protocols

NetFile allows you to access remote systems using FTP, NFS, and jCIFS (Microsoft Windows) protocols. It includes the following file access protocol features:

• If the user specifies AUTODETECT to add a system, NetFile uses the following sequence to automatically detect which protocol to use:

  • Checks the host for FTP server on port 21. If the FTP response contains the string "NetWare", this is considered a NETWARE host.

  • Checks the host for NFS server on port 2049.

  • Checks the host for Microsoft Windows on port 139.

  • If all of the above fail, a message saying unable to determine the host type is displayed.

    The first file system type that is detected is used to connect to the requested host. The host detection order can be changed in the Portal Server administration console (PSConsole).

The connection fails if the servers are running on non-standard ports.

• NetFile enables users to select the file server and protocol of their choice.

  For each of these protocols, the platforms that are supported are listed below.

To upload files to a ProFTPD server using NetFile, "AllowStoreRestart" needs to be set to "on" in the proftpd.conf file on the host running ProFTPD server.

Support for Novell Netware is only through FTP server and not through native access.

To access Microsoft Windows (SMB/CIFS) file systems jCIFS must be installed on the Portal Server. jCIFS is an Open Source client library that implements the CIFS/SMB networking protocol.

To Create a NetFile Policy

1. Login to Portal Administration Console as administrator.

2. Select Secure Remote Access tab, and select NetFile tab.

3. Select the Organization/Role/User from Select DN drop-down box.

4. Set the privileges to access/deny hosts and services.

5. Click Save.

6. Restart the gateway.

Chapter 6 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 the Netlet.

This chapter contains the following sections:

• Introduction to Netlet

• Downloading an Applet From a Remote Host

• Defining Netlet Rules

• Sample Netlet Rules

• Netlet Logging Information

• Running Netlet in a Sun Ray Environment

Introduction to 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 6–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 the 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.

Connections to hosts provided in the chain is attempted serially. For example, if the rule is siroe+ sesta, then a connection to siroe is attempted first. If the connection fails then the connection to sesta is attempted . If the hosts listed first in the rule are physically unavailable in an active network, the time taken to connect to the next available host will increase as the number of unavailable hosts in the rule increases.

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.

Netlet Logging Information

Client side logs for the netlet applet or the jws appear on the java console of the client.

Server side logs for the netlet appear in the portal.0.0.log file present under the /var/opt/SUNWportal/portals/<portal_ID>/logs/<INSTANCE_ID> 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>