Installation Information

• If the Portal Server installation contains both a server node and one or more platform nodes, then must be applied on the server node first, then each additional platform node as well. The patch must also be applied to any installed gateway nodes following completion of application to the Server and platform nodes.
  
  
• In addition to the required Solaris patches, Mozilla.org's Rhino JavaScript engine is also required if you have a Gateway node in place and would like end users to be able to use automatic proxy configuration files in conjunction with the Portal Server Netlet functionality. Rhino 1.5R1, which has been tested and certified for use by Portal Server Quality Assurance, is available for download at http://www.mozilla.org/rhino/, or from the third party product distribution.

1. In a terminal window, become root.
2. Download and install Rhino Version 1.5R1 on the server node if needed for automatic proxy configuration support by the Netlet. Rhino must be installed to the JRE being used by the Portal. In 6.2, this would be /usr/j2se/jre.

   # unzip rhino15R1.zip # cp rhino/js.jar /usr/j2se/jre/lib/ext/js.jar # chmod 444 /usr/j2se/jre/lib/ext/js.jar

3. Be sure the server and platform nodes on which you are currently installing are running and use the Solaris[tm] patchadd command to apply the patch.

   # root@ps-server: /etc/init.d/amserver startall

4. Apply the patch using patchadd to other installed nodes on separate machines including any Portal proxies or Gateway nodes.

   # root@ps-server: patchadd

NOTE:
If you are running a portal in a non-root environment the file ownerships need to be checked and/or the procedure to convert to non-root usage needs to be re-applied after applying the patches.

Back to top

Template Modifications Required

Every attempt is made by the patch installer to both preserve customized template information and automate the update of that information. However, since the contents of the files cannot be accurately predetermined, any modified template files are backed up in the same directory as their updated counterparts with the patch name postfixed to the template name. For example, /etc/opt/SUNWps/desktop/default/MyFrontPageTabPanelContainer \ /Netlet/display.template might be backed up to /etc/opt/SUNWps/desktop/default/MyFrontPageTabPanelContainer/ \ /Netlet/display.template.pre . The backup files are also copied back to their original location upon patch removal. To help avoid potential content-related customization problems, refer to the Tips for Customizing Templates section of this document. The following template files, .properties files, jsps, xml files, and platform files are modified by this patch consolidation:

Back to top

Tips for Customizing Templates

Because the Portal Server itself is so customizable, you should follow some precautions to insure that any customizations made to the Portal Server are preserved after a product upgrade. First, set up a customized template directory if you have not already done so. While this directory could be an entire subset of the default template directory, it is advisable to only copy over those template files that you will be customizing. This particular scheme would then use the default directory as a 'base' for all templates and would help insure that customized templates are not accidentally overwritten when the default templates are modified.

NOTE: Files in the default template directory should should never be customized.

As a general rule of thumb, avoid modifying templates that have only a functional purpose rather than a look and feel purpose. One example of a template that should not need modifications is the NetletProvider/display.template . This template contains only JavaScript necessary for the launching of the Netlet. The contents of the Netlet Pop-up window should instead be customized by modifying the associated .properties file. The reason for this is that there could be a functional change in the product that would overwrite a customization done specifically to that particular template file. This example also exhibits why it is important to only keep customized files in the customized template directory.

Back to top

Checking the Current Product Install Level

and subsequent patch consolidations make changes to both the gateway, and version scripts necessary to print additional information about the current install level. In previous versions of Portal, this information had to be gathered from a variety of sources including the package versions, patchadd -p output, or from a flatfile that was not updated by patches themselves. Portal patches will now update the version files when they are installed and again when they are backed out.

To get the version information for the Gateway node, from node itself as root, type:

# /etc/init.d/gateway version
Mon Nov 17 13:48:15 PST 2003 Sun ONE Portal Server Secure Remote Access 6.2
Mon Apr 26 14:38:05 PST 2004

# <install_dir>/SUNWps/bin/version
Thu Jun 19 14:29:46 PDT 2003 Portal Server 6.1
Mon Apr 26 14:30:18 PST 2004

# /etc/init.d/amserver version
Sun One Identity Server 6.1

An RFE has been filed to modify the Identity Server version information to match that which is available in Portal Server. The First line of the version output contains the major version information that may also include the product build date. Each remaining line of output represents a patch that has been applied to the major version. The comma separated list in order includes the actual patchID (currently a Solaris patch ID), the patch name, and the patch install date. All of this information is important for supportability purposes and to help Portal administrators in product maintainance.

Enabling Exchange 2003 Support Through the Rewriter

This section covers the rewriter integration with Microsoft Outlook Web Access that is delivered as a part of Microsoft Exchange 2003. For integrations with other versions of Microsoft Exchange Server refer to the Sun Blueprints online article titled Sun ONE Portal Server and Microsoft Exchange Integration Cookbook. Follow the steps bellow in enable Microsoft Exchange 2003 support through the rewriter.

1. Associate the new Exchange rulest to include the Exchange Server

As a part of the patch installation, an additional ruleset has been added to the Portal Service in the Identity Server. A new rule association can be created from the Rewriter tab of the Gateway profile Service Configuration. For instance, to create the association for the default Gateway profile:

1. Login to the Identity Administration Console
2. Select the Service Configuration Tab in the upper pane
3. Expand the link next to Gateway under the SRA Configuration section of the left pane
4. Select default from the list of profiles
5. Select the Rewriter Tab from the right pane
6. In the URI to RuleSet Mappings list add an entry similar to the following:
   *://*ex-server.domain.com|exchange_2003_owa_ruleset where ex-server.domain.com is the fully qualified named of the Exchange Server that will be accessed via the Portal Gateway.
7. Select Save
8. Restart the Identity Server and then the Gateway node

2. Disable NTLM Authentication on the Exchange Server

NTLM Authentication must be disabled on the Exchange Server if Internet Explorer browser clients will be used. NTLM is a Windows domain based proprietary authentication protocol that is not supported by the Gateway reverse proxy. HTTP Basic Authentication can be used instead and the Portal Server can cache the authentication credentials to achieve SSO functionality for remote users. For information on enabling HTTP Basic Authentication Caching refer to the SRA Administrator's Guide. To disable NTLM authentication in Microsoft Exchange 2003 perform the following steps:

1. Launch the Microsoft Exchange System Manager
2. From the left hand pane expand Servers
3. Expand the virtual server that Exchange was deployed to
4. Expand Protocols -> HTTP -> Exchange Virtual Server
5. Right select Exchange and choose properties
6. Select the Access tab in the Exchange propertiees window
7. Select the Authentication button
8. In the authentication methods window be sure that Basic authentication is selected, and NTLM authentication is not selected
9. Select OK
10. Select Apply and OK

Fixing Problems With Portlet Channels

Patch fixes the following problems with portlet channels.

1. Bug# 5016148: Value collision when number of portlet channels on the same page are setting the same attribute.
2. Bug# 5023785: Portlet-mode in portlet.xml is case-sensitive.

• Undeploy the application using pdeploy

  <install_dir>/SUNWps/bin/pdeploy undeploy -u "uid=amAdmin,ou=People,dc=red,dc=iplanet,dc=com" -w <password> -p <password> -g <NameofPortletApplication>

• Deploy the application again using pdeploy

  <install_dir>/SUNWps/bin/pdeploy deploy -u "uid=amAdmin,ou=People,dc=red,dc=iplanet,dc=com" -w <password> -p <password> -g <NameofPortletApplication.war>

• Restart the server

  /etc/init.d/amserver startall

Enabling Delegated Administrator Support Through the Rewriter

This section covers the rewriter integration with Delegated Administrator that ships with Sun Messaging Server. The integration includes a fix for BugID #5032856 mentioned in the patch README in addition to a boilerplate rewriter ruleset to use for the integration. The ruleset is uploaded to the Identity Server as a part of the patch installation process, and needs to be mapped to the appropriate machine host in order to be affective. To map the new iDA ruleset, do the following:

1. Login in to the Identity Administration Console as amadmin
2. Select the Service Configuration tab from the top view pane
3. Expand the link next to Gateway under the SRA Configuration subheading in the left view pane
4. Select the appropriate profile that will be used to access Delegated Administrator from the right view pane
5. Select the Rewriter Tab under the Edit Gateway Profile heading
6. In the URL to RuleSet Mappings field create a mapping for the Delegated Administrator Host
   
   EX: http://mailhost.subdomain.domain.com:88*|ida_ruleset
   
   Since Messaging Express and Delegated Administrator may be installed on the same host, be sure to include the port number the service is listening on in the ruleset mapping.
7. Select Add
8. Select Save
9. Select the Proxies tab
10. Be sure that the Delegated Administrator server domain name is listed in the Proxies for Domains and Subdomains field. If not, add it and select save.
11. Restart the Gateway

Configuring Personal Address Book For Multiple Domains

This section covers details on how to configure Personal Address Book (PAB) with multiple hosted domains. This patch has a fix for bug# 4942807 which allows to configure PAB to authenticate users to different domains. Before this fix the users were always authenticated to the default domain and therefore if two users in different domains had same user id, users were able to see address book of the user in the default domain. This patch uses a domain attribute to distinguish between the users of different domains and the users authenticate to the domain they belong to. We need to add an attribute "domain" to the user's SSOAdapter template for PAB to specify which domain this particular user belongs to. This can be done using the following steps. These steps are necessary to ensure proper functioning of PAB with different domains.

1. Login to IS admin console
2. Select Service Configuration Tab
3. Click the arrow next to SSOAdapter
4. In Global section, select the SSO Adapter template you are using for your PAB configuration
   
   EX: Template with configName=SUN-ONE-ADDRESS-BOOK
   
   
5. Change the template to add a string "&merge=domain"
   
   EX: By Default the value of Template for SUN-ONE-ADDRESS-BOOK is
   default|ldap://[SERVER-NAME:PORT]/?configName=[SUN-ONE-ADDRESS-BOOK]&pabSearchBase=[PAB-SEARCH-BASE] \
   &userSearchBase=[USER-SEARCH-BASE]&aid=[ADMIN-ID]&adminPassword=[ADMIN-PASSWORD] \
   &imapHost=[IMAP-HOST]&imapPort=[IMAP-PORT]&clientPort=[CLIENT-PORT] \
   &enableProxyAuth=false&proxyAdminUid=[PROXY-ADMIN-UID] \
   &proxyAdminPassword=[PROXY-ADMIN-PASSWORD]&type=AB-TYPE \
   &subType=sun-one&ssoClassName=com.sun.ssoadapter.impl.LDAPABSSOAdapter\
   &encoded=password&default=ssoClassName&default=host&default=port\
   &default=pabSearchBase&default=userSearchBase&default=aid&default=adminPassword\
   &default=imapHost&default=imapPort&default=clientPort&default=type\
   &default=subType&default=enableProxyAuth&default=proxyAdminUid\
   &default=proxyAdminPassword&merge=uid&merge=password&default=enablePerRequestConnection\
   &enablePerRequestConnection=false&default=userAttribute&userAttribute=uid
   
   Change it to
   default|ldap://[SERVER-NAME:PORT]/?configName=[SUN-ONE-ADDRESS-BOOK]&pabSearchBase=[PAB-SEARCH-BASE]\
   &userSearchBase=[USER-SEARCH-BASE]&aid=[ADMIN-ID]&adminPassword=[ADMIN-PASSWORD]\
   &imapHost=[IMAP-HOST]&imapPort=[IMAP-PORT]&clientPort=[CLIENT-PORT]\
   &enableProxyAuth=false&proxyAdminUid=[PROXY-ADMIN-UID]\
   &proxyAdminPassword=[PROXY-ADMIN-PASSWORD]&type=AB-TYPE\
   &subType=sun-one&ssoClassName=com.sun.ssoadapter.impl.LDAPABSSOAdapter\
   &encoded=password&default=ssoClassName&default=host&default=port\
   &default=pabSearchBase&default=userSearchBase&default=aid&default=adminPassword\
   &default=imapHost&default=imapPort&default=clientPort&default=type\
   &default=subType&default=enableProxyAuth&default=proxyAdminUid\
   &default=proxyAdminPassword&merge=uid&merge=password&merge=domain&default=enablePerRequestConnection\ <-- "change is in here"
   &enablePerRequestConnection=false&default=userAttribute&userAttribute=uid
   
   
6. Click Add and Save button
7. Make sure that new template is added.
8. Remove the old one by selecting the template and click remove and save button
9. Add the String "&domain=" to the SSO Adapter Configurations at the organization level, role or user level depending on your setup.
   
   NOTE: It is important to add this to the lowest level which has the SSOAdapter configuration templates setup else the changes wont take affect. However if it was not configured for the users and they were using the organization or role level template then you need to do it only at those levels.
   
   EX: If you have two domains : domain1.Sun.com and domain2.sun.com
   Steps to configure them at org level are
   1. Select the first organization (domain1.sun.com)
   2. From the View choice list, select services.
   3. Select SSOAdapter
   4. Select the template for the PAB.
   EX: default|undef:///?configName=sunOneAddressBook&configDesc=SUN-ONE-ADDRESS-BOOK
   5. Add the domain at the end.
   EX: default|undef:///?configName=sunOneAddressBook&configDesc=SUN-ONE-ADDRESS-BOOK&domain=domain1.sun.com
   6. Click add and save.
   7. Repeat the steps for second domain and make sure to change the domain to domain2.
   
   
10. Restart the server
11. Login to admin console again and verify that the changes are present

Enabling Gateway Charset Detection Heuristics

This patch introduces a new feature in gateway where the gateway is able to recognize the encoding to use for translating files which dont have HTTP headers for encoding or Meta Tags for Content Type. Solution uses the opensource libraries from mozilla to do the character detection and those bits needs to be downloaded and installed separately from the patch. Follow the steps below to enable this feature.

NOTE: Perform the following steps after installing the patch

1. Download the thirdparty bits shipped with Jave Enterprise System 2 for portalserver
1. Go to http://wwws.sun.com/software/download/allproducts.html
2. Click on Sun Java Enterprise System 2004Q2
3. In product section, there is a subsection for Accessory CD, volume2 select the link for "Sun Java System Portal Server Secure Remote Access 6.2: Rhino, jCIFS"
4. Save the file as sun_java_ent_sys_r2_ps_6.3_thirdparty_acc.zip on the Gateway node.
2. Add the new charset package
1. Become root
   # su -
2. unzip the downloaded file.
   # unzip sun_java_ent_sys_r2_ps_6.3_thirdparty_acc.zip
3. Change directories to the newly created directory "jchardet"
   # cd jchardet
4. Add the SUNWjchdt package by using the Solaris™ pkgadd command
   # pkgadd -d . SUNWjchdt
5. Confirm the default directory (/usr/share/lib), or select your own to be specified later in the Gateway start script
3. Change the gateway script to include the chardet.jar file
1. Change directories to the /etc/init.d/ directory
   # cd /etc/init.d/
2. Backup the original gateway script
   # cp gateway gateway.prechardet
3. Change the gateway start script to include the chardet.jar jar in the Java CLASSPATH. The Following diffs show the procedure done for the default chardet install location:
   

   *** gateway.prechardet Wed Jul  7 16:01:41 2004
   --- gateway Wed Jul  7 16:11:34 2004
   ***************
   *** 31,36 ****
   --- 31,37 ----
     GETTEXT=/usr/bin/gettext
     JSS_NSS_NSPR_LIBPATH=/usr/lib/mps/secv1
     JSS_JAR=/usr/share/lib/mps/secv1/jss3.jar
   + CHARDET_JAR=/usr/share/lib/chardet.jar
   ***************
   *** 172,178 ****
         # Classpath is w.r.t. working directory that is $PS_HOME
         GW_CLASSPATH="lib:locale:lib/gateway.jar:lib/rewriter.jar:lib/certadmin.jar:lib/ssl.jar:lib/x509v1.jar"
     
   !     GW_CLASSPATH="$IS_CLASSPATH:$JCE_CLASSPATH:$JSS_JAR:$GW_CLASSPATH"
     
         if [ -z "$CLASSPATH" ] ; then
               CLASSPATH="$GW_CLASSPATH"
   --- 173,179 ----
         # Classpath is w.r.t. working directory that is $PS_HOME
         GW_CLASSPATH="lib:locale:lib/gateway.jar:lib/rewriter.jar:lib/certadmin.jar:lib/ssl.jar:lib/x509v1.jar"
     
   !     GW_CLASSPATH="$IS_CLASSPATH:$JCE_CLASSPATH:$JSS_JAR:$CHARDET_JAR:$GW_CLASSPATH"
     
         if [ -z "$CLASSPATH" ] ; then
               CLASSPATH="$GW_CLASSPATH"

4. Restart the server and gateway to enable the new feature.

Back to top

Configuring the Network Socket Timeout Between the Gateway and the Netlet Proxy

This patch includes a new option to configure a fixed timeout for the network socket that is opened between the Gateway and Netlet Proxy if the Netlet Proxy is in use. This option was included to reduce socket depletion resulting from sockets on the Netlet Proxy node remaining indefinitely in an ESTABLISHED state.

For example, prior to this fix, if a Telnet session was opened via the Netlet and there was no activity for 2-4 minutes, the Telnet session would timeout as a result of the idle timout being reached. However, the socket opened between Gateway and Netlet Proxy would remain in an ESTABLISHED state. The same behavior would result from a user explicitly exiting the Telnet session as well.

The new option included with this patch gives portal administrators the ability to explicitly set a timeout for how long the abandoned socket should remain open. The default value of this timeout is 10 minutes. So, if there is no activity between the Gateway and Netlet Proxy socket for 10 minutes, the socket will be closed. If this value needs to be changed, an entry for gateway.netletproxy.socket.timeout can be added to the platform.conf file on the Gateway with the new value specified in milliseconds.

Example:
To change the value to five minutes, the following step should be performed on the Gateway instance(s) which require modification.

1. Change directory to /etc/opt/SUNWps
2. Backup the platform.conf.<gateway_instance> file; where gateway_instance is the instance you want to configure this option for.
3. Edit the platform.conf.<gateway_instance> file and add the following entry:
   
   gateway.netletproxy.socket.timeout=300000
   
   
4. Restart the gateway Instance

NOTE: If the socket timeout is set too high, the socket depletion could be significant enough to cause Netlet connections to hang.

Eliminating the Specific Portal Server Requirement During Gateway Failover

The Gateway normally requires a specific Portal Server to be available when the Gateway starts up. This Portal Server which the Gateway uses is defined in the Gateway's platform.conf file in an entry called gateway.dsame.agent. This entry's value creates a single point of failure for each Gateway instance that will prevent it from properly restarting should the specified Portal Server be temporarily unavailable.

To rememdy this problem, multiple entries can be created in each gateway instance platform.conf file in order of preference. For instance, to define two Portal Servers to use during Gateway startup edit the /etc/opt/SUNWps/platform.conf.<gateway_instance> file and change:

gateway.dsame.agent=http://host1:80/portal/RemoteConfigServlet

to:

gateway.dsame.agent.0=http://host1:80/portal/RemoteConfigServlet
gateway.dsame.agent.1=http://host2:80/portal/RemoteConfigServlet

You will also need to add the additional hosts to the /opt/SUNWam/lib/AMCOnfig.properties file.

Change:

com.iplanet.am.naming.url=http://host1:80/amserver/namingservice

to:

com.iplanet.am.naming.url=http://host1:80/amserver/namingservice http://host2:80/amserver/namingservice

And:

com.iplanet.am.notification.url=http://host1:80/amserver/notificationservice

to:

com.iplanet.am.notification.url=http://host1:80/amserver/notificationservice http://host2:80/amserver/notificationservice

This change will take effect the next time the Gateway instance is started.

Configuring a List of URL Paths for the Gateway to Ignore

Under certain circumstances, IE can generate spontaneous requests for content. One example is when Microsoft Office is installed and the Disussion bar is enabled in IE. As these requests have not been rewritten, the gateway mistakes them for authentication requests, which can invalidate the user's session. To avoid this, it is now possible to configure the gateway to ignore certain URLpaths, responding to any request for one of these paths with a 404 (File Not Found) response.

The URI ignore list is configured by adding the following entry to the platform.conf.<instance> file located in /etc/opt/SUNWps (Solaris) and restarting the gateway:

gateway.ignoreURIList=<comma separated list of URL paths>

eg. To ignore the requests from IE when Microsoft Office is installed and the Discussion Bar is enabled add:

gateway.ignoreURIList=/MSOffice/cltreq.asp,/_vti_bin/owssvr.dll

Disabling the rewriting of cookie names retrieved through URLScraper channels

In Portal Server 6.2 Patch 7, the handling of cookies retrieved by URLScraper channels was changed. Prior to Patch 7, the cookies were returned to the client with the same name and value as originally set. However, the domain was changed to match the domain of the Portal Server, and the path attribute was changed to / to ensure that the cookie was accepted by the browser. Unfortunately, this meant that if two cookies were set by two seperate URLScraper channels with the same name, one would be overwritten by the other, and lost. It also meant that cookies set in one channel would be returned to all channels on the next refresh, which could represent a security weakness if the desktop contains a mixture of channels sourced internally, which may include sensitive data in the cookies such as a userid, and channels sourced from external context providers, such as Yahoo!.

For this reason cookie handling was changed in Patch 7 such that the names of cookies retrieved by URLScrapers are rewritten before being returned to the client so that they are unique across all channels, thus ensuring that all cookies with the same name are retained. When the Desktop is refreshed, the rewritten cookies are returned to the Portal Server which reverts their names back to their original form before adding them to the request made to refresh the scraped content. In addition, as of Patch 26, cookies that have been rewritten are only returned to the channel that originally set them.

Unfortunately, this rewriting causes problems if it is desirable that clients be able to access back end systems directly using sessions they originally received through a URLScraper channel. For example, the scraped channel may contains links which if clicked open a new window directly to the back end system from which the content was scraped. If the session cookie name for that system has been rewritten by the Portal Server, and the Portal Server is no longer intervening to restore the original cookie name, the back end system will not recognise the session cookie, and the existing session will not be honoured.

For this reason the rewriting of cookie names has now been made optional. Also, if rewriting is disabled, the cookie domain will also not be rewritten, as long as the Portal Server falls under that domain. If the Portal Server does not fall under that domain, the cookie domain must be rewritten for the browser to accept the cookie, in which case it is rewritten to be the Portal Server's DNS domain as before. The cookie path attribute is still always rewritten to / however, to ensure that the cookie is accepted by the browser. Note that with rewriting disabled, all cookies are returned to all channels as before.

To disable the rewriting of cookie names retrieved through URLScraper channels, change the following option in /etc/opt/SUNWps/desktop/desktopconfig.properties as shown below and restart the Portal Server:

rewriteURLScraperCookieNames=false