Release Notes for iPlanet™ Portal Server 3.0 Service Pack 5
Updated July 2003
The Release Notes for iPlanet™ Portal Server, Version 3.0, Service Pack 5 document important information available at the time of release. Installing this product updates the iPlanet Portal Server software to include fixes from Service Pack 1, Service Pack 2, Service Pack 3, Service Pack 3a, and Service Pack 4 and Service Pack 5. The information in this document includes documentation for previous service packs.
These release notes contain the following sections:
- What's New in Service Pack 5
- Previous Service Pack Enhancements
- Known Problems and Limitations
- Bugs Fixed
- Documentation Updates
- How to Report Problems
- Where to Find More Information
Read this document before you begin installing Service Pack 5. For an online version of this and other Portal Server 3.0 documentation, see the iPlanet documentation Web site at:
After you install and start using iPlanet Portal Server 3.0, Service Pack 5, check this Web site periodically to view the most up-to-date documentation.
About This Document
This section provides details about this document. It contains the following topics:
Typographic Conventions
Table 1 is a three column table that describes the typographic conventions used in this release note. The first column describes typeface or symbol, the second column describes the meaning, and the third column provides an example of how the typeface is used.
Sample Machine Names
Table 2 is a two column table that lists the machine names used in code examples and the types of iPlanet Portal Server components to which they correspond. The first column of the table contains machine names, the second column states what component is installed on the machine.
Machine Name
Running as . . .
iPlanet Portal Server not being used as the profile server in multiple server installations
What's New in Service Pack 5
This section summarizes the newest enhancements implemented in Service Pack 5.
- Template Modifications
- Tips for Customizing Templates
- Customizing Desktop Top Level TABLE Attributes
- Maximizing Desktop Channels
- Setting Cookies From A JSPProvider Channel
See the "Desktop and Provider Changes" section of this document for details on these changes.
- Configuring Multiple Gateway Instances
- Using Wildcards In JavaScript Rewriter Rules
- Disabling Client-Side Caching of Redirected Content
- Advanced Rewriter Concepts
See the "Gateway Changes" section of this document for details on these changes.
See the "NetFile Changes" section of this document for details on these changes.
- Automatic Proxy Configuration for Netlet Connections
- Controlling Server Session Timeout When Using the Netlet
See the "Netlet Changes" section of this document for details on these changes.
See the "Performance and Tuning Changes" section of this document for details on these changes.
See the "Profile Service Changes" section of this document for details on these changes.
See the "Documentation Updates" section of this document for details on these changes.
Previous Service Pack Enhancements
This section summarizes the cumulative enhancements implemented in the following previous Service Packs: iPlanet Portal Server 3.0, Service Pack 1, Service Pack 2, and Service Pack 3a, and Service Pack 4.
Authentication Changes
- A new parameter for redirecting users during login and logout is available.
- Users can be required to authenticate against more than one authentication mechanism.
- User default URLs can be set in the pluggable interface, without changing default URLs in user profiles.
- A new Desktop login channel allows users to register and receive personalized pages.
- Anonymous authentication is available.
- A user with a valid session can go directly to a login module without sending a logout URL.
- Users can change their membership login passwords.
- A user's email address can now be used as the user profile ID on the certificate.
- A persistent cookie mode is now available.
See the "Authentication Changes" section of this document for details on these changes.
Desktop and Provider Changes
- A new provider allows JavaServer Pages™ (JSP™) technology to be used to write providers for Desktop channels.
- The template scan interval, the length of time between checking to see whether disk files have been updated, can now be changed in the administration console.
- Tabs for organizing Desktop content are available for the edit page.
- The Provider API allows a channel to return either a complete HTML edit form or a subset of a complete HTML page.
- Administrators can prevent users from changing a channel's position on the Desktop.
- The Desktop can display full-width channels.
- The Desktop can display channels without frames, titles or controls.
- The Login Provider Channel template files now use the POST method when submitting login forms.
- The URL scraper can forward cookies passed in HTTP requests to the Desktop.
- Multiple cookies differing only in path or value can be used.
- Providers can access HTTP request and response headers.
- Session time-out units are now in minutes.
- Desktop applications can be run on Macintosh computers.
See the "Desktop and Provider Changes" section of this document for details on these changes.
Gateway Changes
- Gateway logging is now disabled by default.
- Administrators can set JavaScript™ variables for rewriting.
- Administrators can define JavaScript functions with a single parameter.
- Administrators can define JavaScript functions with multiple parameters.
- Rewrite Applet/Object parameter values can be changed via the administration console.
- Administrators can deny unknown certificates.
- Administrator can specify how many times the gateway should retry socket connections to a destination server.
- Outlook Web Access 2000 applications can now be used with the gateway.
- Some attribute settings are now inactive.
See the "Gateway Changes" section of this document for details on these changes.
Localization Changes
- Multiple locales for a domain are available.
- The user can select locale.
- The user can see changes in the locale of choice.
- A new properties file allows the default Desktop JSP Provider's description and title to be localized.
- A copy of the sample JSP Provider properties file is provided specifically for localizations.
See the "Localization Changes" section of this document for details on these changes.
NetFile Changes
- A generic file path search utility is now available for all data file types.
- Each channel now can identify whether it supports a client type's output format.
See the "NetFile Changes" section of this document for details on these changes.
NetFile Changes
- Improvements in using NetWare File Systems are available.
- Systems and shares can be defined at the domain, role and user level.
- NT hidden shares can be defined using the administration console.
- Shares on Windows NT systems are now alphabetized.
- NetFile usability has been improved.
See the "NetFile Changes" section of this document for details on these changes.
Netlet Changes
- The Netlet now supports an unlimited number of connections per Netlet.
- The Netlet now supports secure remote FTP transfers.
- The Netlet proxy manages communication between the gateway and target servers and offers improved security.
- Messages in Netlet windows can be changed.
- The Netlet applet can be used with Web browsers that are configured to use automatic proxy configuration (PAC) files.
- Internet Explorer can use automatic configuration files for automatic proxy services.
See the "Netlet Changes" section of this document for details on these changes.
Performance and Tuning Changes
- Netscape™ Security Services (NSS) is now supported on the gateway component.
- The Maximum Thread Pool Size parameter can be increased.
- A new method for loading multiple attributes in one profile request is available.
- Short-circuiting for session and logging requests improves performance.
- Adjusting iPlanet™ Web Server parameters can improve performance.
See the "Performance and Tuning Changes" section of this document for details on these changes.
Profile Service Changes
- A separate profile service is now used for each Portal Server instance.
- New methods for getting and setting user properties are available.
See the "Profile Service Changes" section of this document for details on these changes.
Server Changes
- Portal Server can now be run without the gateway.
- Multiple instances of the Portal Server can be run on different ports.
- The server can now access multiple instances of iPlanet Portal Server from a single server installation.
- You can run applications written using iPlanet Portal Server APIs on a server host that is not iPlanet Portal Server.
See the "Server Changes" section of this document for details on these changes.
Third-Party Software Changes
- A new parameter allows NetFile to display ISO8859-1 character sets.
See the "Third-Party Software Changes" section of this document for details on this change.
Webmail Changes
- A workaround to allow Portal Server to display Webmail is now available.
See the "Webmail Changes" section of this document for details on this change.
Authentication Changes
This section provides details about authentication changes in iPlanet Portal Server. It contains the following topics:
- Using the goto Parameter
- Authentication Chaining
- Setting Default URLs
- Login Channel
- Anonymous Authentication
- Extending Authentication
- Changing Membership Login Passwords
- Using an email Address as User Profile ID
- Setting Persistent Cookies
Using the goto Parameter
The goto parameter is now available. It enables applications to instruct authentication to redirect the user to a URL other than the default URL stored in the user profile upon login or logout. It is valid for the current session only, and it does not change the default URL stored in the user profile.
To be redirected to a specific URL, the application must specify the goto parameter in the URL.
The goto parameter allows the calling application to specify where the user is redirected upon successful login.
For example, if an application wanted to redirect the user to my.sesta.com after successful authentication, the URL would be:
http://server1.domain:port/login?goto=http://my.sesta.com
An API developer can use the goto parameter in conjunction with the logout URL to specify where the user should be redirected upon logout.
For example, if an application wanted to redirect the user to sesta.com after logout, the logout link would be:
http://server1.domain:port/logout?goto=http://sesta.com
Authentication Chaining
Authentication chaining can provide a higher level of security for organizations by requiring users to authenticate against more than one authentication mechanism. For example, if the membership and UNIX authentication modules are chained, Desktop users would authenticate against both to access the Desktop.
To set up authentication chaining, complete the following steps:
- Log on to the administration console as super administrator.
- Select Manage Domains.
- Select the domain for which authentication chaining is to be used.
- Select Authentication.
-
In the Authentication Chaining Modules field, enter the authentication modules to be chained, separated by spaces. For example:
- Select the Authentication Enabled check box to enable authentication chaining.
- Select Submit. A message is displayed indicating that the profile was successfully updated.
- Select Continue.
Setting Default URLs
The user's default URL can now be set in the pluggable authentication interface, without changing the default URL in the user's profile. When the user authenticates successfully, the user is redirected to this URL.
A new method called setDefaultURL in the pluggable authentication API allows the authentication modules to set the user's default redirect URL on successful authentication:
To use this, replace the setDefaultURL parameter with the user's default URL. This is an example of setting the default URL to www.sesta.com:
public void setDefaultURL("http://www.sesta.com")
Tip
This method overrides the goto parameter. See "Using the goto Parameter."
Login Channel
Portal Server now contains a membership authentication module that is useful for open portal installations. Combined with anonymous user, unregistered users can view non-personalized content in a portal, and registered users can log in and view personalized content.
The addition of a login channel on the Desktop allows registered users to access the portal, register and receive personalized pages. It allows non-registered users to view static content.
The login channel also allows the user to enable persistent cookies, if the domain allows this option. Persistent cookie support puts user login information into a cookie so that the user does not have to log in for subsequent sessions.
The user interface for the login channel does not have an edit page, as user-editable preferences are not available.
Anonymous Authentication
In a typical anonymous installation, the anonymous authentication module would be the only authentication type enabled. When the URL http://server.domain:port/login/domain is specified, the user's browser displays the anonymous user Desktop. No user input, other than the URL, is required.
A list of user IDs authorized to log in to the anonymous user's Desktop can be specified and modified through the administration console.
When a user ID appears in the List of Anonymous Usernames, access to the anonymous user's Desktop is granted. The session is assigned to the specified userID. When user ID does not appear in the List of Anonymous Usernames, the session is assigned to the user ID specified in the Default Anonymous Username field and the anonymous Desktop is displayed.
Modifying Default Anonymous User Names
To change the default anonymous user name, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link to display the Portal Server Domains page.
- Select the domain to display the Role and Users page.
- Expand the Profiles link and expand the Authentication link.
- From the Authentication menu, select Anonymous.
- Select Show Advanced Options at the bottom of the page.
- In the List of Anonymous User Names, change default value anonymous to the desired user ID.
- Select Submit at the bottom of the page to commit these changes to the profile server.
- On the Profile Successfully Updated page, select Continue.
Setting Default Anonymous User Names
To define the default anonymous user name, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link.
- In the Domain, Role and Users page, expand the Profiles link and expand the Authentication link.
- From the Authentication Menu, select Anonymous.
- Select Show Advanced Options at the bottom of the page.
- In the Default Anonymous User Name field, change the default user ID anonymous to the desired user ID.
- Select Submit at the bottom of the page to commit these changes to the profile server.
- On the Profile Successfully Updated page, select Continue.
Enabling Anonymous Desktop
Use the administration console to enable an anonymous Desktop using the Anonymous Authentication Module and Login Channel.
To enable the anonymous Desktop, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link to display the Portal Server Domains page.
- Select the domain to display the Domain, Role and Users page.
- Expand Profiles link.
- Select Authentication link.
-
From the Authentication Menu, select Anonymous and de-select all other authentication modules.
-
Portal Server is now defaulted to the Anonymous authentication module in all cases and displays the anonymous Desktop by default.
-
- Select Submit at the bottom of the page to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
- Select Show Advanced Options at the bottom of the page.
-
In the Non Interactive Modules, add Membership.
-
This enables users to use the login channel to use Membership authentication instead of having to use the provided membership login page.
-
- Select Enable Persistent Cookie Mode, if persistent cookies are desired.
- Select Submit at the bottom of the page to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
Customizing Anonymous Desktop Templates
You can customize templates for the anonymous Desktop by editing the menubar.html file and changing settings in the administration console.
To customize a user logout from the Desktop redirect to the anonymous user Desktop, complete the following steps:
-
Edit the HREF definition for the Log Out link in the /etc/opt/SUNWips/desktop/default/iwtDesktop/menubar.html file.
Tip Use this format to set the logout from the Desktop to be redirected to the anonymous Desktop in all cases:
To customize the Help page for the anonymous Desktop, complete the following steps:
- Log on to the administration console as super administrator.
- Select the Anonymous User Desktop.
- From the left frame, select the Manage Domains link.
- Select the domain.
- Select Default Role.
- Select Users.
- Select Anonymous.
- Expand Applications.
- Select Desktop.
- Scroll down and select Show Advanced Options.
-
Modify the value for Front Page Help.
-
The default English locale value in Front Page Help is assumed to be relative from the /opt/SUNWips/public_html/docs/en_US/online_help directory.
-
- Select Submit at the bottom of the page to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
Enabling Anonymous Desktop for Other Domains
To create an anonymous user for any other domain, complete the following steps:
-
Use this command to copy the /var/opt/SUNWips/iwtAnonymousUser.xml-orig file to a temporary location (/tmp):
# cp /var/opt/SUNWips/iwtAnonymousUser.xml-orig /tmp/iwtAnonymousUser.xml-orig
-
Change the string INST_DEFAULT_DOMAIN in the /tmp/iwtAnonymousUser.xml-orig file to the name of the other domain:
userConfigurable="true" > <Val>/INST_DEFAULT_DOMAIN/defaultRole</Val> </iwt:Att>
-
Use these commands to load the new anonymous user profile to the primary server service:
# cd /opt/SUNWips/bin
# ipsadmin create user /other_domain/anonymous /tmp/iwtAnonymousUser.xml-orig
-
Use this URL to access the authentication menu for the new domain in the browser:
http://server1.domain:port/login?domain=/other_domain
Disabling Anonymous Desktop
To disable anonymous Desktop, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link to display the Portal Server Domains page.
- Select the domain to display the Domain, Role and Users page.
- Expand Profiles link.
- Select Authentication link.
-
In the Authentication Menu, de-select the Anonymous auth module.
- Select Submit at the bottom of the page to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
Modifying the Login Channel
The login channel can be modified to work with other authentication modules. A sample template is available to illustrate how the login channel can be changed to work with the Unix authentication module, rather than the Membership authentication module.
To enable Unix authentication for the login channel, complete the following steps:
When replacing files to modify the operation of the Desktop, make copies of the files being replaced, first, so that they can be reinstated at any later date.
Note
-
As root, use these commands to make a copy of the display.html file:
# cd /etc/opt/SUNWips/desktop/default/iwtLoginProvider
# mv display.html display_iwtAuthMembership.html
-
Replace the display.html file with /etc/opt/SUNWips/desktop/default/iwtLoginProvider/display_iwtAuthUnix.html.
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link to display the Portal Server Domains page.
- Select the domain to display the Domain, Role and Users page.
- Expand the Profiles link and select the Authentication link.
- Scroll down to and select Show Advanced Options.
- In the Non Interactive Modules field, add Unix.
- Select Submit at the bottom of the page to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
The login channel now uses UNIX authentication.
The template file, display_iwtAuthUnix.html, is an example of how templates could be created to enable other authentication modules for the login channel. The contents of the built-in login page for a given authentication method provide an example of the correct parameters to include in the display.html template.
Extending Authentication
When a registered user authenticates from the anonymous Desktop, Portal Server obtains information about the user and presents the user Desktop from the user profile. When a new user registers from the anonymous Desktop, the user's current session from the anonymous Desktop is destroyed before the auth module in the URL for the user's default Desktop is called.
This allows a user with a valid iPlanet Portal Server session to directly go to a login module without sending a logout URL. For example, a login channel sends the following URL to allow an anonymous user to register with the membership module:
http://server.domain:port/login/Membership?domain=/mydomain&arg=newsession
The arg=newsession parameter instructs the authentication module to destroy the current session before calling the authentication module in the URL.
Previously, if a user wanted to switch from anonymous user to registered user, it was impossible to authenticate the user using another authentication module such as the Membership module since an anonymous user has a valid session.
Changing Membership Login Passwords
Users can now change their membership login passwords.
To change the membership login password, the user must complete the following steps:
- Select the Edit icon from the User Information channel menu.
- Enter the original password and the new password and confirm the new password.
Password checking is subject to the same rules as the membership authentication module. The user must authenticate via Membership for changes to the Membership password.
Using an email Address as User Profile ID
A user's email address can now be used as the user profile ID on the certificate. When the email address is selected, the cert auth module searches for the emailAddr field in the certificate's user subject dn field for the attribute tag emailaddr and uses its value to access the user's profile ID.
The tag emailAddr is stored in the iwtAuthCert.properties file. It can be replaced with a different value, depending on the site or the certificate issuer.
To use the email address as profile ID, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select your domain and select Profiles and Authentication.
- Select Cert from the list.
- Select email address from the What field in cert to use to access user info in profile field.
- Select Submit.
Setting Persistent Cookies
Persistent cookies are now supported. If the persistent cookie mode is enabled, the user:
- Is not required to log in to Portal Server after relaunching the browser
-
Can display the Desktop immediately without logging in
Note If the user explicitly logs out when persistent cookie mode is enabled, logging in is required on the next visit.
To set up persistent cookie mode for an individual user, the user must select the Remember My Username and Password check box using the Login Channel.
Administrators can set a persistent cookie for a domain. To do this, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select your domain and select Profiles and Authentication.
- In the Profile:Auth page, select Show Advanced Options.
- In The Persistent Cookie MaxAge Value text box, specify the maximum age of the cookie in seconds.
- Select the Enable Persistent Cookie Mode check box to enable the persistent cookie mode for users in this domain.
Desktop and Provider Changes
This section provides details about Desktop changes in iPlanet Portal Server. It contains the following topics:
- Template Modifications
- Tips for Customizing Templates
- Customizing Desktop Top Level TABLE Attributes
- JavaServer Pages Provider
- Setting Cookies From A JSPProvider Channel
- Reloading Templates without a Server Restart
- Tabbed Desktop
- Using Form Control
- Maximizing Desktop Channels
- Locking Channel Positions
- Setting Up Full-Width Channels
- Setting Up Frameless Channels
- Default Login Channel Templates Changes
- Forwarding Cookies
- Using Non-iPlanet Portal Server Cookie Management
- Enabling Access to HTTP Requests and Responses
- Setting Session Time-out Units
- Running Desktop Applications on Macintosh Clients
Template Modifications
The patch installer attempts to preserve customized template information and to 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/SUNWips/desktop/default/iwtBookmarkProvider/display.template
/etc/opt/SUNWips/desktop/default/iwtBookmarkProvider/display.template.preSP5.
The backup files are also copied back to their original location upon service pack removal.
To help avoid potential content-related customization problems, refer to the "Tips for Customizing Templates" section of this document.
Table 3 is a three column table that lists the template files, .properties files, xml files, and platform files that are modified by this service pack. The first column of the table contains the template or flatfile names. The second column contains the component with which the template is associated. The third column describes the change to the template.
Tips for Customizing Templates
Because the Portal Server itself is so customizable, you should follow some precautions to ensure that any customizations made to the iPlanet Portal Server product are preserved after a product upgrade. First, set up a customized template directory if you have not already done so. While this directory might be an entire subset of the default template directory, it is advisable to copy over only 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 ensure that customized templates are not accidentally overwritten when the default templates are modified.
Creating a Customized Template Directory
- Create a directory at the same level as the /etc/opt/SUNWips/desktop/default/ directory with a new name such as mytemplates. In that directory, put only copies of the templates you need to modify. The other templates will be retrieved from the default directory.
- Edit the templates in the mytemplates directory according to your own preference. Refer to the "Desktop Template and Tag Index" section of this document for additional template-related information.
- Log into the administration console.
- Select Manage Domains.
- Select the domain you want to administer.
- Go to Applications | Desktop.
- In the Display/Layout section, change the value of the Template Directory field to match the name of the directory you just created—for example, mytemplates.
- Click Submit at the bottom of the page.
In general, 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 iwtNetletProvider/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 (install_dir/SUNWips/locale/iwtNetletServlet.properties). This is because the product might have a functional change that would overwrite a customization done specifically to that particular template file. This example also exhibits why it is important to keep only customized files in the customized template directory.
For instance, in the iPlanet Portal Server Service Pack 3 product, the Netlet launching behavior changed. Therefore, for customers who use the Netlet, and upgraded from the iPlanet Portal Server Service Pack 2 product to iPlanet Portal Server Service Pack 3, and have an entire copy of the default template directory, the functional change was not propagated to the customized template directory.
The following sections contain instructions for some simple template modifications that may help you get you started with your new customized template directory.
Customizing the Channel Border Look
To modify the look of all the channels (for example, where the buttons are and how the border looks) do the following:
- Edit the file /etc/opt/SUNWips/desktop/mytemplates/iwtDesktop/providerWrapper.html
-
Edit the file
- Logout of the Desktop and then log back in again.
Changing the Desktop Background Colors, Images, and Product Name
-
Edit the file /etc/opt/SUNWips/desktop/mytemplates/banner.html to:
- Point to different graphics files with your company name or logo.
-
Change the background color and layout to match that of your portal's look.
-
If you change the red background color in banner.html, you should also change the background color in the following files wherever the HTML tag attribute BGCOLOR appears:
- contentTemplate.html
- layout1Template.html
- layout2Template.html
- layout3Template.html
- layout4Template.html
- minimized.html
- optionsTemplate.html
-
providerWrapper.html
-
If you want to change the iPlanet Portal Server 3.0 product name that appears on the Desktop in the menubar, you must remove the tag [tag:productName] that appears in the following files and replace it with the text you prefer. The files are:
- banner.html
- contentTemplate.html
- editTemplate.html
- errorTemplate.html
- layout1Template.html
- layout2Template.html
- layout3Template.html
- layout4Template.html
- menubar.html
- optionsTemplate.html
- popupMenubar.html
- popupTemplate.html
-
userTemplate.html
-
This text can be changed in the profile store, but it is system-wide and not specific to any one domain. To change the value system-wide, do the following:
-
From the profile server command line, as root type:
- Edit the file and delete all the attributes except for iwtPlatform-productName. Change the attribute value between the <Val></Val> tags to be the value you want-- most likely the title of your company portal. Save that file with just that attribute in it.
-
From the command line, enter the following:
-
Remove the iwtSampleRSS and iwtIPInfo channels. These channels both contain iPlanet information, so they can be removed from the installation by removing them from the available providers.
-
These channels are sourced from the RSS Provider and URL Scraper providers, respectively, and are examples of how the iPlanet Portal Server can pull content from other sources. The iwtIPInfo channel is simply an HTML page and a GIF file displayed by the URLScraper. The iwtSampleRSS channel is an RDF file with an accompanying GIF file. You can set up channels like this quickly for your own portal by using the Channel Wizard in the iPlanet Portal Server Administration Console.
-
- Restart the server for any changes you have made to take effect
Changing the Channel Buttons:
The links and image tags for the channel buttons are generated dynamically by the Desktop, but the actual image file sources are taken from the Desktop properties file. To change the button images, do the following:
-
Edit the file /opt/SUNWips/locale/iwtDesktop.properties and change the properties entries:
- ProviderCommands-helpIcon
- ProviderCommands-minimizeIcon
- ProviderCommands-maximizeIcon
- ProviderCommands-editIcon
- ProviderCommands-removeIcon
-
ProviderCommands-attachIcon—all relative to install_dir/SUNWips/public_html/
-
Edit the following entries in the same .properties file as above to change the ALT text for the IMG tags in the channel buttons.
Using Images for Channel Titles
-
In the providerWrapper.html file, replace [tag:title] with the following:
-
In the <HEAD> section of the userTemplate.html file, insert the following:
<script> function drawTitle(title) { if (title == 'special title') { document.write('<img src=/images/specialtitle.gif>'); } else { document.write(title); } } </script>
Changing The Link Color in The Desktop
Edit the following line in userTemplate.html to change link colors for the page:
Desktop Template and Tag Index
Table 4 is two column table that contains a list of templates and tag descriptions. The first column lists the template name. The second column provides a tag description.
Customizing Desktop Top Level TABLE Attributes
The top level TABLE attribute definitions have been moved from being emitted directly by the FrontProvider Servlet to the userTemplate Desktop template file. All customized template directories under /etc/opt/SUNWips/desktop/ that contain an iwtDesktop/userTemplate.html file will be modified automatically by the installer to include the default TABLE attributes which were already being set by the FrontProvider.
As a result, the attributes can now be modified to provide more flexible control over the look and feel of the entire iPlanet Portal Server Desktop in addition to providing a means to use Cascading Style Sheets for themes, or JavaScript to change the TABLE attributes dynamically.
If the content tag ([tag:content]) was already removed from the userTemplate.html file prior to the service pack installation, the template will need to be updated manually in order for the portal contents to be displayed correctly.
Just below the inlineError tag ([tag:inlineError]) of each customized userTemplate.html file, add the following:
Maximizing Desktop Channels
Individual channels on the iPlanet Portal Server Desktop can now be maximized. Maximizing a channel means that it is displayed on entire Desktop space between the horizontal menu bars. When a channel has been maximized, the banner and the menu bars are still visible.
If a channel is edited in the maximized state, its previous size will be restored once the edit is completed. Additionally, if the provider is detached while maximized, it will be re-attached in a restored state.This feature is also extended by adding the ability to tag-swap the providerName tag ([tag:providerName]) in the provider Desktop templates.
In order to maximize a provider channel, a URL should be constructed so that the channel's name appears at the end of the query string. The following is an example of a relative URL for a stocks channel:
/DesktopServlet?action=content&provider=iwtMaximizeProvider&targetprovider=stocks
Selecting this link from anywhere on the Desktop or explicitly setting it in the URL field of the web browser, after being fully qualified, will result in the stocks channel being maximized.
This maximize feature differs from the maximize functionality already built in to the Desktop as a provider command. When a provider has been minimized, the menu bar for the provider will contain a maximize button. Maximize, in this instance, will merely restore the provider to its original position and size on the Portal Desktop.
One example of how to use this new feature on the Desktop would be to create the maximize URL dynamically using the tag-swapping capability of the iPlanet Portal Server from within the providerWrapper.html template. The provider commands available are determined based on the policy for that provider and user. However, a maximize button could be inserted just prior to the provider_cmds tag so each provider could be independently maximized.
In this example, default Desktop images were used for two additional buttons—one to maximize the provider, and one to restore it to its original size. To avoid potential confusion for the end users, these buttons should be made unique if the providers will be allowed to minimize or detach.
Both the providerWrapper.html and userTemplate.html files could be changed to have only one image which would represent the current state of the provider (maximized or restored).
Add the following to the HEAD element of the userTemplate.html file:
Edit the providerWrapper.html template to look like the following:
The preceeding example uses JavaScript to determine whether the provider is maximized or not and to dynamically update the button and corresponding URL.
The Netscape Navigator™ 4.x browser does not correctly update the ALT text of the image object. For example, the ALT text for the restore button will say "maximize."
Note
This example demonstrates how the provider maximization feature might be generally applied to the Desktop. Many other applications are possible. If Secure Remote Access Pack has been installed, verify that any reference to the maximize or restore URLs are rewritten correctly.
JavaServer Pages Provider
The JSP Provider allows you to use JavaServer Pages technology to write providers for Desktop channels. JSP Provider-based channels have the following attributes in addition to the attributes of other channels:
- contentPage - the JavaServer Page specification used to generate the HTML content for the channel through the provider's getContent method. The generated HTML must contain only those tags that are appropriate for display within a channel.
- editPage - the JavaServer Page specification used to generate the internal content for the edit form through the provider's getContent method displayed when the user selects the channel's Edit function. This page is optional, and if it is not specified, the isEditable method for the provider returns false.
- processPage - the JavaServer Page specification used to process the results of an edit page using the processEdit method.
The contentPage and editPage JSP specifications can be used in various combinations. For example, you can use a JSP specification to generate content while you can use Java™ code in the provider class to generate the edit page. Both have access to iPlanet Portal Server platform services.
Processing of the edit form consists of Java code that checks validity of the form entry and updates user preferences for the channel. The result is a display of the Desktop in the case of success or a display of the edit page in the case of a failure, possibly with some error information for the user.
To handle the processing of an edit form, the JSP-based provider has these options:
- Defining a processPage JSP. If defined, this JSP is invoked via a POST request and the JSP processes the results, either using a script or a bean or other Java class. The JSP must produce a redirect in the response. This redirect then becomes the return value for the provider's processEdit method.
- Extending the JSPProvider class and implementing the processEdit method. The processPage attribute is left blank.
Support for JSP-based channels is provided through a class called JSPProvider. The JSPProvider extends the ProfileProviderAdapter class to support other attributes for the channel by using the profile service.
When specifying a JSP in one of the JSP attributes, the path name is interpreted relative to the Desktop template directory using the same algorithm as for other Desktop templates, including the locale setting.
If the user's locale is de_DE, the Desktop type is SunBlue, and a JSP attribute is set to myChan/chan.jsp, the system would search for these JSP files:
/etc/opt/SUNWips/desktop/SunBlue_de_DE/myChan/chan.jsp
/etc/opt/SUNWips/desktop/SunBlue_de_DE/chan.jsp
/etc/opt/SUNWips/desktop/SunBlue/myChan/chan.jsp
/etc/opt/SUNWips/desktop/SunBlue/chan.jsp
/etc/opt/SUNWips/desktop/default_de_DE/myChan/chan.jsp
/etc/opt/SUNWips/desktop/default_de_DE/chan.jsp
/etc/opt/SUNWips/desktop/default/myChan/chan.jsp
/etc/opt/SUNWips/desktop/default/chan.jsp
For more information on implementing JSP-based channels, see the Javadoc™ software shipped with Service Pack 5.
Tip
Setting Cookies From A JSPProvider Channel
Cookies can now be set from JSP provider channels using response.addCookie(cookie_name) to amend the Set-Cookie response from the Desktop Servlet. For example, a personal cookie-based counter could be added to the out-of-box samplecontent.jsp by adding the following code to /etc/opt/SUNWips/desktop/desktop_name/samplecontent.jsp:
When the default JSP provider channel is accessed, a cookie will now be set and the provider will indicate the cookie value plus one which represents the current number of visits to the page.
Reloading Templates without a Server Restart
When the Desktop accesses templates to generate content, it reads them from disk and caches them. All subsequent requests for the template are served from the cache.
The Desktop periodically checks to see if the disk files have been updated. If the disk file is newer than the cache, the template is re-cached based on the updated disk file.
The length of time between checking to see if the disk files have been updated is the template scan interval. This interval can now be changed in the administration console. Changing the template scan interval causes the Desktop to immediately check for changes to the disk files and then wait for the new interval value before re-checking again.
To change the template scan interval, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Management Platform Settings link.
- Expand the Applications link.
- Select the Desktop link.
-
In the Component Profile: Desktop page, edit the Template Scan Interval Field.
Tip The default value for the template scan interval is 900 seconds, or 15 minutes.
- Select the Submit button, at the bottom of the page, and save the changes.
- Select the Continue button on the Profile Successfully Updated page.
Tabbed Desktop
The Desktop can now use tabs to organize content. Tabbed Desktop pages can be individually modified to customize the Desktop.
The tab feature must be turned on for any given domain. By default, it is not active. The super administrator must enable the Tab Provider and then configure or remove tabs in a chosen domain.
Configuring the Tab Desktop
To enable Desktop tabs in a particular domain, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Manage Domains link.
- Select a domain.
- Expand the Applications link in the right frame.
- Select the Desktop link.
- At the bottom of the Profile: Desktop page, select Show Advanced Options.
- In the Profile: Desktop page, scroll down to the Channels Field.
-
If the iwtTabProvider is shown in the Available Channels list, complete the following steps:
- Highlight iwtTabProvider in the Available Channels list.
-
Select the arrow to move iwtTabProvider to the Selected Channels field.
-
If the iwtTabProvider is not shown in the Available Channels list, then complete the following steps:
- In the New Channel Name window, enter a new channel name, iwtTabProvider.
-
In the Provider Class Name field, enter a new provider class:
- In the Available Channels list, select Add to display iwtTabProvider in the Available Channels list.
- In the Available Channels list, highlight iwtTabProvider.
-
Select the arrow to move iwtTabProvider to the Selected Channels field.
-
Scroll down the page and confirm that the Active Channel List Module contains a Tab Channel List entry. The Tab Channel List Module must be selected. For example:
-
In the Start Tab field, enter a tab name. The first tab default name is My Front Page.
-
In the Available Tabs field, edit the default tab conditions that the tab contains. Change the name, providers, and description to create a custom tab. For example:
-
name=new tab|channels=iwtTabProvider;iwtUserInfoProvider;
iwtIPInfoProvider;iwtSampleRss|desc=new tab description|
removable=true|renamable=true
-
- In the Tab Pattern field, enter the name of a tab content template, and the providers to be included.
-
In the Make From Scratch Tab field, enter a suitable heading and all content providers that appear on the Edit Tab Provider page. For example:
-
name=Make From Scratch ...|channels=iwtTabProvider;iwtUserInfoProvider;
iwtBookmarkProvider;iwtIPInfoProvider|desc=Design a tab from the ground up|
removable=true|renamable=true
-
-
In the Maximum Number of Tabs field, provide the total number of tabs that can be on the Desktop.
- Select Submit to save the changes.
- On the Profile Successfully Updated page, select Continue.
Configuring the Tab Provider on the Desktop
Users can configure the tabs on their Desktops. The tab's channel edit page allows users to create, rename, or remove tabs from their Desktops. In addition, users can select which tab should be present on the initial Desktop page.
To configure tabs, the user must complete the following steps:
In the Edit Tab Provider page, the user can use a predefined tab content template by topic, or by choosing each channel for the new tab manually.
Creating Customized Tabs
To create custom tabs, the user must complete the following steps:
- In the Edit Tab Provider page's Tab Name field, enter the name of the tab being created.
- In the Tab Topics field, select Make From Scratch.
- Select Finished at the bottom of the page.
-
In the Channels page, select the channels to display on the Desktop.
Tip During configuration of Desktop pages and layout, the administrator uses the administration console to determine which channels are thin and thick.
- Select Finished at the bottom of the page to return to the Desktop.
Creating Default Content Tabs
To create a default content for a tab, the user must complete the following steps:
- In the Edit Tab Provider's Tab Name field, enter the name of the tab being created.
- In the Tab Topics field, select a pre-made Tab Content Provider.
- Select Finished at the bottom of the page to return to the Desktop.
Aligning Tabs
Desktop tabs can now be aligned from the left side or the right side of the Desktop. By default, tabs are left-aligned.
To use tabs, the super administrator must enable the Tab Provider and then configure or remove tabs in a selected domain.
To change to right-to-left ordering of Desktop tabs, complete the following steps:
- Log in to the administration console.
- Select Manage Domains.
- Select the domain for which you want to apply the changes.
- Select the key next to Applications to expand the Application list.
- Select Desktop to display the Profile: Desktop page.
- From the Available Channels list, select iwtTabProvider.
- Select Edit Channel to display the Profile: Tab Provider page.
- Select Show Advanced Options at the bottom of the page.
- Put a check mark in the check box labeled RTL Presentation.
- Select Submit.
- Select Continue when the console displays the Profile was successfully updated message.
Using Form Control
The Provider API now allows a channel to return either a complete HTML edit form, or a subset of a complete HTML page in response to a request for the edit page.
Provider API
Integer constants are added to the Provider interface that return values from the getEditType() method. These integer constants define the form type, return type, from the getEditType() method:
New methods query and set the form type.
The Desktop uses the getEditType() method so that it knows to expect either a complete or subset HTML form to be returned when calling channel.getEdit().
These restrictions apply to what can be returned from getEdit() when the edit type is equal to EDIT_COMPLETE:
- This method returns a complete, valid, HTML form.
- The form is an encoding type of application/x-www-form-urlencoded.
- The form must contain the correct parameters for instructing the Desktop to process the page, as defined in editTemplate.html.
-
The following parameters must be present in the submitted form:
- The form action must be /DesktopServlet. When returning a complete HTML form, a channel must submit valid actions to the Desktop as defined in the Desktop URL Javadoc software.
Provider Attributes
For channels that extend the ProfileProviderAdapter class, a new attribute can be defined in the profile component:
The default value is different for each provider. Variations to this might include turning off write permission for OWNER, if one or the other edit type was not implemented.
All iPlanet Portal Server default channels return Provider.EDIT_SUBSET. Modifying the -editType attribute causes a malfunction. A new channel must return Provider.EDIT_SUBSET, or Provider.EDIT_COMPLETE depending on how the getEdit() method is implemented.
Locking Channel Positions
Administrators can now lock a channel's position so that the user cannot change its position or remove it from the Desktop. The purpose is to force the user to see particular content.
The Layout page that allows the user to arrange channels on the Desktop does not list locked channels.
To lock a channel's position, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select the domain and select Profiles and Policy.
-
Deselect the Movable check box for the channel to lock the channel's position.
Tip If you select the Movable check box, the user can move channels around in the Desktop.
-
Deselect the Removable check box, so that the channel cannot be removed from the Desktop.
Tip If you select the Removable check box, the user can remove channels from the Desktop.
- Select Submit.
To unlock a channel's position, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select the domain and select Profiles and Policy.
-
Select the Movable check box for the channel to unlock the channel's position.
Tip If you select the Movable check box, the user can move channels around in the Desktop.
-
Select the Removable check box so the channel can be removed from the Desktop.
Tip If you select the Removable check box, the user can remove channels from the Desktop.
- Select Submit.
Setting Up Full-Width Channels
The Portal Server Desktop can now display full-width channels. A full-width channel spans the width of the Desktop, either at the top or bottom.
To configure a full-width channel, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select your domain and select Applications and Desktop.
- Select the channel to modify and select Edit Channel.
- Select Show Advanced Options.
- Modify Width to either full_top or full_bottom.
- Select Submit.
Setting Up Frameless Channels
The Portal Server Desktop can now display unframed channels. A frameless channel is one that is displayed without a title, controls, and a border or frame.
To configure a frameless channel, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select your domain and select Applications and Desktop.
- From the list of available channels, select the channel you want to present without a border.
- Select Edit Channel and select Show Advanced Options.
-
Deselect the Framed? check box if it is selected.
Tip If the Framed? check box is selected, the channel is displayed with a title, controls, and border.
-
Select Submit.
Note To modify just the border of the channel, edit the hasBorder attribute in the Policy page.
Default Login Channel Templates Changes
The Login Provider Channel template files now use the POST method for improved security when submitting the login forms. This change provides the choice of using the POST or GET methods in customized login channels.
Using the POST method is more secure because it prevents the password from showing up in the server logs, URLs and bookmarks.
Forwarding Cookies
The URL scraper can now forward cookies passed in the HTTP request to the Desktop. That is, the URL scraper sends cookies when it makes a connection to the target site to retrieve the content it is scraping. The URL scraper also sends set-cookie requests to the browser. That is, it gets all cookies from set-cookie headers and adds them to the HTTP response to the client browser.
By default, no cookies are forwarded. For the affected domain, role or user, the administrator must use the administration console to set the list of cookies to forward.
To forward cookies, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select your domain and select Profiles and Policy.
-
Change the entries in the allow and deny lists for the Cookies To Forward privilege for the channel.
Using Non-iPlanet Portal Server Cookie Management
Multiple cookies containing the same name and the same path can be stored, as long as the domain is not explicitly set to the same value. By default, the domain value is the fully qualified hostname of the server that originally set the cookie.
- Log in to the iPlanet Portal Server administration console.
- Select Gateway Management.
- Select Manage Gateway Profile.
- Select the Non Portal Server Cookie Management check box.
If the cookie is in a different domain from the server (for example, if scraping a page to the iPlanet Portal Server Desktop that sets its own cookie), complete the following steps:
- Add that cookie to the Forward Cookie URL List.
- Select Submit.
- Select Continue when the console displays the message Profile was successfully updated.
- Select Server Management.
- Select Manage Server Profile.
-
Add the cookie domain name to the Cookie Domain List and select Add.
Tip Use this format to add the domain name:
Note the . that precedes the name.
- Select Submit.
- Select Continue when the console displays the Profile was successfully updated message
- Log out of the administration console and restart the server and gateway.
If the cookie is set from the same domain as the server, complete the following steps:
- Select Submit.
- Select Continue when the console displays the Profile was successfully updated message
- Log out of the administration console and restart the server and gateway.
Enabling Access to HTTP Requests and Responses
Providers can now access HTTP request and response headers. This change is desirable for single sign-on, setting cookies, getting parameters from the HTTP headers, and for inserting data into the headers.
Three new methods in the Content Provider interface are available to provide this. The methods are:
- public StringBuffer getContent(HttpServletRequest req, HttpServletResponse res);
- public StringBuffer getEdit(HttpServletRequest req, HttpServletResponse res);
- public URL processEdit(HttpServletRequest req, HttpServletResponse res);
These methods in the ProviderAdapter and ProfileProviderAdapter classes call the getContent, getEdit, and processEdit methods.
Table 5 is a two column table that lists the indicated methods for the HttpServletRequest and HttpServletResponses objects. The first column lists the method name and the second column lists the return values.
getSession(boolean)
Null
Setting Session Time-out Units
The session time out unit of measurement is now in minutes.
To set the session time-out to the maximum possible value, complete the following steps:
- Log on to the administration console as super administrator.
- Select Manage Domains.
- Select the name of the desired domain.
- Select Session under Profiles.
- Make value of Maximum Idle Time to the maximum value of: 153722867280912930.
- Make value of Maximum Session Time to the maximum value of: 153722867280912930.
- Select Submit.
Running Desktop Applications on Macintosh Clients
NetFile and NetMail applications now work on a Macintosh similarly to the way they work on other supported platforms.
The Netlet application, when used on a Macintosh, however, does not support the dynamic loading feature. If the Netlet is enabled, Macintosh clients automatically load the Netlet when the Netlet Channel is enabled on the Desktop.
Table 6 is a two column table that lists the minimum system requirements for running the Netlet, NetMail, and NetFile applications on Macintosh clients. The first column contains the system component name, and the second column describes the minimum requirements for that component.
Component
Description
Gateway Changes
This section provides details about gateway changes in iPlanet Portal Server. It contains the following topics:
- Configuring Multiple Gateway Instances
- Using Wildcards In JavaScript Rewriter Rules
- Disabling Client-Side Caching of Redirected Content
- Advanced Rewriter Concepts
- Gateway Logging
- Rewriting JavaScript Variables in JavaScript
- Rewriting JavaScript Functions with a Single Parameter
- Rewriting Javascript Functions with Multiple Parameters
- Editing Rewrite Applet/Object Parameter Values
- Denying Unknown Certificate Authorities
- Setting the Number of Socket Connection Retries
- Using Outlook Web Access 2000
- Inactive Attributes
Configuring Multiple Gateway Instances
It is now possible to configure multiple gateway instances on a single system, with the following caveats:
- All instances on a single system must be associated with the same profile and platform server instances.
- Each gateway instance needs a unique IP address to bind to, with a hostname in DNS.
- All gateway instances associated with the same profile server instance must listen on the same port, for example, 443, and use the same protocol, for example, HTTPS.
Updated Command Options
The ipsgateway script in install_base/SUNWips/bin now supports several new options. Table 7 is a two column table that describes the new ipsgateway command options. The first column contains the command, and the second column provides a description of the new command.
The following examples assume that the commands are being run from the directory in which they reside.
Command
Description
Adds a new gateway instance listening on fully_qualified_instance_name
Deletes the instance listening on fully_qualified_instance_name
In addition, the following commands in install_base/SUNWips/bin now accept an optional instance name argument to specify the instance to target:
- ipsgateway start [fully_qualified_instance_name]
- ipsgateway stop [fully_qualified_instance_name]
- ipsgateway watchdog on|off [fully_qualified_instance_name]
- certadmin [fully_qualified_instance_name]
- checkipsgw [fully_qualified_instance_name]
The instance created at install time is considered the default instance, and is addressed using the above commands with no hostname argument. The default instance cannot be deleted.
There is also a copy of the ipsgateway script in the /etc/init.d directory.
The gateway instance name must be the fully qualified hostname in DNS for the IP address to which this instance will bind.
Note
Creating Multiple Gateway Instances
You can create multiple instances of the iPlanet Portal Server gateway, after you install the iPlanet Portal Server gateway.
Unless you have a multi-homed system and wish to have individual gateway instances for each physical interface, you will need to configure a virtual interface for each gateway instance to bind to. For more information on configuring virtual interfaces, refer to InfoDoc 15659 at http://www.sunsolve.sun.com.
By default, the minimum and maximum JVM heapsize value for the default instance is 512Mb and 768Mb respectively, and for additional instances is 256Mb and 384Mb respectively. If you configure a large number of instances, you may want to change these values in the ipsgateway script, to avoid exhausting physical memory.
To create a new gateway instance, perform the following steps.
- Configure a virtual interface for the new IP address. Refer to InfoDoc 15659.
-
Add a forward and reverse entry in DNS for this IP address. When creating a new gateway instance, use the fully qualified hostname that you gave this IP address in DNS as the instance name.
-
After the iPlanet Portal Server gateway has been installed, and the appropriate interfaces are established, do the following to create a new gateway instance:
-
-
As root enter the following commands:
# cd /opt/SUNWips/bin
# ipsgateway create fully_qualified_instance_name
-
When prompted, answer the questions.
After creating the instance, do the following to add the instance name and default portal domain for that instance:
-
Add the new gateway instance name to the Platform Gateway list.
- Log on to the administration console as super administrator.
- From the left frame select the Sever Management link.
- Select Manage Server Profile.
-
Add the new gateway instances to the Gateway List. For example,
-
Add the default portal domain for that instance.
Alternatively, use the ipsadmin command line utility to:
- Update the Platform Gateway list by retrieving the iwtPlatform component profile.
- Edit the iwtPlatform-gateways attribute, and update the Domain URLs list by retrieving the domain profile and editing the iwtAuth-domainURL attribute.
Using Wildcards In JavaScript Rewriter Rules
The JavaScript rewriting ability has been extended to include the ability to use wildcards for rules that can be added to the Rewrite JavaScript Variables in the URLs section of the Gateway Profile. This helps reduce the number of similar rules necessary to represent the same basic JavaScript content. It also allows the creation of rules to represent complex JavaScript content that makes proficient use of the JavaScript object model where arrays are used to access data values.
Previously, if the content looked like:
document.all["IMG"+img].src = "../../images/"
The only solution would be to change the code in a manner similar to the following:
up2dir = "../../" document.all["IMG"+img].src = up2dir+"images/"
and add up2dir to the Rewrite JavaScript Variables In URLs section of the Gateway Profile.
It is now possible to define a rule such as document.all*.src in the same section of the iPlanet Portal Server Gateway Profile.
Disabling Client-Side Caching of Redirected Content
A new entry has been added to the /etc/opt/SUNWips/platform.conf file called allow.client.caching. This controls the caching behavior of non-Desktop content redirected through the gateway.
Setting allow.client.caching value to false will result in a pragma:no-cache header being set for any content retrieved by the gateway. This ensures that no Portal content accessed by remote users will be cached on their local machine, regardless of their individual browser caching options if they are using at least an HTTP 1.0 compliant browser.
For example, if the iPlanet Portal Server has been deployed to take advantage of its authentication and secure remote access features, but not the Desktop itself, setting allow.client.caching to false will prevent whatever content is redirected after successful authentication from being cached on the user's local machine.
Limitations and Considerations
Setting allow.client.caching to false, will dramatically increase the load on the gateway component. Caching itself exists to eliminate unnecessary server requests for static content. However, in a secure environment, the performance ramifications of not allowing client caching of content may be outweighed by the added security of content not being permanently, even temporarily, stored on a remote machine. This might be the case when a remote employee is accessing sensitive corporate intellectual property from a public Internet kiosk.
Additionally, a Microsoft Internet Explorer 5.x limitation exists in which helper applications cannot load encrypted data with associated MIME types not handled internally by the browser if a "no-caching" header is set. The same is true for saving encrypted files to a different location on disk.
Internet Explorer has its own functionality for preventing the permanent caching of SSL pages. This functionality can be configured using an advanced browser setting called "Do Not Save Encrypted Pages To Disk." When this option is not enabled, Internet Explorer first decrypts the SSL data, then caches it in the clear prior to handing the decrypted copy to a helper application like Word for .doc files. This functionality is not related to the iPlanet Portal Server itself, since it affects users accessing any SSL-enabled web server in the same way. When the "Do Not Save Encrypted Pages To Disk" option is enabled, the behavior appears to be exactly the same, except the browser cleans up after itself by removing the decrypted data from the cache directory once it is handed off to the helper application.
Therefore, the iPlanet Portal Server allow.client.caching option should not be set to false if Internet Explorer will be a supported client by the deployed portal, with end users downloading or saving files locally that are not registered to be handled internally by the browser itself.
Caching Alternatives
Many secure portal deployments need to work around the browser no-cache header limitation for SSL pages. Working around the browser no-cache header can be difficult if the browsers are not under corporate IT control. If the browsers are under IT control however, a custom Internet Explorer browser can be built using the Internet Explorer Administrator Kit (IEAK).
With the IEAK, the advanced browser option "Do Not Save Encrypted Pages to Disk" can be locked down in an enabled state. If the iPlanet Portal Server gateway is running https, no pages accessed by the client will be cached. This essentially works around the limitation of encrypted pages having to be decrypted and cached prior to being passed to a helper application. Such is the case when this browser option is not enabled. With the default iPlanet Portal Server platform.conf entry allow.client.caching set to true, Internet Explorer browsers can access any pages through the gateway regardless of whether they need helper applications to launch without caching any data.
To limit access and possible caching by other browsers, logic can be added to /etc/opt/SUNWips/auth/[your_template_dir]/login_template.html that disallows their login, and possibly usage.
Alternately, multiple gateways may be used with a redirector in front basing its decision on the userAgent. This would enable allow.client.caching to be set to false on one iPlanet Portal Server gateway accessed by Netscape clients and set to true on a different gateway accessed by Internet Explorer clients (customized using IEAK or with a downloaded activeX plugin that would enforce the "Do Not Save Encrypted Pages To Disk" option enabled). Because SRAP licenses are based on the number of users instead of CPUs, having multiple gateway hardware boxes will not affect software costs for the same number of users.
Using the same psuedo-code as above for an Internet Explorer-only solution, the multi-browser solution might look as follows:
Advanced Rewriter Concepts
Two new Gateway Profile sections have been added. They are advanced configuration options and should be used only as a last resort for difficult rewriting problems that have no other workaround.
- Rewriting JavaScript Function Parameters in Fractured HTML
- Rewriting JavaScript Function Parameters Which Appear as JavaScript Or as A URL
To access these new Gateway Profile sections:
- Log in to the Administration Console.
- Select Gateway Management.
- Select Manage Gateway Profile.
-
Scroll to the bottom of the frame and select Show Advanced Options.
Rewriting JavaScript Function Parameters in Fractured HTML
This Gateway Profile section is suitable for search, rewrite, and replace applications where JavaScript language dynamically creates HTML through multiple document.write function calls. For example:
In this particular case, the FORM tag is broken up by multiple document.writeln() function calls, and the rewriter is unable to determine that ACTION is an HTML tag attribute of the FORM tag. In order to rewrite correctly, the URL pattern ../servlet/ needs to be added to the Rewrite JavaScript Function Parameters in Fractured HTML section of the Gateway Profile.
Rewriting JavaScript Function Parameters Which Appear as JavaScript Or as A URL
Some JavaScript functions do not differentiate the context of what can be passed to the function as a parameter. This additional Gateway Profile section allows for some ambiguity in rewriting JavaScript function parameters. Specifically, this new Gateway Profile section allows the rewriting of JavaScript function parameters that are themselves either JavaScript or a URL. For example:
In this example, a function target has been created whose second function parameter can either be a URL or a JavaScript statement. To rewrite this correctly, Target:,y would be added to Rewrite JavaScript Function Parameters in JavaScript or a URL, instead of Rewrite JavaScript Function Parameters.
Redirecting URLs That Are Relative to the Server Root
URLs that are relative to the server root are resolved using the browser's URL field or may be constructed by using built-in scripting methods created from the browser's URL field. If the request to fetch the URL contains a Referer header (such as requests for embeded images) a redirection will be created so that the browser asks for the correct, rewritten, fully qualified URL.
If no Referer header exists, a 404 not found HTTP error will be returned instead. For example, the following message will be thrown in iwtGateway logs:
By turning on message level logging and testing the gateway access to internal content with Service Pack 5, it may now be possible to use the logs as a self-help mechanism for finding things that should be added to the Gateway profile.
Gateway Logging
Gateway logging is now disabled by default because logging traffic between the gateway and the server can affect portal performance.
Administrators can use the administration console to enable gateway logging.
To enable gateway logging, complete the following steps:
In the following instructions and examples, /opt is the default installation directory.
Note
- Log on to the administration console as super administrator.
- From the left frame, select the Gateway Management link.
- In the right frame, select the Manage Gateway Profile link to display the Component Profile: Gateway page.
- At the bottom of the page, select Show Advanced Options.
- Select the Logging Enabled check box.
- Select Submit.
- Select Continue when the console displays the Profile was successfully updated message.
-
Use these commands to stop and restart the gateway:
# /opt/SUNWips/bin/ipsgateway stop
# /opt/SUNWips/bin/ipsgateway start
Rewriting JavaScript Variables in JavaScript
The entries in this list are the names of the JavaScript variables which are in turn expressed in JavaScript, and which is rewritten by the gateway.
The iPlanet Portal Server administration console's Gateway Profile page contains the Rewrite JavaScript Variables in JavaScript list.
If the list has the following entries:
The gateway tries to rewrite the right-hand sides of both jsvarjs1 and jsvarjs2.
- If there is an entry var1 in Rewrite JavaScript Variables in URL, then url1 is rewritten.
- If there is an entry func2:y in Rewrite JavaScript Function Parameters list, then url2 is rewritten.
Rewriting JavaScript Functions with a Single Parameter
The gateway wraps the matched parameters with a function called iplanet, which does the actual rewriting when the browser interprets the page.
The iPlanet Portal Server administration console's Gateway Profile page contains the Rewrite JavaScript Function Parameters Function list. This is the syntax for entries in this list:
java_script_function_name: [y|], [y|], ...
Example
Rewriting Javascript Functions with Multiple Parameters
The gateway rewrites JavaScript variables or JavaScript functions according to existing rules specific to that variable, or function, in the gateway profile.
The gateway tries to rewrite the matched parameters. A matched parameter in JavaScript is either in the form of a JavaScript variable or a JavaScript function.
The iPlanet Portal Server administration console's Gateway Profile page contains the Rewrite JavaScript Function Parameters list. Each entry in the list has the following syntax:
java_script_function_name: [y|], [y|], ...
The gateway tries to rewrite func2 and var3.
- If there is an entry var3 in Rewrite JavaScript Variables in URLs, then url3 is rewritten.
- If there is an entry func2:y in Rewrite JavaScript Function Parameters list, then url2 is rewritten
Editing Rewrite Applet/Object Parameter Values
Administrators can now use the administration console to edit the Rewrite Applet/Object Parameter Values list on the Gateway Profile page.
This is the syntax for entries in this list:
- If url_pattern is omitted, the value of the applet/object parameter is examined as a single URL, and the gateway rewrites accordingly.
-
If url_pattern is included, the gateway rewrites according to the pattern matching.
- The url_pattern consists of *, or **, plus the separation character used in the original parameter value to separate multiple fields. One wildcard (*) matches any field that is not to be rewritten. Two wildcards (**) match any field that is to be rewritten. The separation character could be , or |.
-
The last field to be rewritten does not have to be indicated by **. The url_pattern matches the start of the string in the parameter value, and the remainder of the value is considered a URL to be rewritten.
Example
If the gateway receives this request for the URL:
Table 8 is a two column table that contains examples of entries for the Rewrite Applet/Object parameter Values List. The first column provides an example value that is entered in the list. The second column provides a description of how the URL is rewritten.
Denying Unknown Certificate Authorities
A new attribute allows administrators to deny unknown certificate authorities (CAs). The ips.gateway.trust_all_server_cert attribute is in the /etc/opt/SUNWips/platform.conf file. It is used when the Portal Server gateway component uses SSL to communicate with:
- An HTTP proxy, on which a self-signed certificate is installed.
-
An iPlanet Portal Server server, on which a self-signed certificate is installed.
Tip See "Adding a Root CA Certificate" for instructions on installing a Root CA certificate.
The default value of this attribute is false. Administrators should change the value to true to trust all CAs presenting signed certificates to the gateway component during an SSL handshake. For example:
ips.gateway.trust_all_server_certs=true
Typically, the Root CA certificate should be added to gateway certificate database so that the gateway component can identify the certificate presented. However, if a site presents a self-signed certificate, setting the ips.gateway.trust_all_server_cert attribute to true allows the iPlanet Portal Server gateway component to communicate with the site presenting the unknown certificate.
If the gateway does not recognize the certificate that is presented, and if the ips.gateway.trust_all_server_cert attribute is set to false, this error is generated:
Setting the Number of Socket Connection Retries
A new parameter now allows administrators to specify the number of times the iPlanet Portal Server gateway tries to make a socket connection to a destination server should the first attempt fail. The ips.gateway.sockretries parameter is in the platform.conf file.
To specify the number of times the gateway tries to make a socket connection, edit the platf `orm.conf file in /etc/opt/SUNWips and change the ips.gateway.sockretries definition. For example:
Using Outlook Web Access 2000
The Outlook Web Access (OWA) 2000 application can now be used with the iPlanet Portal Server gateway component. To do so, enable basic authentication for your server.
NTLM authentication is not supported.
Inactive Attributes
These attribute settings in the iPlanet Portal Server administration console are no longer used:
- IP Address Validation Enabled
- Trust Server SSL Certificate List
- ReverseProxy Maximum Socket Connections
These settings appear in administration console on the Manage Gateway Profile page, but they do not function. The information in the "IP address validation" section in Chapter 8 "Configuring the Gateway" of the iPlanet Portal Server 3.0 Administration Guide no longer applies.
Localization Changes
This section provides details about localization changes in iPlanet Portal Server. It contains the following topics:
- Installing and Enabling Multiple Locales for a Domain
- Selecting Locale
- Choice Property Keys
- Localizing JSP Provider Titles and Descriptions
- Sample JSP Provider Property File for Locales
Installing and Enabling Multiple Locales for a Domain
The administrator can now specify the locale for domains, roles, and users. A single Portal Server installation with three locale packages installed, for example, allows the administrator to set up three domains, one for each locale. Users registering in domain1 use locale 1. Users registering in domain2 use locale2 and so on.
When you install a new locale, you must run the ipsadmin command to update the iwtPlatform attribute. The iwtPlatform-availableLocales attribute lists all the locales available for the user. For example:
Although values for this attribute are en_US or ja_JA, for example, users see only the common name of the available locale — English or Japanese.
To specify the locale for domains, complete the following steps:
- Log in to the administration console and select Manage Domains.
- Select the domain that you are administering.
- Select Platform and Show Advanced Options.
- Specify the languages you wish to make available for this domain.
Selecting Locale
Users can now select their own locale from a list of locales available.
The provider displays the list of languages to the user. After the user makes a selection, it stores the selection in the user profile. The user must then log in again to get the new locale.
To select locale, users complete the following steps:
- Log in to the Desktop.
- Select Edit to display the Edit User Information page.
- From the list of available languages pull-down menu, select the language.
Choice Property Keys
This feature allows the user to see the changes in the locale of choice.
When editing the profile, for channels created with the channel wizard in a non-English locale, the administrator now sees the choices translated in the chosen language of the locale.
Localizing JSP Provider Titles and Descriptions
A new properties file was added to localize the default Desktop's JSP Provider's title and description. The file, iwtSampleJSP.properties, is in /opt/SUNWips/locale.
This change is visible in the Desktop content provider list as the title and description and also on the Desktop channel title bar as the title.
To change the values of the JSP channel title and description, edit the iwtSampleJSP.properties file and change the description and title entries to display the desired text. For example:
Other entries in the file are used in the administration console for this provider. They are not displayed for the end user. These values align with the idx values in the attributes of the XML files.
Sample JSP Provider Property File for Locales
A copy of the JSP Provider properties file is created specifically so that you can create your own JSP property file for different localizations. In the file, locale specifiers are used as suffixes for locale-specific files. For example:
- The Egypt-Arabic localization file would be called iwtSampleJSP_ar.properties.
- The France-French localization file would be called iwtSampleJSP_fr_FR.properties.
- The U.S. English localization is called iwtSampleJSP_en_US.properties, but the default localization is en_US.
When a user creates a JSP Channel using the Channel Wizard, no properties file is created for that channel. The default property file for a newly created JSP channel is the iwtJSPProvider.properties file, but this file cannot be customized.
To customize or localize the title and description of the newly created JSP channel, complete the following steps:
-
As root, make a copy of the iwtSampleJSP.properties file in the base_dir/SUNWips/locale directory with the component name of your channel:
# cp iwtSampleJSP.properties domaintestjspchannel2.properties
-
Give the file write permissions.
- Edit the values for the title and description entries, which appear as the channel title in its title bar, and the title and description on the Desktop content page.
- Restart the server for the changes to take effect.
The entries other than title and description in this file are unused, because newly created JSP channels get their admin strings from the iwtJSPProvider.properties file. They all share the same strings and would all be edited or localized at once.
NetFile Changes
This section provides details about NetFile changes in iPlanet Portal Server. It contains the following topics:
- NetFile Internationalization and Usability Enhancements
- Using NetWare File Systems
- Defining Systems and Shares
- Defining Hidden Shares
- Alphabetized Shares on Windows NT Systems
- NetFile Usability
NetFile Internationalization and Usability Enhancements
NetFile enhancements include Internationalization compliance and features enabling broader support of FTP servers and usability enhancements. Internationalization compliance is achieved through a combination of internal modifications, and an additional modification to the end user interface. When creating a new share, there is now an option to select the system encoding type. In order to establish a successful connection, the encoding type selected by the end user must match the encoding type of the FTP server.
By applying this service pack, 15 encoding types are added to the NetFile properties files. For more information about the exact properties files entries refer to the section titled "Template Modifications."The default encoding type is ISO-8859-1, and will be associated with a system and consecutive shares if another encoding type is not explicitly selected from the drop-down menu prior to selecting OK.
The following usability enhancements have been added to make NetFile easier and more intuitive to use:
- WU-FTP and MSFTP support
- Novell 5.1 Support (when Novell is explicitly selected)
- Users are no longer able to add non-existent shares
- The use of the tab and return keys are normalized across the Netfile Java interface
- NetFile now shows hidden files (files beginning with a ".")
- NetFile responses more accurately reflect successful or failed actions
- When multiple files are selected for download, all of the file names are now displayed correctly in the pop-up confirmation window
- NetFile saves selected filenames correctly on Macintosh platforms (instead of saving each as NetFileServlet)
- If the incorrect username is supplied when creating a share, the user will have the opportunity to re-enter it instead of only re-entering the password
-
Directory names are shown in the chosen locale
Using NetWare File Systems
File Transfer Protocol (FTP) support for NetWare File Systems through the NetFile and NetFile Lite applications is now available.
Adding a NetWare File System to NetFile
The administrator uses the administration console to add a NetWare File System to NetFile applications. This allows users to use NetFile in the same way they do for any other host type.
To add a NetWare File System, complete the following steps:
- Select the NetFile link in the Desktop's Applications channel to start NetFile.
- Select File and then select Add System.
- Enter the fully qualified system name.
- Select AUTO DETECT or NETWARE as the system type, and select OK.
- Double click on the system in the Network Neighborhood to add a share.
- Enter your Netware user name and password and select a directory to mount.
-
Double click on the share under the system name in the Network Neighborhood to browse the directory.
Adding a Novell File System to NetFile Lite
The administrator uses the administration console to add a Novell file system to NetFile Lite applications. This allows users to perform NetFile functions by using the check boxes next to the file names and selecting an action using a button at the bottom of the page.
To add a Novell file system, complete the following steps:
- Select the NetFile Lite link in the Desktop's Applications channel to start NetFile Lite.
- Fill in the form field for System Name and select the Machine Type as AUTODETECT or NETWARE.
- Fill in the next form fields for User Name, Password, Directory to mount, and select Enter.
- Select the View Systems link.
- Select the host name from the list and select Enter.
Defining Systems and Shares
Administrators can now define Systems and Shares for NetFile and NetFile Lite at the domain, role and user levels. By setting common host data attributes, administrators can define systems and shares to be displayed in the end user's Network Neighborhood.
These NetFile profile attributes changes were made to allow this:
- The iwtNetFile-hostlist attribute can no longer be edited from the administration console.
- The iwtNetFile-commonhostdata attribute was created for NetFile to allow administrators to predefine systems and shares for the user.
Defining Systems and Shares at the Domain Level
To define Systems and Share at the domain level, complete the following steps:
- Log on to the administration console as super administrator.
- Select Manage Domains.
- In the Portal Server Domains page, select the desired domain.
- Expand the key next to Applications.
- Select NetFile.
-
In the prepopulated Host list/type and share information field, modify the common host data attribute.
- For each entry, select Add to add the host and share to the list.
-
Select the Apply changes to all subRoles check box prior to selecting Submit to apply changes to subroles.
Note Applying changes to subroles may overwrite customizations done further down the tree, for example, at the user level.
- Select Submit from the bottom of the page.
To view the defined systems or shares in NetFile, the end user must complete the following steps:
- Log in to the iPlanet Portal Server Desktop.
- Start NetFile or NetFile Lite application.
- Select desired host and select Edit Host Info.
- Enter user name and password for the required host or share.
Defining Systems and Shares at the Role Level
To define Systems and Share at the role level, complete the following steps:
- Log on to the administration console as super administrator.
- Select Manage Domains.
- In the Portal Server Domains page, select the desired domain.
- Select the desired role.
- Expand the key next to Applications.
- Select NetFile.
-
In the prepopulated Host list/type and share information field, modify the common host data attribute.
- For each entry, select Add to add the system and share to the list.
-
Select Submit.
Note End users cannot delete defined hosts and shares, even if they remove them and choose to save their session upon exit.
To view the defined systems or shares in NetFile, the end user must complete the following steps:
- Log in to the iPlanet Portal Server Desktop.
- Start NetFile or NetFile Lite application.
- Select desired host and select Edit Host Info.
- Enter user name and password for the required host or share.
Defining Systems and Shares at the User Level
To define Systems and Share at the user level, complete the following steps:
- Log in to the iPlanet Portal Server administration console.
- Select Manage Domains.
- Select the desired domain.
- Select the desired role.
- Select Users.
- Select the desired user name.
- Expand the key next to Applications and select NetFile.
-
In the prepopulated Host list/type and share information field, modify the common host data attribute.
- For each entry, select Add to add the system and share to the list.
-
Select Submit.
Note End users cannot delete defined hosts and shares, even if they remove them and choose to save their session upon exit.
To view the defined systems or shares in NetFile, the end-user must complete the following steps:
- Log in to the iPlanet Portal Server Desktop.
- Start NetFile or NetFile Lite application.
- Select desired host and select Edit Host Info.
- Enter user name and password for the required host or share.
Defining Hidden Shares
Administrators and Desktop users can now define NT hidden shares for use in NetFile. The Common Host Data attribute allows administrators to define NT hidden shares through the administration console.
The procedure for defining hidden shares through the administration console is the same as that for defining regular shares. Desktop users can add hidden NT shares the same way they would add a regular share, as long as they use the correct user name and password for the hidden share.
For administrators and user instructions, see "Defining Systems and Shares at the Domain Level."
Alphabetized Shares on Windows NT Systems
Windows NT shares in NetFile are now alphabetized. Because all shares on a Windows NT system are automatically displayed when a user selects a system name, alphabetizing the list of shares makes locating the desired share easier.
NetFile Usability
Several NetFile enhancements now make NetFile easier to use. These include the following:
- User can open NetFile files by double-clicking the file name.
- User can select multiple files for download.
- The maximum file size for uploading files with the NetFile application has increased to 500MB. NetFile Lite still has a maximum file size of less than 5 MB.
Netlet Changes
This section provides details about Netlet changes in iPlanet Portal Server. It contains the following topics:
- Automatic Proxy Configuration for Netlet Connections
- Controlling Server Session Timeout When Using the Netlet
- Unlimited Netlet Connections
- Enabling Secure FTP Using A Netlet Connection
- Using the Netlet Proxy
- Netlet Windows
- Using Automatic Proxy Configuration
- Configuring Internet Explorer INS Files
Automatic Proxy Configuration for Netlet Connections
The Netlet can now make use of the browser's Automatic Proxy Configuration file. This feature is supported in Netscape and in Internet Explorer with the Automatically Detect Proxy Settings option deselected. A valid PAC file must be specified in the configuration URL for either browser.
Setting the PAC File Location
In Netscape, the PAC file location can be set by doing the following:
- Go to Edit | Preferences | Advanced | Proxies.
- Enable Automatic proxy configuration by selecting the radio button.
- Enter a URL to an automatic proxy file.
- Click OK to save the new preferences.
In Internet Explorer, the PAC file location can be set by using one of the following procedures.
If you are using a dial-up connection:
- Go to Tools | Internet Options | Connections.
- Select the correct connection name.
- Choose Settings.
- Check Use Automatic Configuration Script.
- Fill in the URL of the PAC file.
- Select OK.
If you are using a LAN connection:
- Go to Tools | Internet Options | Connections.
- Select Lan Settings.
- Select the option to Use Automatic Configuration Script.
- Fill in the URL of the PAC file.
- Select OK.
Internet Explorer can also make use of an auto configuration file. If end users are using INS files for autoproxy purposes, it must contain an entry for AutoConfigJSURL for the Netlet to read the proxy settings correctly. An example INS file section might look like:
Automatic Proxy Configuration File
An automatic proxy configuration file is written in JavaScript and defines a single function called FindProxyForURL that determines which proxy server, if any, the browser should use for each URL. Since the Netlet only needs a communication path back to the iPlanet Portal Server gateway, this decision needs to be made only once. The simplest PAC file is the one that only returns DIRECT (meaning no proxy should be used). The easiest way to test whether the Netlet is configured correctly to use PAC files is to create a simple PAC file and test it on one of the default dynamic Netlet rules, such as telnet.
This PAC file can be placed on a WebServer that is configured to send a MIME type of application/x-ns-proxy-autoconfig for the file extension pac.
Once that is done, the URL to the PAC file can be configured in the browser by using one of the procedures in "Setting the PAC File Location." and the telnet Netlet rule can be launched from the Netlet Provider. The Proxy Server used is displayed in the Java console.
Controlling Server Session Timeout When Using the Netlet
The session timeout value can be set to determine session time outs in one of the following ways:
- By considering Netlet traffic when determining whether a Portal Desktop user session is active
- By letting the Portal session timeout after the idle time has been exceeded even if a Netlet session is active
An entry called netlet.session.extension has been added to the platform.conf file. The netlet.session.extension entry can take a value of true or false.
- A value of true keeps the Desktop session alive if the Netlet is running.
- A value of false results in the termination of the Netlet session upon Desktop idle timeout.
Because of the inherent client/server relationship in most Netlet tunnels, an additional enhancement has been added that enables administrators to configure whether client-bound traffic should be considered when extending the portal session if the netlet.session.extension value is set to true. This option was previously located in the platform.conf file, where it was specified in an earlier patch as netlet.session.extension.for.clientbound.traffic. This option has moved to an Advanced Option in the Portal Server console Gateway Management screen.
Extending Portal Session for Client bound Netlet Traffic
The option can be changed as follows:
- Log in to the iPlanet Portal Server Administration Console.
- Click Gateway Management.
- Click Manage Gateway Profile.
- Click the Show Advanced Options button at the bottom of the frame.
- Deselect or Select the checkbox next to Extend Portal Session for Client bound Netlet Traffic.
Enabling this option updates the iPlanet Portal Server Desktop idle timer even if the traffic is only initiated by the Netlet client's own server. Disabling this option updates the Portal Desktop idle timer only if there is activity initiated by the Netlet client itself. The implementation of this particular option depends on the definition of an Active Netlet User for any given portal deployment. As a rough guideline, here are two examples:
- Active Netlet user is defined as a real person interacting in real time with the Netlet client application.
- Active Netlet user is defined as a real person interpreting Netlet client data pushed from a server application.
If the active Netlet user is defined as a real person acting in real time with the Netlet client, the Extend Portal Session for Clientbound Netlet Traffic option should be disabled. This prevents the Portal Session from being extended in the end-user's absence if the server continues to send updates or other notification to the client application.
Conversely, if an active Netlet user is defined as a real person interpreting Netlet client data pushed from a server application, the Extend Portal Session for Clientbound Netlet Traffic option should be enabled. With this definition, an end user interpreting data streamed or pushed to the Netlet client does not suddenly and unexpectedly have their Netlet session terminated as a result of the Portal Desktop idle timeout.
Advanced Configuration of the Netlet Session Extension
The new attribute's associated XML looks like:
Unlimited Netlet Connections
The Netlet now supports an unlimited number of connections per Netlet. This rule change is beneficial if an application running through the Netlet requires many connections per Netlet.
Enabling Secure FTP Using A Netlet Connection
Secure remote FTP transfers from an end user system to an FTP server are now provided through a Netlet connection. Without a user name, an FTP URL is interpreted as an anonymous FTP connection.
Administrators can use static or dynamic Netlet rules to set up FTP service to a single FTP server. Static rules define the FTP server that is used to transfer files. Dynamic rules allow the user to specify the FTP server.
Table 9 is a three column table that describes netlet rules and provides their formats. The first column describes the purpose of the Netlet rule. The second column states what type of rule it is. The third column provides the format for writing the rule.
Purpose
Type
Format
Rule in which the user logs in to the FTP server as an anonymous user
Rule in which the user logs in to the FTP server with a user ID
This Netlet enhancement requires creating a Netlet rule that listens for FTP requests. To create a static FTP Netlet rule for the Default Role, complete the following steps:
- As root, log in to the administration console at http://server.domain.subdomain:port/console
- Select Manage Domains.
- Select the domain where you want to set the Netlet rule.
- Select DefaultRole.
- Expand the key next to Applications and select Netlet.
- Select the form field below the Netlet Rules text area and add a Netlet rule similar to one in Table 9.
- Select Add and then Submit.
- Log out from the administration console.
Using the Netlet Proxy
The Netlet proxy is used for these reasons:
- To minimize the use of extra IP addresses and ports from the gateway through an internal firewall in a significantly sized deployment environment.
-
To provide encryption for each transaction through the Netlet to iPlanet Portal Server from the gateway to the platform server. The Netlet proxy offers improved security benefits through data encryption but may increase the use of system resources.
Configuring the Netlet Proxy
To configure the Netlet proxy, complete the following steps:
- Log in as root to the iPlanet Portal Server administration console.
- From the left frame, select the Gateway Management link.
- Select the Manage Gateway Profile link to display the Component Profile: Gateway page.
- Scroll to the end of the page and select Show Advanced Options.
- Select the Netlet Proxy Enabled check box to enable the netlet proxy.
-
In the Netlet Proxy Port text field, enter the available port number.
Tip To determine whether the port desired is available and unused, enter this command from the command line:
- Select Submit at the bottom of the page to commit these changes to the profile server.
- On the Profile Successfully Update page, select Continue.
Configuring Restart of the Netlet Proxy
Administrators can use the command line interface to configure an automatic restart of the Netlet proxy whenever the system server is rebooted.
To start the netlet proxy automatically when the machine is rebooted, execute these commands as root:
These steps do not automatically start the netlet proxy when you use ipsserver start to restart iPlanet Portal Server.
Note
Netlet Windows
Administrators can now change the contents of Netlet windows by editing the files that store the values for these messages.
To change the message displayed in the interim status window that lets the user know when the Netlet has finished loading, modify the nc3 value in the install_dir/SUNWips/locale/iwtNetletServlet.properties file. For example:
To change the message displayed in the status window when a static rule has been defined for the current user, modify the Netlet-Provider-wait value in the iwtNetletProvider.properties file. For example:
To change the messages displayed when a Macintosh client attempts to use an automatic proxy configuration file, or when the Netlet cannot determine the Macintosh browser's proxy settings, modify values in the iwtNetletApplet.properties file. For example:
-
ppd.2=Netlet was unable to determine your browser proxy port setting.
ppd.3=Please enter your browser Proxy Port setting below:
pwarn.3mac=Netlet was unable configure your browser proxy settings. In your browser's Preferences->Network->Proxies section:\n\n - add these entries to the 'List of sites that you want to connect to directly':\nlocalhost\n\127.0.0.
To change the message displayed when the Netlet is started from a link within the Netlet channel itself rather than being launched following a successful login, modify the iwtNetletServlet.properties file. For example:
The nc4 value and the contButton value are displayed in the intermediate status window.
Using Automatic Proxy Configuration
The Netlet applet can be used with Web browsers that are configured to use automatic proxy configuration (PAC) files. The automatic proxy configuration feature is supported in the Netscape Navigator and Internet Explorer browsers.
Configuring Internet Explorer INS Files
In addition to using automatic proxy configuration (PAC) files, Internet Explorer can also use an .ins automatic configuration file for automatic proxy services.
If end users are using .ins files for automatic proxy purposes, the .ins file must contain an entry for AutoConfigJSURL so that the Netlet can read proxy settings correctly. The value for the AutoConfigJSURL is a URL that points to a valid PAC file. For example: AutoConfigJSURL=http://sesta.com/corp.pac
Performance and Tuning Changes
This section provides details about performance and tuning changes in iPlanet Portal Server. It contains the following topics:
- Tuning the Gateway for Optimal Performance
- Support of Netscape Security Service (NSS)
- Maximum Thread Pool Size Parameter
- Loading Multiple Attributes in One Profile Request
- Short-Circuiting for Session and Logging Requests
- Web Server Performance
Tuning the Gateway for Optimal Performance
Tunable parameters and internal changes have been added to improve the overall performance of the iPlanet Portal Server gateway component. For detailed Bug IDs and descriptions of specific problems addressed by this service pack see the "Bugs Fixed" section.
The following changes are designed to improve performance:
- Elimination of iPlanet Portal Server gateway restarts as a result of the iPlanet Portal Server gateway not being able to immediately validate its own session
- Reduction of socket depletion by reallocating it to the connection pool as soon as it is no longer being used
- Increase in the JVM heap size
- Removal of verbose Garbage Collection logging
- Creation of tunable memory management options to control forced Garbage Collection
- Reduction of 502 errors returned by the gateway for remote sites that are under heavy load
- Fixed stack overflow when HTTP Proxy is enabled
Tuning the Gateway JVM Heap Space
The minimum and maximum JVM heap size for the gateway process is now 512MB and 768MB, respectively.
Tuning the Gateway JVM Forced Garbage Collection
Three new /etc/opt/SUNWips/platform.conf entries have been added to control the behavior of forced Garbage Collection of the JVM heap by the gateway process.
Table 10 is a three column table that lists and describes the new platform.conf entries. The first column provides the name of the platform.conf entry. The second column lists the default value. The third column gives a description of the new entry.
Tuning Gateway Socket Reconnection for Remote Websites Under Heavy Load
When the gateway component makes a call to retrieve data from a remote site, the socket may fail to open or the request may not be handled because the remote site is under heavy load. Previously, the gateway would report a 502 error and not attempt to reconnect. An additional entry has now been added to the /etc/opt/SUNWips/platform.conf file to specify a number of retries for socket reconnection. The retry interval is fixed at three seconds, but the number of retries can be changed by setting the value of ips.gateway.sockretries, which has a default value of 3.
Support of Netscape Security Service (NSS)
Netscape™ Security Service (JSS) version 2.8.4 to version 2.8.6 is now supported on the gateway component. This increases the number of HTTPS operations that the gateway component can sustain.
Certificates installed for the previous SSL library are automatically converted to the format required by NSS when Service Pack 5 is installed. However, certificate management for the gateway component is different from previous releases of the iPlanet Portal Server software. For more information on gateway certificate management see, "Web Server Performance."
Maximum Thread Pool Size Parameter
For better performance under load, administrators can increase the value of the Maximum Thread Pool Size parameter to 500. The default value is 200.
To increase this value, complete the following steps:
- Log in to the administration console.
- Select Gateway Management.
- Select Manage Gateway Profile.
- Select Show Advanced Options.
- Change the value in the field for Maximum Thread Pool Size to 500.
- Select Submit.
- Restart the gateway for the changes to take effect.
Loading Multiple Attributes in One Profile Request
A new method called Profile.loadAttributes for loading multiple attributes in one profile request is now available. It is used to pass a set of attribute names that can contain wildcards for multiple profile components.
The parameter name is attributeNames. The value is a set of attribute names that can contain wildcard characters.
The returned attribute values are cached in the profile object. This allows a subsequent call to retrieve these attributes faster, thereby improving overall Portal Server performance.
Short-Circuiting for Session and Logging Requests
Short-circuiting for session and logging requests reduces the number of HTTP requests for logging and session services and eliminates XML parsing for these requests. This improves the overall performance of iPlanet Portal Server.
If the logging client and the logging server are in the same JVM, the HTTP connection is bypassed during client and server communication.
Likewise, if the session client and the session server are in the same JVM, no HTTP connection is needed for them to communicate.
Web Server Performance
Adjusting iPlanet Web Server parameter settings can improve the performance of the gateway component. Table 11 is a four column table that describes these parameters. The first column lists the parmeter and the associated configuration file. The second column lists the default value. The third column lists the recommended value. The fourth column provides a description of the parameter.
These configuration files are located in the install_directory/netscape/server4/https-server/config file.
Profile Service Changes
This section provides details about profile service changes in iPlanet Portal Server. It contains the following topics:
- Disabling Synchronization of User Profile Changes
- Multi-Profile Server Support
- Getting and Setting User Properties
Disabling Synchronization of User Profile Changes
By default, changes that users make to their profiles are distributed to other platform server instances using synchronization requests sent over HTTP. This ensures that any instance that has a cached copy of that user's profile updates it's cache with those changes before it needs to handle a request for that user again.
However, many large sites use load balancers in front of their platform servers that maintain sticky sessions. This ensures that the same platform server instance handles all the portal requests made during a single user session. Under these circumstances, distribution of user profile changes to other instances represents an unnecessary burden on the network.
Therefore, it is now possible to disable synchronization of user profile changes by adding the following entry to the /etc/opt/SUNWips/properties.file on each platform server:
This should only be used when load balancers that maintain sticky sessions are in use. A side-effect of this option is that an additional LDAP read of the user's profile is needed at each login to ensure cached copies are updated with changes made during sessions on other instances.
Multi-Profile Server Support
A separate profile service is now used for each Portal Server instance. The profile services are synchronized with each other to keep all modified profile data current. Previously, all Portal Server instances in a deployment used a single profile service. This was a potential single point of failure.
Profile requests originating at any Product_Name instance are now directed to the profile server of that Portal Server. Each Product_Name instance communicates directly with the Directory Server. Performance and scalability for simultaneous logins are improved because all profile requests go directly to LDAP without XML-to-LDAP overhead.
Multiple directory servers are not supported at this time.
The LDAPMonitor object now checks for LDAP connectivity. If it finds a lost connection, it removes all connections from its LDAP connection pool and lets the profile service create the LDAP connection as needed. The first profile service requesting an LDAP connection would then refill the connection pool.
Administrators can use directory.monitor.sleeptime, a new parameter in the etc/opt/SUNWips/properties.file, to define the length of the sleep interval, which is 30 seconds by default.
This is the format of the parameter:
directory.monitor.sleeptime=sleeptime_in_milliseconds
To set the interval to 40 seconds, for example:
directory.monitor.sleeptime= 40000
Tip
Getting and Setting User Properties
Two new methods called setUserSessionProperty and getUserSessionProperty in the pluggable auth API enable authentication modules to get and set properties in the user session. They allow authentication modules to communicate with channels, applications, or other authentication modules by setting session properties.
Example
A custom authentication module may add the user password to the session, so that an application can retrieve this property, for single sign-on at a later time.
The parameter name is the property name, and the parameter value is the property value in this example:
The parameter name is the property name and this returns the property value in this example:
Server Changes
This section provides details about server changes in iPlanet Portal Server. It contains the following topics:
Using Open Portal Mode
iPlanet Portal Server can now be deployed without the services of the gateway. Running without the gateway is referred to as open portal mode. One iPlanet Portal Server installation can be configured to support both open and secure portal modes.
The services presented by the open portal typically reside within the DMZ, not within the secured intranet. If a portal provides public information and allows access to free applications, using open portal mode allows Portal Server to respond faster to access requests.
Using the iPlanet Portal Server in open portal mode may improve the individual response of the portal for a large number of simultaneous users.
Tip
The following Portal Server features are provided by the gateway component and are thus not available when running in open portal mode:
- Netlet, which provides a secure encrypted tunnel for TCP/IP applications from the browser through the gateway to the backend service.
-
URL access policy enforcement, which ensures that any request for a URL is validated against the requesting user's policy. It is important to note that this does not mean there is no user policy. All iPlanet Portal Server services such as the Desktop are protected by the iPlanet Portal Server Policy server.
-
If a user is restricted from either running the Desktop or adding specific channels within the Desktop, for example, this type of policy is still enforced.
-
- URL rewriting, requiring that all URLs accessed from the Desktop must be resolvable and reachable by either the client host or the web proxy the client is configured to use.
-
HTTP basic authentication, which provides a single sign-on service. The gateway listens for interaction between the user and the Web Server and stores the user name and password in the user profile so that the next time the user does not have to enter the information. The gateway responds on behalf of the user.
Note For instructions on installing the iPlanet Portal Server software in open portal mode, see Chapter 4, "Clean Installation," in the iPlanet Portal Server Installation Guide.
Configuring Open Portal Mode
The typical public portal uses HTTP. You can now deploy a portal using HTTP over SSL (HTTPS). You can configure Portal Server to run HTTPS services during installation, or you can manually change from HTTP to HTTPS after installation.
See the iPlanet Portal Server Administration Guide for more information on using SSL.
The user accesses the server directly as though the server is configured for HTTP, but uses the URL https://server.domain instead of http://server.domain.
To update Portal Server to open portal mode following installation, complete the following steps:
-
Use the ipsgateway stop command to shut down the gateway.
-
Use the pkgrm command to remove the gateway.
Logging In
The rules for logging in to the open Portal Server include the following:
-
If the server is running HTTP and is using the default HTTP port 80, use the following URL:
-
If the server is running HTTP and is using a non-default port number, use the following URL:
-
If the server is running HTTPS and is using the default HTTPS port 443, use the following URL:
-
If the server is running HTTPS and is using a non-default HTTPS port number, use the following URL:
Supporting SSL Login
In a portal setup without the gateway, this feature provides support for SSL (HTTPS) server for user registration although the sites run without SSL (HTTP).
All registrations and logins now can be directed to an HTTPS server, while all Desktop redirects are sent to an HTTP server. The iPlanet Portal Server supports this configuration by running two instances of iPlanet Portal Server. One instance runs HTTP, and the other instance runs HTTPS.
After you set up the server instances, you convert the second instance of the server to SSL. After configuring the second instance, you update user profiles to redirect users to the non-SSL server after authentication. See "Multi-Profile Server Support" for detailed information on setting up two instances of iPlanet Portal Server.
To ensure that all unauthenticated sessions on the non-SSL server are redirected to the SSL server, you must edit the platform.conf file in /etc/opt/SUNWips/ directory and then set the user profile to point to the non-SSL port on the open portal.
To do this, complete the following steps:
- Become root and change directory to /etc/opt/SUNWips.
-
In the appropriate platform.conf files, change the value for ips.nosession.url setting to this:
-
ips.nosession.url=https://server.domain:port/login
Tip Replace server with the host name of the SSL server and port with the port number where the server is running. For example:
ips.nosession.url=https://server1.sesta.com:8081/login
If you have multiple iPlanet Portal Server server instances, you must edit the platform.conf file associated with each instance.
-
-
Add the following to the /etc/opt/SUNWips/desktop/customized_template/iwtLoginProvider/display.html file:
-
<FORM ACTION="https://server1.sesta.com:8081/login/Membership" onSubmit="return checkBlank()" MET
HOD=GET NAME="userid_form" ENCTYPE="application/x-www-form-urlencoded"><FONT FACE="[tag:iwtDesktop-fontFace1]" SIZE="-1"><A HREF="https://server1.sesta.com:8081/login/Membership?arg
=newsession&page=1&Submit=New%20User">Sign Me Up</A></FONT>
-
- Log in to the administration console and select Manage Domains.
- Select your domain and under Profiles, select User.
- Select Show Advanced Options.
-
Change User's Default URL from /DesktopServlet to:
- Select Submit at the bottom of the page, and save the changes.
-
On the Profile Successfully Updated page, select Continue.
Note For information about changing multiple instance servers to SSL in open portal mode, see "Changing Created Multiple Instance Servers to SSL."
URL Scraping
Some rewriting facilities that were only in the gateway profile are now available with the server. This allows administrators to configure parameters for URL scraping in open portal mode. These parameters include:
- Rewrite HTML attributes
- Rewrite HTML attributes containing JavaScript
- Rewrite JavaScript function parameters
- Rewrite JavaScript variables in URLs
- Rewrite JavaScript variables functions
- Rewrite JavaScript function parameters in HTML
- Rewrite JavaScript variables in HTML
- Rewrite Applet parameter values list
When the open portal mode is installed, the selections on the Gateway Profile page are not disabled even though most selections are disabled because no gateway is running.
To view this and observe the impact, in the administration console, do the following to access the Gateway Profile page:
- Log on to the administration console as super administrator.
- From the left frame, select Gateway Management.
- Select the Manage Gateway Profile link.
- Select the Gateway Profile page.
Using a Load Balancer
iPlanet Portal Server now supports using a load balancer in open portal mode. The load balancer must support persistent connections, sometimes referred to as sticky sessions based on cookies. If the load balancer supports persistence based on a cookie name and value, this feature must be enabled.
If the Portal Server environment includes a load balancer, and a URL scraper channel that references material from a server other than the iPlanet Portal Server, that material is looked up from the server on which it sits. For example, server names in an image's URL are visible in the browser's page information window, and the browser accesses those images without using the load balancer.
The load balancer must be able to recognize the cookie on the first reply from portal. It should then continue to send all requests with that cookie name and value to that same server. Cookie persistence algorithms that do not recognize the cookie on the reply do not work, because the first and second request can end up on different servers.
If the load balancer does not support this type of cookie persistence algorithm, but it supports load balancing to specific servers based on the presence of a cookie name and value, the administrator can edit the appropriate platform.conf file to configure cookie values on each server.
Each server defines a special cookie that the load balancer is configured to recognize and always forwards requests with that cookie to that specific server. Each Portal Server instance sets this cookie along with the usual portal session cookie.
Cookies can be used to establish session persistence between some load balancers and servers in an iPlanet Portal Server installation.
To use a load balancer in open portal mode, complete the following steps:
- Set up a load balancer to the servers.
-
As root, add the following lines to the platform.conf file:
ips.lbcookie.name=iPSlbCookie ips.lbcookie.value=some_unique_server_string
- Log in to the administration console as the super administrator.
- Select Server Management and select Manage Profile Server.
-
Add the load balancer domain name to the Cookie Domain List and select Add.
Tip Use this format to add the domain name:
Note the . that precedes the name.
- Select Add.
- Select Submit.
- Add the load balancer name to Domain URLs list.
- In the administration console, select the desired domain.
- Select Authentication.
-
Add the load balancer name three times to Domain URLs list.
-
Edit the URL for channels that reference their content from the iPlanet Portal Server server.
Note This step is not for channels that point to external content. It is useful for portal-related content that is displayed in channels.
- In the administration console, select the desired domain.
- Click the key next to Applications to expand the list choices, and select Desktop.
-
Edit the URL scraper channels that reference their content from the server. Change the attribute to a relative URL by removing the protocol, server and port number from the URL.
Tip For example, change this URL scraper channel value:
http://server1.sesta.com:8080/ipinfo.html
- Select Submit.
Changing the Primary Profile Server to SSL
The profile server's protocol can be changed to HTTPS. This is the server that has the profile service running on it. See the following instructions.
In the following instructions and examples, /opt is the default installation directory.
Note
-
As root, use this command to start Portal Server:
- Log in to the administration console as super administrator.
- From the left frame, select the Server Management link.
- Select the Manage Server Profile link.
-
Change the Platform Server List attribute to HTTPS. For example:
- Select Submit to save the changes.
- Select Continue on the Profile Successfully Updated page.
- From the left frame, select Server Management link.
- Select Manage Naming profile.
-
In Profile URL, change the protocol to HTTPS. For example:
-
https://server1.server2.sesta.com@8080/profileservice
-
-
In Logging URL, change the protocol to HTTPS. For example:
- Select Submit to commit these changes to the profile server.
- Select Continue on the Profile Successfully Updated page.
-
In a terminal window, go to the /etc/opt/SUNWips directory.
-
In the platform.conf file for the primary server, which is /etc/opt/SUNWips/platform.conf.server.domain, change HTTP to HTTPS in these definitions:
-
ips.server.protocol (for example, ips.server.protocol=https)
ips.naming.url (for example, ips.naming.url=https)
ips.notification.url (for example, ips.notification.url=https)
-
-
In the platform.conf file for the second server, which is /etc/opt/SUNWips/platform.conf.server.domain@8081, change HTTP to HTTPS in this definition:
-
In the platform.conf file for the third server, which is /etc/opt/SUNWips/platform.conf.server.domain@8082, change HTTP to HTTPS in this definition:
-
Use a text editor to edit the /opt/netscape/server4/https-server1/config/magnus.conf file to turn on the Security option. For example:
-
Use this command to stop and restart all Portal Server instances:
# /opt/SUNWips/bin/ipsserver startall
Configuring Multiple Server Instances
You can now run multiple instances of the iPlanet Portal Server on different ports. Running multiple instances of Portal Server, each with its own copy of iPlanet Web Server on the same physical machine, changes the context of iPlanet Portal Server to have multiple web servers and JVMs on the same machine.
It is possible to configure the various instances to implement SSL, giving a user the flexibility of switching to SSL mode for security on any of the iPlanet Portal Server instances. So when running in open portal mode, iPlanet Portal Server instances can talk over SSL.
Using the create command only configures new iPlanet Portal Server instances using the HTTP protocol.
Note
Installing Multiple Server Instances
You can create multiple instances of the iPlanet Portal Server on different ports, after you install iPlanet Portal Server.
For installation instructions, see "Service Pack 5 Installation Notes" in the iPlanet Portal Server Installation Guide.
Tip
To configure multiple server instances, complete the following steps:
In the following instructions and examples, /opt is the default installation directory.
Note
-
As root, enter the following commands:
# cd /opt/SUNWips/bin
# ./ipsserver create
-
This option is interactive. The administrator can continue to enter unique port numbers, not already in use, where multiple instances are to be created. Select Return after your last entry.
Tip To determine whether the desired port is available and unused, enter this command from the command line:
This process takes approximately 5 minutes, depending on the machine architecture. Here is an example of what the script output and user input looks like:
Should any instances entered already exist, the following message is displayed before you are prompted to overwrite:
Warning:: server instance already exists:server1.sesta.com-8081
-
- Select Return when the menu is completed.
-
Use this command to stop and restart all the Portal Server instances:
# /opt/SUNWips/bin/ipsserver startall
- Log on to the administration console as super administrator.
- From the left frame, select the Server Management link.
- Select the Manage Server Profile link.
-
Add the new server instances to the Server List. For example:
- Select Submit and save the changes.
- On the Profile Successfully Updated page, select Continue.
-
Use this command to stop and restart all the Portal Server instances:
# /opt/SUNWips/bin/ipsserver startall
These instances can be directly accessed through the web browser. For example:
If the machine name is siroe.iplanet.com, and two port numbers 8081 and 8082 were configured as shown in the Step 1, and the install directory was /opt, the following files are listed:
/opt/SUNWips/bin/ipsserver.server1.sesta.com@8080
/opt/SUNWips/bin/ipsserver.server1.sesta.com@8081
/opt/SUNWips/bin/ipsserver.server1.sesta.com@8082
Updated Command Options
Table 12 lists new ipsserver commands and the command options that have been updated. The first column contains the command name and option. The second column contains a description of the command option.
The following examples assume that the commands are being run from the directory in which they reside.
Changing Created Multiple Instance Servers to SSL
In open portal mode, you can change the protocol to HTTPS of any of the other created multiple instances. Make these changes for the server where SSL is required. Make sure that the key pair file password and the trust database password entered for any of the certificate installation is the same between all the iPlanet Portal Server created multiple servers which are being configured to talk over SSL and that password must be the SSL passphrase entered during the iPlanet Portal Server installation.
In the following instructions and examples, /opt is the default installation directory.
Note
If the instance running on port 8081 is to be secure, for example, complete the following steps:
-
Stop and restart all Portal Server instances:
- Log on to the administration console as super administrator.
- Select the Server Management link from the left frame.
- Select the Manage Server Profile link in the right frame.
-
Change the Platform Server List attribute to https. For example:
- Select Submit.
- Select Continue on the Profile Successfully Updated page.
- Open the platform.conf file of the server that is configured for SSL, in the /etc/opt/SUNWips directory.
-
Find the ips.server.protocol setting and change it to the following:
-
Find the ips.notification.url setting and change it to the following
- Open the /opt/netscape/server4/https-server1.domain@port/config/magnus.conf file.
-
Find the Security setting and change it to the following:
-
Use this command to s top and restart all Portal Servers:
-
To confirm that the configured server is talking SSL protocol, enter its URL in a browser. For example:
Multi-hosting
The server can now access multiple instances of iPlanet Portal Server from a single server installation. Access to Portal Server is through one of these:
To log in to a different domain on Portal Server, use this URL:
Mapping URLs to Domains
If the existing installation of Portal Server contains multiple servers and multiple domains, a URL-to-domain mapping setting allows Portal Server to find the domain automatically. The domain name does not need to be provided in the URL.
If the Portal Server installation has one server and two domains (domain1 and domain2), the following URL-to-domain mapping is needed:
- http://server.domain:port/domain1 to go to domain1
- http://server.domain:port/domain2 to go to domain2
To map a URL to a domain, complete the following steps:
- Log in to the administration console as super administrator.
- From the left frame, select the Manage Domains link to display the Portal Server Domains page.
- Select one of the domains to display the Domain, Role and Users page.
- Expand the Profiles link and select the Authentication link.
- In the Domain URLs field, add the URLs for that domain.
- Select Add.
-
Select Submit.
Note You must repeat these steps for each domain.
Domain URL Mapping List
The domain URL list for domain1 must contain the following URLs:
- /domain1
- server1.domain/domain1
- server1 IP address/domain1
- /domain2
- server1.domain/domain2
-
server1 IP address/domain2
Note In the following instructions and examples, /opt is the default installation directory.
-
Add the following two lines to the obj.conf file in the /opt/netscape/server4/https-server1/config/ directory:
-
NameTrans fn="redirect" from="/domain1" url="/login/domain1"
NameTrans fn="redirect" from="/domain2" url="/login/domain2"
Replace domain 1 and domain 2 with iPlanet Portal Server domain names.
-
-
Use this command to stop and restart the server:
# /opt/SUNWips/bin/ipsserver start
Example 2
If there are three servers (server1, server2, and server3) and two domains (domain1 and domain2), the following are the URL to domain mappings:
To map a URL to a domain, complete the following steps:
- Log in to the administration console as super administrator.
- From the left frame, select the Manage Domains link.
- In the Portal Server Domains page, select one of the domains.
- In the Domain, Role and Users page, expand Profiles link and select the Authentication link.
- Scroll to the Domain URLs field, add the URLs for that domain. (See the "Domain URL Mapping List for Example 2" section.)
- Select Add.
- Select Submit.
- Repeat these steps for the second domain.
Domain URL Mapping List for Example 2
The domain URL list for domain1 must contain the following URLs:
- server1.domain
- server1.domain IP address
- server1.domain/domain1
- server1.domain IP address/domain1
- .domain/domain1
- server1.domain/login
- server1.domain IP address/login
The domain URL list for domain2 must contain the following URLs:
- server2.domain
- server2.domain IP address
- server2.domain/domain2
- server2.domain IP address/domain2
- .domain/domain2
- server2.domain/login
- server2.domain IP address/login
- server3.domain
- server3.domain IP address
- server3.domain/domain2
- server3.domain IP address/domain2
- server3.domain/login
- server3.domain IP address/login
Running Applications on a Non-iPlanet Portal Server
If you write applications using iPlanet Portal Server APIs, you can run them on a server host that is not iPlanet Portal Server. The applications can be either standalone Java applications (with some limitations) or a servlet application running on iPlanet Web Server.
iPlanet Portal Server public APIs are supported only on Solaris™ operating systems.
Note
- JDK software/Java™ runtime environment 1.2.2_16-er-20030716
- Sun ONE Web Server 4.1 SP12
- Solaris™ 2.6 Operating System (SPARC™ Platform Edition)
- Solaris™ 7 Operating System (SPARC Platform Edition)
- Solaris™ 8 Operating System (SPARC Platform Edition)
Setting Up a Non-iPlanet Portal Server Server
In the following instructions and examples, /opt is the default installation directory.
Note
To set up a non-Portal Server, complete the following steps:
- Create the following directories on the server host.
- iwtPll.properties
- iwtProfile.properties
- iwtSession.properties
- iwtLogging.properties
-
iwtNaming.properties
Applications Not Running Under iPlanet Web Server
A notification feature of the iPlanet Portal Server session and profile APIs allows applications to listen for profile and session state changes. If an application runs as a standalone application:
- The application cannot receive session or profile notifications.
- The client side cache is not updated when attributes change in the profile. The application sees the changes only after the user logs out and logs back in.
-
After the user session times out on the iPlanet Portal Server session server, the user still has a valid session until the cache refresh timer is reached.
Tip Use the administration console to reduce the cache seconds attribute in the session profile.
Running Client Applications Using SSL
If the iPlanet Portal Server server is configured to use SSL, the iPlanet Portal Server APIs also use SSL. The application must also use SSL to communicate with the iPlanet Portal Server services.
The iPlanet Web Server, when installed, is not properly configured to support outgoing SSL connections by servlets.
In the following instructions and examples, /opt is the default installation directory.
Note
To enable SSL connections by servlets, complete the following steps:
-
Copy the following files from the /opt/SUNWips/lib directory to the same location on the server host:
-
include the following files in the classpath in the iPlanet Web Server iws_server_root/https-your_server/config/jvm12.conf file:
- Copy the /opt/SUNWips/lib/solaris/sparc/libjssl.so file to the iws_server_root/bin/https/lib directory.
- Restart the iPlanet Web Server after updating these files.
Running Applications Through the Gateway
To run applications using the iPlanet Portal Server gateway, you must configure the gateway to forward iPlanet Portal Server cookies to the application host. By default the gateway forwards cookies only to the iPlanet Portal Server.
If the URL of the server the application is running on is not added to this attribute, the iPlanet Portal Server cookie is not forwarded, and the application has an invalid user session.
In the following instructions and examples, /opt is the default installation directory.
Note
To configure the gateway to forward cookies, complete the following steps:
- Log on to the administration console as super administrator.
- From the left frame, select the Gateway Management link.
- In the right frame, select the Manage Gateway Profile link.
- Select the Manage Gateway Profile link in the right frame.
- Scroll down to the Forward Cookie URL List attribute.
-
Enter the URL of the server the application is running on in this field. For example:
- Select the Submit button at the bottom of the page to commit these changes to the profile server.
- Select the Continue button on the Profile Successfully Updated page.
-
Use this command to restart the gateway:
# /opt/SUNWips/bin/ipsgateway start
Running Applications Without the Gateway
To run applications without the gateway, access the application using a fully qualified domain name (FQDN).
If a fully qualified domain name is not used, the iPlanet Portal Server cookie is not forwarded to the application, and the user session is invalid.
Third-Party Software Changes
This section provides details about updating the smbclient command in iPlanet Portal Server.
Adding smb.conf Parameter to smbclient
The smb.conf parameter has been added to the smbclient command to allow NetFile to display ISO8859-1 character sets in file names.
This new parameter also provides a way for administrators to configure the NetFile application to take advantage of other smbclient features.
Example
Here is an example of an smb.conf file that could be used to see the choices translated in a locale's chosen language:
An accompanying map file in /opt/samba/lib/users.map might look like this:
For more information about Samba-specific configurations, refer to the samba Web site at:
Webmail Changes
This section provides details about enabling Webmail applications in iPlanet Portal Server.
Enabling Webmail Applications in Portal Server
Portal Server can now deliver Webmail applications.
A connection handling problem between the Internet Explorer 5.5 browser and iPlanet Portal Server may result in Page not Found errors when Webmail is used. The administrator can avoid this problem by editing the Messaging Server's main.js file.
To change the main.js file on the Messaging Server, complete the following steps:
- As root, edit the /msg_install_dir/msg*/html/main.js file.
-
Find the following line:
-
Change this line to:
- Find all instances of .msg entries and change each msgHREF to srcHREF to get the rewritten URL.
Deprecated Features
The following features and products might not be supported in future releases of the iPlanet Portal Server product:
- Firewall software that is currently included with the iPlanet Portal Server product
- NetFile Lite
- GraphOn server and client (client still available for download)
- Citrix (available for download)
- PCAnywhere Java client (available for download)
- Mail check channel (replaced by mail channel)
Although the GraphOn client, Citrix software, and PCAnywhere Java client will no longer be included as third-party software with the iPlanet Portal Server product, they will continue to work with the iPlanet Portal Server product and are available from their respective websites.
Known Problems and Limitations
This section lists known problems with iPlanet Portal Server 3.0, Service Pack 5. Details are provided in the following areas:
- Authentication
- Administration
- Desktop
- Gateway
- Installation
- ipsadmin
- ipsserver
- Logging
- NetFile
- NetMail
- Sample Providers
- Upgrade
Authentication
The LDAP authentication module does not allow the administrator to specify a search filter when configuring the server for user lookup in the directory. (4599553)
The text field, search filter for userId, refers to the attribute (by default, the uid attribute) to use in searching the directory. Then the attribute specified in the search filter for userId is used to create the search filter used in the lookup.
For example, if you did not specify an attribute in the search filter for userId text field and left it blank, the default is uid. So, the search filter becomes (uid=jim), where jim is the user name that the user entered. If the search filter for userId field contained the value surname or sn, then the search filter would become surname=jim.
Administration
Inherited value is not reflected once the change has been submitted. (4825404)
If the Make Inherited option is selected for a field in the Administration console, the inherited value is not reflected after the change has been submitted. However the change is written back to the profile server, and will be reflected when the profile is next refreshed.
If an end user has customized the Desktop, new channels cannot be pushed to the Desktop. (4500010)
Currently, if an end user personalizes the Desktop and the administrator creates a new channel, there is no way for the channel to automatically appear on the Desktop.
Each user needs to add the new channel manually.
Adding channels using a platform server that does not have the profile server installed causes an error. (4521342)
Although the channel wizard is present in the administration console, if a platform server does not have the profile server installed, an error occurs and channels will not be added to the Desktop.
To add channels, the administrator must be logged onto the primary server (first installed server), or original profile server.
The Desktop is blank if no channels are selected in the administration console and in the Desktop. (4375670)
Workaround:
The setDomain method should attempt to retrieve a domain profile before setting the domain. (4378030)
Workaround:
The administration console allows duplicate tab names if one attribute is different. (4376634)
Workaround:
Verify that tab names are not duplicated.
The Valid Session number in the Manage User Session page provides an inaccurate number of valid sessions. (4381586)
When you log in to the administration console (either as super user or any user) and select Manage User Session, the Valid Session number is shown as 1. When you log in again from another browser, the Valid Session number does not increment to 2 to show that two valid sessions are in progress.
Contents of profilestyle.css can become visible in the administration console when adding a new user to a newly created domain. (4379326)
Workaround:
After the server is restarted, the gateway cannot be restarted from the administration console. (4531433)
After the server is restarted, the gateway's session becomes invalid. The next connection will cause the gateway to restart itself.
Manually restart the gateway and then click on the Gateway Management link again in the admin console.
Just hitting the browser reload button will not work.
Note
The gateway cannot be restarted from the administration console if a case mismatch for the gateway name occurs during installation. (4521387)
During installation of the gateway and the profile server, the fully qualified name of the gateway given should match the profile server name. For example, if gateway.sesta.com is the fully qualified name provided during the gateway installation, during the profile server installation. the gateway name must be entered as gateway.sesta.com (not gateway.SESTA.COM, for example) during the profile server installation.
if there is a case mismatch problem occurs, edit the /etc/opt/SUNWips/platform.conf file to change the ips.gateway.host value to match the entry in the server configuration. For example, change the value to ips.gateway.host=gateway.sesta.com. Then restart the gateway.
When accessing the administration console through the gateway, the URL in the browser's address field reflects the name of the server that the gateway is connecting to. The server name must be that of the primary server. If more than one instance is running on the primary server, the URL must also contain the port number for the primary instance.
The URL should be similar to the following:
https://server1.sesta.com:333/https://primary_server.sesta.com:primary_instance_port/
-
Verify that the gateway is connecting to the primary server and the primary iPlanet Portal Server instance. If necessary:
- Replace the server name in the URL so that it contains the name of the primary server.
-
Replace port number in the URL so that it contains the port number of the primary iPlanet Portal Server instance.
- Select Enter.
Desktop
Disabling the Netlet provider in the Administration console for a user causes "Document contained no data" error message. (4319604)
Workaround:
Remove the provider from the channel list in the Administration console.
When using Internet Explorer 5x on Windows 98, closing the Netlet window crashes the web browser. (4355280)
Workaround:
Using bookmark provider with Internet Explorer 4.x client on open portal gets a script error (4358738)
Workaround:
None. This Internet Explorer 4.x bug is not reproducible with Internet Explorer 5.x or Netscape browsers.
delAttribute permits deletion of a profile attribute without write permission. (4447005)
Workaround:
Administrators can delete their own accounts. (4454833)
Workaround:
- Log on as root.
-
At the prompt, enter this string:
# echo '<iwt:Att name="iwtUser-role"><Val>/$DOMAIN/AdminRole</Val></iwt:Att>' | /opt/SUNWips/bin/ipsadmin create user /$DOMAIN/root/dev/stdin
- Select Return.
Descriptions for channels created with channel wizard cannot be localized. (4457299)
Workaround:
To localize the description and title for a channel created with the channel wizard, complete the following steps:
-
On each iPlanet Portal Server, create a file called /opt/SUNWips/locale/channel_locale.properties where channel is the fully qualified name of the channel and locale is the name of the locale to be supported.
-
In this file, create these entries for the description and title:
-
description=This is the description
The .properties file must use Java Unicode encoding, where multi-byte characters are represented as XXXX where the Xs are hexidecimal digits.
Files in this encoding can be created from files in a variety of native encoding using the java native2ascii program.
Note A separate .properties file is necessary for each locale to be supported.
-
The user's default HTML character set is overridden, which causes problems in an iPlanet Portal Server environment that uses multiple locales. (4481045)
Workaround:
Specify the user's character set in the profile and in the .properties file. To do so, complete the following steps:
- Log in to the administration console.
- Select Manage Domains.
- Select the domain for which you want to specify the locale and character set.
- Select User in the Profiles list.
- Enter the locale information in User's Default Locale. To specify the Japanese locale, for example, enter ja_JP
- In the User's Default HTML charset field, enter the character set information.
- Select Submit at the bottom of the page.
- Select Continue on the Profile Successfully Updated page.
- As root, create a property file for the locale, if one does not already exist, in /opt/SUNWips/locale.
-
Rename the file, by adding the locale specifier. For example, to create a property file for the Japanese locale:
# cp /opt/SUNWips/locale/iwtUser.properties iwtUser_ja_JP.properties
-
Edit the property file to specify the character set. For example, to specify the Japanese locale: charset=EUC-JP
Note This workaround applies for the NetMail character set and the iwtNetMailServlet.properties file. Perform this procedure for creating and editing the iwtNetMailServlet.properties file.
Reconnecting to a Netmail Java session causes Internet Explorer 5.0 or Internet Explorer 5.5 browsers to close when running on a Windows 2000 client machine when using Microsoft Virtual Machine (VM) for Java, 5.0 Release 5.0.0.3234. (4525913)
Workaround:
Install Microsoft VM for Java, 5.0 Release 5.0.0.3802.
Users logged in as anonymous cannot access other authentication mechanisms with the same iPlanet Portal Server session. (4525900)
This problem requires the user to exit the browser because the anonymous user Desktop page does not have a means for logging out of the session.
Gateway
When the Non Portal Server Cookie Management option is enabled, the gateway rewrites cookies using the domain name of the gateway. Internet Explorer does not accept these cookies when domain names contain upper case letters. (4647934)
Workaround:
Use lower case letters when setting domain names during installation and when referring to domain names.
Installation
Installing the iPlanet Portal Server product over a previous installation that did not install correctly causes the installation log file to get very large. (4448387)
Workaround:
After installation, remove the installation log file /var/sadm/install/logs/ipsinstall.process_id/install.log.
Solaris 8 patch causes patchadd -p command called from install script to fail due to large output. (4638284)
Workaround:
Change the variable assignment for AWK from usr/bin/awk to usr/bin/nawk in ipsinstall. The approximate location for this change is at line 10 in the script.
ipsadmin
When using an ipsadmin command line option to add, delete, or change a userid that contains special characters, the special characters are treated as delimiters and the ipsadmin utility gives an error.(4640045)
Workaround:
Place single or double quotation marks around the string that contains the special character to identify it as a single token.
The command ipsadmin does not check for the syntax of boolean flags. (4319514)
Workaround:
When you create an XML file, if the attribute type is boolean, add a true or false statement. For example:
If the iPlanet Portal Server software is in a non-English locale, any input provided to the ipsadmin command should be in UTF-8 character encoding when using the certain options with an xml file. (4614401)
These options include the following:
Workaround:
XML files should not use Java Unicode encoding as produced by native2ascii. To change the character set encoding in an XML file, do one of the following:
- Set the encoding header at the top of the XML file to the correct character set.
- Convert the file to UTF8 and set the encoding in the XML file to UTF.
An example of an encoding header using the Thai character set would be:
<?xml version="1.0" encoding="TIS620"?>
An example of an encoding header set to UTF8 would be:
<?xml version="1.0" encoding="UTF8"?>
To convert an XML file to UTF8 do the following:
-
Extract getdomain.xml using the ipsadmin utility.
-
Use native2ascii to convert it to ascii mode.
# native2ascii -encoding character_encoding getdomain.xml getdomain-ascii.xml
-
For example, if using Thai character set encoding, the command would look like:
# native2ascii -encoding TIS620 getdomain.xml getdomain-ascii.xml
-
-
Use native2ascii to convert it to UTF mode.
# native2ascii -encoding UTF8 -reverse getdomain-ascii.xml\ getdomain-utf8.xml
-
Get the XML file back using the ipsadmin utility.
# ipsadmin change domain sun.com getdomain-utf8.xml
ipsserver
The ipsserver start command requires additional arguments if the server is running multiple instances. (4379242)
For more information, see "Configuring Multiple Server Instances."
To start all processes for all instances, use the ipsserver startall command:
To start the processes for a specific instance, use the ipsserver start command and the server-specific ipsserver file:
Heavy loads for an extended duration cause components in the operating system to fail. (4472975)
Workaround:
Logging
Log records should be written using iwtPlatform-locale not iwtUser-locale. (4376995)
Workaround:
Mobile Access Pack
The iPlanet Portal Server: Mobile Access Pack software is not supported in Service Pack 5.
NetFile
The hour glass occasionally keeps running after attempting to add a share in NetFile Java. (4342453)
Workaround:
Select some other part of NetFile to clear up the hour glass.
NetFile Lite does not check the size of a file before attempting to upload. If the file is greater than 5 MB, the upload fails. (4293370)
Workaround:
Uploading tar files greater than the 5 MB limit in NetFile Lite, and tar files greater than the 500 MB limit in NetFile generates an incorrect error message. (4372826)
Workaround:
The NetFile application allows users to access denied hosts if those hosts were added to the Desktop before a deny rule was added in the iPlanet Portal Server administration console. (4463515)
Workaround:
if Portal Server and the FTP server are on different subnets, the FTP server is tried on all the IP addresses of the interfaces. (4486094)
It is expected that the interface's IP address and the IP address of the FTP Server are on the same subnet. The solution does not work with IPv6 to IPv4 tunneling. The solution does not work with tunnelled source and destination, even if the source and destination addresses are IPv4. The solution works with multiple homes created for separating two different networks.
In the case an appropriate IP address/interface cannot be determined, the FTP server is tried for on all IP addresses of the interfaces. In this case the request can time out and NetFile would show the contents to be blank.
NetMail
A race condition occurs if when replying to a message, selecting send and then immediately deleting the message. (4321516)
Workaround:
Wait for the reply flag to be set (slow down) or delete the message again.
IMAP password is displayed in clear text in source of edit. (4307367)
Workaround:
Sample Providers
The editType attribute is missing in the iwtHelloWorld3Provider.xml file and the iwtQuotationProvider.xml file. (4389071)
Workaround:
Add the following code inside the component tags of iwtHelloWorld3Provider.xml:
Add the following code inside the component tags of iwtQuotationProvider.xml:
Upgrade
Custom-added attributes are lost after upgrade is complete. (4766377)
During an upgrade, any custom-added attributes will be lost. This is because, if ipsadmin utility is used to add the new attributes, the utility will only add the attribute in the directory.
In order for custom-added attributes to be carried over after an upgrade, the administrator must manually add the new attributes in the associated xml file.
When attempting to upgrade individual platform servers from a multi-profile environment to a Service Pack 5 multi-profile environment, the installer assumes that Directory Server is installed locally and attempts to re-install it. (4714378)
Workaround:
Temporarily change the ips.profile.host entry in the platform.conf file from the localhost to the "real" profile FQD.
When attempting to upgrade from a highly-customized Portal Server with many new components or channels, a tuned ipsadmin script is replaced by a default script and heap space allocated for successive component imports is inadequate.
Workaround:
Modify the ipsinstall script to stop for intervention right after the SUNWwtds package has been installed. The approximate location for this change is at line 3353 in the script. Change the following lines:
Once the installer prompts you to continue, edit install_dir/SUNWips/bin/ipsadmin. The approximate location for this change is at line 34 in the script. Change the following line:
Upgrade may take a long time because custom components are imported twice, regardless of whether they differ from their XML counterparts.
Workaround:
Edit the ipsinstall and ipsadmin scripts as noted previously in this Upgrade section. In addition, once the installer prompts you to continue, remove the XML files from /etc/opt/SUNWips/xml that do not differ from values stored in LDAP.
Bugs Fixed
This section lists the fixes to the known problems associated with previous iPlanet Portal Server product releases.
Table 13 is a three column table that describes the bugs that have been fixed in this release. The first column contains the Bug ID and the component with which the bug is associated. The second column provides a description of the bug. The third column lists the Service Pack number that contains the bug fix.
Bug ID
Bug Description
Fixed In
The authentication component does not use the iwtUser-defaultURL attribute value from a user's profile if the domain profile contains this attribute value.
Changes to External LDAP mappings made using ipsadmin command utility do not take effect. If new values are added to ExtLdap mapping using the ipsadmin command, the values get changed but the remote flags are not set therefore the changes do not take affect.
If Certificate authentication and SSL between the gateway and the iPlanet Portal Server are enabled at the same time, users are unable to login.
The iPlanet Portal Server returns a 502 gateway error when the administrator chooses Server Name under Session Servers.
Clicking on a server link on the Logging Servers page gives an iPlanet Portal Server gateway Error.
The attribute in LDAP to use for Profile ID field in Cert Authentication is a password field.
Administration console allows roles and users to be entered with non-ASCII characters, and generates an unclear warning message.
The Users First Name field in Membership Authentication is a password field.
The Service Pack 3 and Service Pack 3a versions limit the number of entries in the Cookie Domain List field to four. If more than four entries are used, the gateway component does not start.
Missing choice value (CVal) key value pairs in the iwtAuthCert.properties file, and spaces in the keys in the iwtAuthCert.properties file prevent some translated strings from being displayed in the administration console. Instead, the strings are displayed in the default language, which is English.
The keys in the xml files and the .properties files do not match, so some translated strings are not displayed in the administration console. Instead, the administration console displays the strings in the default language, which is English.
Domain Admin Roles page shows incorrect listing of domain administration roles.
Wrong value is inserted upon creation of CSR if a blank field exists.
The LDAP authentication module fails when iDAR is interposed between the iPlanet Portal Server and the LDAP server.
If the user logs in as anonymous, then uses the Login provider to login in, the user will not be able to use the Netlet. The Netlet loads, but the following error message is displayed: "Unable to connect to Gateway: default:443."
A series of rapid logins and logouts (100 users at 3 minutes per user session), cause the authentication servlet to fail to read the domain profile. This eventually results in an HTTP 500 server error and a fairly large memory leak.
Authentication fails when the AuthCert module cannot find the CN in an issuer name.
Authentication time out returns the error message document contains no data instead of a message stating that the session timed out.
Login channel causes passwords to show up in Web Server's access log. For more information, see "Default Login Channel Templates Changes" in this document.
Authentication chaining fails when SecureID is the second authentication module.
Authentication fails when platform server is configured to use HTTPS.
certadmin self-signed certificate validity defaults to 90 days.
UNIX authentication fails when the server and the doUnix helper are out of sync.
The option to match the certificate in LDAP does not work if the certificate in the LDAP directory is stored as binary.
The Bookmark channel should be able to take a '|' symbol in the title field. Currently, the '|' symbol is used as dilimiter and does not recognize it as a regular character. The solution is to replace '|' symbol with '-' and store the title accordingly.
The JSPProvider channel can not set a cookie at the browser.
The current implementation of the JavaScript in the bookmarks channel causes saved bookmarks to be sent through the gateway by using the "/redirect" scheme even when unnecessary.
Internet Explorer caches Desktop content. If the user logs out and then selects the back button the Desktop is displayed. The links will not work, but the contents are visible.
If a bookmark is added with the same title and same URL as an existing one, it causes a server error.
The Tab edit button is displayed on the Desktop even when the Tab Provider is not editable.
Time zones on summer time should be indicated with an asterisk (*). According to the description of time zones on the User Information Channel, summer time is indicated with an asterisk (*), however, none of the time zones using summer time have asterisks.
The URLScraper channel does not pass the User-Agent information to the server from which it is making the request. In some cases, this header is needed to fulfill the request.
After the multi-profile fix, if the user changed the Layout Provider, many sync requests were generated. The amount of these requests causes a delayed response.
Internet Explorer caches content when the user sets the browser setting "Check for Newer Versions of stored pages" to "Never." This is because the Login Servlet does not set required Internet Explorer headers.
Cell padding around Tab Provider cannot be specified because of hard coded HTML in DesktopServlet.
Cell spacing cannot be specified in the main block of channels and providers.
Background color cannot be specified for main block of channels.
The iPlanet Portal Server 3.0 software does not provide the ability to maximize a provider. A provider can be minimized or restored, but cannot occupy the entire width of the Desktop without the presence of other providers.
A user who belongs to a non-default domain is taken back to the default domain's login page after a session timeout.
The Web server goes to sleep when the URLScraper is used to get SSL content.
The time zone setting in the User Information Provider cannot be updated.
High level caches are not updated when profile data changes, so changes in Desktop configuration are not synchronized across instances.
A multi-instance portal environment in which request handling is distributed by a load balancer that is not using sticky sessions causes changes in displayed channels to be undone by other instances.
Maximized channel with no content should display the message Content not available.
Edit Page of Netlet and Bookmark Provider can not be accessed after any one of the fields is deleted.
Entries with multiple sn and givenname do not display correctly in the User Info channel.
A URL scraped channel does not display JPEG files with a non-relative path.
The tab provider displays tabs in only right-to-left alignment. For more information, see "Tabbed Desktop" in this document.
The JSP provider cannot localize title or description. For information on the JSP Provider sample properties file, see "Localizing JSP Provider Titles and Descriptions" in this document.
Occasionally, the Desktop is displayed only after the entire timeout — the default timeout is 30 seconds.
Detaching all channels on the Desktop causes an unrecoverable error that makes the Desktop unusable.
Desktop provider does not catch throwable, resulting in a Desktop error page with the message A fatal error has occurred displayed in the channel window.
Some attribute strings for Desktop tabs are displayed in English for other locales.
Desktop logs expired or invalid sessions as an errors instead of warnings in the debug log files. This can debug files to grow unnecessarily large.
URLScraperProvider does not preserve backward compatibility.
Channel titles are always displayed in the language stored in the profile service.
Changes to TimeZone are not effective until user logs in again.
Changing to layout Option Four causes wide channels to be removed.
Selecting Open all pages in the Desktop when editing bookmarks causes the javaScript function openURL to call the server twice in the URL.
The Channel Wizard works incorrectly when an in-line channel is created if the iSyndicate connector is installed.
Weather provider templates should not be installed. The product does not contain a weather provider.
Content provider should check for null provider in content provider edit page creation.
The URL scraper failed when it tried to fetch a URL that resulted in a redirect.
URL rewriting did not work for relative URLs in URL scraper.
Removing a channel with thin-thick-thin layout caused null pointer.
The iPlanet Portal Server gateway POST request forwarding performance inefficient.
In some cases, CLOSE_WAIT sockets accumulate and never get closed.
If an HTML form action is inside document.write function and is broken into two or more statements, gateway doesn't understand it as a single tag and therefore doesn't rewrite it.
gateway prints debug messages to console for short connections because exception messages are printed to standard out and standard err, rather than using the Debug class.
The Gateway redirect option does not base its decision on gateway profile. The gateway attempts to fetch the response for a URL request without first checking to see if the gateway scheme is "redirect."
When the iPlanet Portal Server http proxy is enabled, and the gateway is used under heavy load with HTML pages containing a large number of images, it starts giving StackOverFlow Error and stops responding.
Wildcard support for JavaScript variables does not exist. For URLs and variables which may be dynamically generated, it is not possible to define a rule that applies to them all without being able to specify a wildcard for the entry in the Gateway Profile.
The rewriter ignores content between nested SPAN tags. Service Pack 3 Hot Patch 1 broke the rewriting functionality of content between the SPAN tags in order for Microsoft Exchange to work through the gateway.
URLs are not rewritten inside JavaScript while adding a menu item. If javascript variables like top.location were added to the Rewrite javascript variables in urls section, they do not get rewritten correctly because of the presence of location in the Rewrite Javascript varibales function section.
If the domain, and path are not explicitly set, they are not prepended to the cookie name when the gateway wraps the header up and sends it to the client. In some cases this causes problems maintaining uniqueness.
The gateway blindly rewrites source tags even if they are empty. An empty source tag can cause an error 404 to occur. Once a 404 error has been reported in the frame, it is no longer accessible to JavaScript functions.
The gateway incorrectly handles multiple Content-Length headers. The first value us rewritten with the new length after translation and appended to the end of the request. However, the Internet Explorer browser uses the first content-length header it encounters which would be smaller than the translated length, which causes the page sent back to the client to be truncated.
Pages redirected through the gateway should have the option not to be cached. When surfing pages through the bookmark provider or by specifying the redirected URL in the location field of the browser, the content can be cached on a local system.
Relative URLs with no prepended path information embedded in remote JavaScript are not rewritten correctly on import.
The option to disable client-bound Netlet traffic from extending iPlanet Portal Server session is needed.
If an HTML page is written in different parts using the document.write function, the rewriter may not understand all the attributes and tags correctly because of the quotation marks.
Cookies are not set while using http-proxy, if the domain is not the iPlanet Portal Server's domain.
If an applet archive tag has multiple jar files separated by commas, only the first archive tag is rewritten.
The iPlanet Portal Server gateway has a problem re-writing URLs when it sees a codebase directive with an applet tag. The gateway does not translate any other <a href directive correctly within the HTML file even though the codebase should only be in scope until the closing APPLET tag.
The rewriter should not automatically rewrite SRC tags the iPlanet Portal Server gateway does not understand.
The iPlanet Portal Server gateway passes different Content-Length: size in the HTTP header than the actual size. This happens only when the iPlanet Portal Server gateway sends HTTP/1.0 302 Moved Temporarily. The difference is one byte (the actual payload is bigger).
In some cases the iPlanet Portal Server gateway hangs under load. The java process does not die, and new connections are accepted, but no response is returned.
The applet getCodeBase call fails through the iPlanet Portal Server gateway if BASE HREF is commented out.
The iplanet function causes an error when rewriting JavaScript variables.
The rewriter has no option for specifying a JavaScript function parameter that is either a URL or JavaScript.
The iPlanet Portal Server gateway incorrectly rewrites JavaScript programming language containing the style tag.
Rules containing dotted separators cannot be used in the specified iPlanet Portal Server gateway profile section "rewrite javascript variables function."
If the URL specifies the protocol in upper case, the rewriter will not rewrite the URL. For example, only URLs starting with http are rewritten, and URLs starting with Http: or HTTP are not rewritten.
Using Outlook Web Access and Internet Explorer in combination, causes errors when the inbox is opened through the iPlanet Portal Server gateway.
Sometimes under load, the content character set is forced to be converted into other character set than one specified in header of the HTML.
Relative URLs are not rewritten correctly if the absolute URL used for the BASE HREF value does not contain any path information.
A defect in the logging service causes the iPlanet Portal Server gateway to hangs on DNS lookup.
The iPlanet Portal Server gateway encounters an error when the location header is all lower case.
The last scraped page's iplanet function will take precedence, and all other URLs in other scraped pages will use its requestPHP variable value to be rewritten.
Pages are not displayed correctly through the gateway. BASE tags containing a target attribute are commented out.
Unencoded Korean characters in the request URL are not handled properly when the LANG setting for the iPlanet Portal Server gateway is "Ko."
Requests to single or double level domain are not adhering to the HTTP proxy rules.
URL rewriting fails for JavaScript strings that extend across several lines.
The iPlanet Portal Server gateway does not correctly rewrite the META tag when putting the URL in quotation marks.
The iPlanet Portal Server gateway does not store basic authentication credentials when using httpproxy.
Applet Parameters are not rewritten if the code contains a line break.
The URLrewriter cannot rewrite cookie paths that contain an underscore (_).
When the rewriter needs to add the iplanet function to "Rewrite JavaScript Variable Function" and there is no <head> tag, the iplanet function is placed in the middle of the HTML code.
The iplanet function has the variable requrl, which is not defined. If the iplanet function is called with an already rewritten URL, it produces JavaScript error.
The iPlanet Portal Server gateway moves a server into the unavailable list when it is unable to make a single socket connection to that server. The gateway does not retry to make the connection.
Cookies are not rewritten correctly for an iPlanet Portal Server gateway that is installed in a top level domain.
The iplanet function does not check to see if variables are null. This affects the rewriting of variables in imported JavaScript in the Exchange interface.
The gateway automatically forwards requests for nonexistent domains, creating a unnecessary traffic and putting undue load on the Gateway.
If the gateway socket timeout is not set for the erproxy, denial of service attacks can occur.
The gateway translates special characters when rewriting XML, causing incorrect XML syntax.
When a style attribute is followed by a boolean attribute and a DOMstring attribute, the rewriter throws a string out of bounds exception.
The gateway does not handle implied tags. The rewriter inserts <HEAD></HEAD> tag in the wrong place if a pair does do not already exist.
The rewriter does not ignore comments that occur prior to opening XSL tag, which breaks the message multi-view functionality in Microsoft Exchange.
The gateway does not distinguish between base href internal and external URLs.
Outlook Web Access 2000 does not work out-of-the-box. See "Using Outlook Web Access 2000" in this document.
The gateway cannot handle cookies differing only in path. For more information, see "Desktop and Provider Changes" in this document.
JavaScript window.location.path value is not rewritten correctly.
The gateway component does not rewrite JavaScript variables that contain escaped double quotes.
Internal applications cannot be accessed because cookie domain rewriting does not use gateway domain or cookie domains list.
Internal applications that use URLs in which the file path starts with the word login cannot be accessed when using personal digital certificates (PDCs). iPlanet Portal Server redirects these URLs to the Desktop.
The gateway does not rewrite cookies correctly when used with the HTTP Proxy.
Re-submitted HTTP posts to foreign hosts by the gateway contain no data.
The gateway component does not handle pages correctly when lines end with line feed only.
iPlanet Portal Server 3.0, Service Pack 3 does not work with iPlanet Messaging Server 5.1.
The gateway component should not add default port number to re-written links.
The gateway rewrites src= tags when it is an SSL site and the site is not in the rewrite domain/subdomain list.
The gateway does not display a URL correctly unless / follows the hostname.
If the socket connection cannot be created, the gateway sends a 502 HTTP error code to the client indicating that the server is unavailable. For information about the addition of the isp.gateway.sockretries parameter, see "Setting the Number of Socket Connection Retries" in this document.
HTTP basic auth caching (SSO) fails when using server HTTP proxy.
Referer headers must be forwarded so servers can track the user's URL.
The ipshttpd script does not set the maximum number of file descriptors to a high enough value for the HTTP proxy process, causing the ipshttpd process to run out of file descriptors. When that happens, ipshttpd stops responding.
Users cannot authenticate with Internet Explorer, if hostname contains capital letters.
If the server and the gateway are installed on two different machines, the iwtGateway.properties file is not installed in basedir/SUNWips/locale directory of the server machine. The gateway-related strings are displayed in the default language, English, for foreign languages on the server machine.
The URL rewriter incorrectly rewrites relative URLs by using the document's URL instead of its instead of its base URL (indicated by the BASE tag).
In some cases the gateway or HTTP proxy would not respond due to CLOSE_WAIT sockets accumulating, and not getting closed.
If an applet is between <OBJECT> and </OBJECT>, the URL rewriter does not rewrite the URL.
The URL rewriter does not rewrite the applet parameter value if there is space between an HTML tag's parameter name and value.
URL Scraper and RSS channel providers fail when load balancing is active.
URLscraper does not handle the character set from Content-Type.
Internet Explorer 5.5 cannot display Webmail application when used with the gateway.
The gateway component should use JSS for talking to the platform server in HTTPS mode.
Gateway boot process hangs if the server is not started first.
Rewriter did not work if a URL had no leading http:// and no port number specified.
Rewriter for applet tags could rewrite only limited number of URLs in a parameter.
Upgrade script does not give executable permissions to the web server stop script.
The ipsinstall script displays false error messages about missing patches.
When using iPlanet Portal Server with iPlanet Web Server 4.1 Service Pack 11, an improperly formed request using chunked transfer encoding is received by the web server it can cause a buffer overflow.
Install needs to check disk space for installing Java packages. If Java packages don't get installed, the install script fails.
Stop script stops all slapd processes and all external LDAP server processes.
The installation script requires a fully qualified domain name (FQDN) with three parts (separated by two dots). It does not accept an FQDN with only one dot.
Installing gateway with profile server, using non-default port for SSL, sets port to 443.
Service Pack 3 image should not include jdk1.2.2_05 patches.
Installing profile server with a web proxy causes ipsserver to fail.
The command line utility ipsadmin returns invalid XML if the attributes value contains special characters. If the administrator tries to use this XML file it gives SAXParserException.
Unable to change user attribute values to null using ipsadmin.
After installing iPlanet Portal Server Service Pack 4, unnecessary messages were displayed on console when using ipsadmin for any profile changes.
Importing privileges after accessing the Policy page requires relogging to view.
ipsadmin -import converts new attributes in previously existing components to lower case and reports all attributes of new components as already existing. This bug is fixed in the iPlanet Directory Server 4.12 release.
ipsserver stop script kills all HTTPD processes running on the server. In doing so, it may also kill some external iPlanet Web Servers running on the server. The ipsserver stop command should stop only relevant processes.
Incorrect country code for Japan in the iwtUser.properties file.
On Japanese localization, NetFile Java did not work on Solaris and Windows NT.
With the release of the iPlanet Portal Server Service Pack 3 software, log records written using the Logging API were logging userID as authentication. This makes logging useless because there is no way to associate any entry with any user.
When logging is disabled, the log client still sends the log message.
Oracle jdbc driver does not re-initialize when the database cycles off and on.
NetMail sessions are not released when the user logs only out of the iPlanet Portal Server Desktop.
Installing NetMail locally on a Macintosh client will break on Macintosh clients running Internet Explorer.
Double-byte nickname entries in NetMail Lite address book are not supported.
In the NetFile application, the Return key should choose OK to avoid having to move the hand from the keyboard to the mouse.
An incorrect error is reported when creating an existing directory.
Users are able to add nonexistent shares. If a non existing share is added and you try to open the share, an error occurs and permission denied. If the share is not present, the user should not be allowed to add it.
Multiple files are mailed as copies of the same message with one attachment at a time. They should be mailed as multiple attachments.
Japanese files and folder names are not displayed correctly on NetFile and NetFile Lite, which makes the navigation and transfer of these directories or files impossible.
When mailing a file in NetFile using the Mail button, the From: address values are sourced and filled in incorrectly.
NetFile Truncates directory listings for subfolders if the number of listings is more than approximately 30.
File listing does not work for Windows NT FTP server host types. The file listing is not viewable although the file can be uploaded correctly.
When deleting a file with NetFile FTP, a messaging saying that the file has been Deleted is displayed, but the file is not actually deleted. This problem occurs if the user deleting the file is different from the file owner.
When saving a file from the NetFile applet on the Macintosh using Internet Explorer 5 or MRJ, the name NetFileServlet is used as the filename in the dialog box. The actual filename gets ignored.
When more than one user is specified in the To field, using a comma as a separator, mail is sent to only one user.
Mail sent from NetFile containing Japanese characters gets corrupted.
When downloading any files with Internet Explorer using NetFile, the file extension becomes .NetFile.
When a large number of files is selected and the Mail button is clicked, the Mail dialog opens and is displayed huge horizontally.
Internationalization: A warning message is displayed when uploading multi-byte files in Netfile.
Mail form field values in NetFile are not checked uniformly.
File names are not displayed when mailing multiple files from the NetFile Java application. File names are now displayed as a comma separated list.
Sending a blank email reply with the NetFile application causes the browser to spin indefinitely.
The window for displaying files on right side is too small. The file name window has been changed to allow 11 additional characters.
NetFile FTP connection method does not work properly with server components using multiple network interfaces. The PORT command uses the wrong IP address when sending data back to the client.
The Print and Save functions don't work in Netscape Navigator for files sent by NetFile.
The NetFile Lite application incorrectly displays compressed file names when using Windows NT hosts.
NetFile Lite behavior, under certain circumstances, can compromise password security.
NetFile Lite can display only one share for Windows systems.
NetFile Lite does not save changes to host information upon exiting and saving the session.
NetFile has problems displaying hidden shares that have been defined by the administrator.
NetFile shares that have been defined through ipsadmin can be added again through the NetFile application resulting in duplicate shares.
Using the host info menu in NetFile to edit host information, such as user name and password, removes the shares associated with that host.
NetFile assumes that a system is valid without verifying that the system exists. If the system to which NetFile tries to connect does not exist, the NetFile application eventually times out.
NetFile applet occasionally does not pass the sessionid to the servlet during a servlet call, resulting in a session exception that causes the log files to get unnecessarily large.
If the server's LANG setting specifies Japanese or Chinese locale, NetFile download functions for image, HTML, and executable files do not work.
If the server's LANG setting specifies Japanese or Chinese locale, NetFile upload functions for image, HTML, and executable files do not work.
NetFile mail functionality can overwrite iPortal Web Server configuration files.
NetMail was unable to receive mail with attached text file sent from NetFile.
If a dynamic netlet rule with target listening on different ports is specified, it does not work properly and the target is set only for the first port.
Netlet does not work on a Macintosh machine because it cannot resolve localhost. It needs the value 127.0.0.1 instead.
The ability to increase the session time out when the user is working with the Netlet should be configurable.
The Netlet cannot find a PAC file when it is specified using a file URL. For example: file://.
Large PAC files are truncated when content length is not explicitly set.
With Internet Explorer, the Netlet does not connect to the server after the user logs out and then logs in again.
Current idle time is constantly reset by the Netlet when the MaxCache time value has been exceeded.
Netlet does not support Netscape with PAC files. For more information, see "Installed Software Modules, Customizations, and Third-Party Products" in Chapter 2 of the iPlanet Portal Server Installation Guide.
Dynamic rules should be supported when using FTP through a Netlet connection.
Netlet does not support .ins files for Internet Explorer Configuration. For more information, see "Configuring Internet Explorer INS Files" in this document.
Netlet activity is not monitored and causes a session idle time out even when the Netlet is in use.
The port number is not stripped from the host name when evaluating a PAC file.
The autoproxy does not work when the autoconfig URL does not point directly to a file or redirect to a file. For instance, if http://domain_name:1001 is used an exception is thrown.
PAC files that contain evaluation entries based on the client IP address either fail or are evaluated incorrectly.
Netlet applet is hardcoded for a maximum of ten connections per rule.
The global encryption version of Netlet Applet incorrectly shipped with the domestic version of iPlanet Portal Server 3.0, Service Pack 3.
The request XML document for any service gets corrupted under a heavy load. The PLLRequestServlet does not read the XML document correctly.
Sizes of PLL Session threadpool are not configurable, which causes the server to hang in some cases.
A certificate error occurs when using an HTTPS connection when the VIP name does not match the server name.
After installing the iPlanet Portal Server Service Pack 3 Hot Patch 1 software, a profileException is thrown saying that attribute iwtGateway-responsedelay is not found.
After multi-server fix, if a suborole has modified content, and the administrator has changed the upper domain or role, the change is visible only on the server on which the change was made. The change is not visible on the other platform servers.
If the iPlanet Portal Server software is configured to run SSL in open portal mode on port 80, users are not able to see the Desktop on Internet Explorer. Netscape works fine.
A single write operation produces a large number of LDAP reads.
The Profile service issues excessive requests for the domain list.
Unnecessary LDAP reads occur if a request has no iPlanet Portal Server cookie.
A single Desktop reload causes multiple sessionservice requests.
Every time a user logs in to the portal, the profile server receives an LDAP request.
Every time a user with a profile that is not already cached logs in, two LDAP requests are issued for their profile in immediate succession. Since user profiles are cached, only one request should be necessary.
Profile server should be able to reconnect to the LDAP server.
ipsadmin has wrong content type for UpdateProfileCache request.
Profile API returns valid profile object for non existing profiles.
Domain search did not search for users mapped from external LDAP. The search limit for external LDAP users is 400 users only.
External LDAP attribute mappings did not work with binary type attributes.
The steps to add a gateway are documented incorrectly in the iPlanet Portal Server 3.0 Administration Guide. For correct instructions, see "Adding a Gateway After Installation" in this document.
Document required disk space for /var; /etc; /opt; and installation directory.
Portal Server and gateway components on a single computer must use the same install directory.
Correct instructions for adding iwtTabProvider in selected channels.
Documentation Updates
This section provides information that supplements the iPlanet Portal Server Administration Guide. Topics include:
- Non-Portal Server Cookie Management
- Certificate Management for the Gateway
- Adding a Gateway After Installation
Documentation for iPlanet Portal Server is at this Web site:
http://docs.iplanet.com/docs/manuals/portal.html
Gateway Profile Attributes
Table 14 is a two column table that lists the gateway profile attributes. The first column contains the attribute name, and the second column provides a brief description of each attribute.
For more detailed information on configuring the gateway, see the iPlanet Portal Server Administrator's Guide 3.0 at:
For detailed information specifically related to rewriter configuration, see the Sun™ONE Portal Server 3.0 Rewriter Configuration and Management Guide at:
http://www.sun.com/solutions/blueprints/
Attribute
Attribute Description
Allow connections to the gateway from browsers that only support weak (40 bit) encryption.
List of FORM tag attributes that get rewritten. The FORM tag attribute ACTION gets rewritten out of the box. Other attributes that might need to be added are INPUT and SELECT.
object_of_url_with_form form_name input_or_option_name [url_pattern]
If this attribute is set to true, the Gateway will rewrite any URL without checking the URLs subdomains and domains against entries in DNS Domains and Subdomains list.
List of gateways that require authentication by Personal Digital Certificate.
Web sites may be protected with HTTP Basic Authentication, requiring visitors to enter a username and password before viewing the site (the HTTP response code is 401 and WWW-authenticate: BASIC). Sun ONE Portal Server can save the username and password so that users need not re-enter their credentials when they revisit BASIC-protected web sites. These credentials are stored in the user profile on the Sun ONE Directory Server.
Sun ONE Portal Server utilizes a cookie to track user sessions. This cookie is forwarded to the server when the gateway makes HTTP requests to the server (for example, when the desktop servlet is called to generate the user's desktop page). Applications on the server use the cookie to validate and identify the user.
The Portal Server's cookie is not forwarded to HTTP requests made to machines other than the server, unless URLs on those machines are specified in the Forward Cookie URL Lists. Adding URLs to this list therefore enables servlets and CGIs to receive the Portal Server's cookie and use the APIs to identify the user.
Specifies whether cookies get rewritten and restored.
If false, cookies are forwarded, but not rewritten or restored
Specifies whether a Web Proxy is to be used. If a web proxy is specified in the DNS Domains and Subdomains list, the gateway checks this attribute.
This checkbox can be used in conjunction with:
If this box is checked, the Don't Use Web Proxy Enabled list can be used to add URLs that do not get proxied, but are contacted directly.
If the box is not checked, the Use Web Proxy Enabled list can be used to add URLs that do get proxied.
List of URLs that get proxied when the Use Intranet Web Proxy attribute is set to false.
List of URLs that do not get proxied when the Use Intranet Web Proxy attribute is set to true.
List of HTML attributes that contain URLs to be rewritten by the gateway. If an attribute in this list contains a URL, that URL will be rewritten.
These entries tell the gateway what web proxy (if any) to use when contacting specific subdomains in specific domains.
If Use Intranet Web 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 from the Proxies for Domains and Subdomains list.
If a web proxy is not indicated for the target URL through the DNS Domains and Subdomains list as described above, the gateway will connect to the destination host directly.
If a web proxy is indicated, the gateway will check the attribute Use Intranet Web Proxy.
Rewrites PCDATA. Add the tag name to the Rewrite Text data of XML document section. If the PCDATA is dependent on the tag attribute values, both the tag name and the attribute definition need to be added to the Rewrite Text Data of XML Document profile section.
Pre-populated with the entries required for Outlook Web Access 2000 to work through the gateway.
Used to rewrite XML values that contain URLs. Add a rule that contains the attribute name.
Pre-populated with the entries required for Outlook Web Access 2000 to work through the gateway.
Note: To differentiate specific tag names containing the same attribute names from having their values rewritten, specify a rule with the syntax attrName,tagName
Used for event handlers (HTML attributes that contain JavaScript whose values will attempt to be translated as URLs).
List of JavaScript function parameters to be rewritten. Used to rewrite document object methods. If the URL is a raw URL, then the function name can be added to the Rewrite JavaScript Function Parameters section of the gateway profile.
If the content is passed through the gateway that contains a call to a method, where the first parameter is not a raw URL, then the method would have to be moved from the default section of the gateway profile to the Rewrite JavaScript Function Parameters Function section.
List of JavaScript variables. The gateway rewrites the value of the URL that is assigned to the JavaScript variable. Used to rewrite document object properties.
Used to rewrite built-in JavaScript variables for which a relative URL is required, rather than translating its value into an absolute URL. location.pathname for instance should only specify the path portion of a URL.
Entries in this section of the gateway profile will likely be sparse, but this section can be useful if the content defines its own object rather than using the window object.
Used to rewrite JavaScript variables. If a JavaScript variable is used instead of a raw URL, the Rewrite JavaScript Variables Function inserts a function called iplanet within the SCRIPT tag and changes the variable name on the right side of the variable assignment to iplanet(variable_name).
Used to rewrite browser object methods that contain URLs. If the content is passed through the gateway that contains a call to a method, where the first parameter is not a raw URL, then the method would have to be moved from the default section of the gateway profile to the Rewrite JavaScript Function Parameters Function section.
An iplanet function is defined and the variable, or parameter in this case, is then wrapped within an iplanet function call.
The gateway will rewrite the HTML in the parameters of the JavaScript function if there is a match.
Used to rewrite URLs in nested JavaScript. Lets the rewriter know that the first parameter of the function call contains JavaScript content. So, the rule must be added to the Rewrite JavaScript Function Parameters in JavaScript section of the gateway profile.
Used in conjunction with the Rewrite JavaScript Function Parameters section. The rule must be also be added to the Rewrite JavaScript Function Parameters section.
Used to rewrite dynamically created HTML blocks. If an attribute is created dynamically by the client rather than passing through the gateway, which would normally translate the attribute value (the JavaScript variable that contains HTML to be rewritten requires a rule in the Rewrite JavaScript Variables in HTML section).
Used when rewriting JavaScript content for statements whose right side contains variable initializations that could have a right side that is a URL string literal. For the URL to be rewritten correctly, a rule address needs to be added to the Rewrite JavaScript Variables in URLs section of the gateway profile,
Used to rewrite Applet and Object attributes that contain URLs. The attributes ARCHIVE and CODEBASE are rewritten out-of-the-box.
object_of_applet/object_url applet_class/object_classid applet/object_parameter_name [url_pattern]
Specifies the time interval in milliseconds after which the gateway times out its connection with the browser.
This section is suitable for search, rewrite, and replace applications where JavaScript language dynamically creates HTML through multiple document.write function calls.
The rule is in the form of a URL pattern.
For more information see the section "Advanced Rewriter Concepts"
Specifies the MIME type. This section extends the rewriter functionality to other MIME types.
Specifies the maximum number of threads that can be pre-created in the gateway thread pool.
Rewrite JavaScript Function Parameters in JavaScript or a URL
Used when JavaScript functions do not differentiate the context of what can be passed to the function as a parameter. This section allows for some ambiguity in rewriting JavaScript function parameters. Specifically, when rewriting JavaScript function parameters that are themselves either JavaScript or a URL.
java_script_function_name: [y|], [y|], ...
For more information see the section, "Advanced Rewriter Concepts"
If this is disabled, only client activity on netlet connections extend the portal session (stop it from timing out). This is to avoid server side applications that send regular hello packets from keeping the session active when the user has abandoned it. However, some administrators may wish server side data to extend the session so that they can access system management or monitoring applications for which user interaction is relatively minor.
The port number on which all gateway instances registered against this profile server listen.
The protocol (HTTP or HTTPS) that all gateway instances registered against this profile server use.
Specifies that some URLs do not need any authentication. These are normally directories and folders that contain images.
List of hostnames with SSL certificates that are trusted, even if the certificate can not be verified.
If the http proxy is enabled, the gateway will send HTTP requests to the HTTP proxy instead of directly to the destination host. The HTTP proxy will then send the request to destination server.
The port number on which the HTTP Proxy (if enabled) listens
Enable proxying by the platform server of netlet traffic from the gateway to the target system. This avoids the need for internal systems accessed by the netlet to be directly reachable from the gateway.
The port number on which the Netlet Proxy (if enabled) listens.
Enable logging of connections made to the Gateway on the platform server via the logging service.
Non-Portal Server Cookie Management
The iPlanet Portal Server Administration Guide 3.0 currently states the following:
The actual behavior of the non-portal server cookie management feature is to allow or prevent cookies from being rewritten and restored. Cookies set by the application server are not discarded when the option is set to false.
The non-portal cookie management feature handles cookies in the following manner:
- Forward, but not rewrite or restore the cookie if this attribute is set to "false"
- Rewrite the cookie using the Gateway's domain and forward the cookie if this attribute is set to "true"
This means that if the cookie is set from a different domain than that of the Gateway, and the non-portal server cookie management attribute is set to true, the Gateway will rewrite the cookie's domain and the browser will accept it. When the cookie is returned to the application, the Gateway will restore the cookie's original domain.
By setting this attribute to false, the Gateway does not rewrite the cookie. If the cookie is set from a different domain, the browser will not recognize it and will, therefore, reject the cookie. However, if the cookie is sent from the same domain as that of the Gateway, the browser will recognize the cookie as a valid cookie and will store it, even if the non-portal server cookie management attribute is set to false.
If this feature is enabled and later disabled, a cookie that has been previously set will not be restored to its correct domain when it is sent back to the application server.
Note
Certificate Management for the Gateway
SSL certificate management changes have changed information for SSL certificates for the gateway component presented in Chapter 11 of the iPlanet Portal Server3.0 Administration Guide and Appendix A of the original iPlanet Portal Server 3.0 Installation Guide.
The following information replaces the existing documentation on SSL certificates for the gateway.
Documentation about certificates for the iPlanet Portal Server server component still applies.
Note
Understanding SSL Certificates
The certadmin script in installation_directory/SUNWips/bin/ wraps around the ipscertutil command for convenience and consistency with previous certificate administration. The certadmin script should satisfy the conventional needs of certificate administration. For additional functions, use the ipscertutil command directly. For example, use ipscertutil to delete a certificate from the certificate database. The command ipscertutil -H lists use.
Certificate-related files are located in /etc/opt/SUNWips/cert. Three of the five certificate files, cert7.db, key3.db, and secmod.db, are binary files containing data for certificates, keys, and cryptographic modules. These files can be manipulated implicitly by using the certadmin script.
These binary files have the same formats as the database files used by iPlanet Web Server. They are located in installation_directory/netscape/server4/alias. If necessary, they can be shared between the iPlanet Portal Server server and gateway components or the HTTP proxy.
The other two certificate files are hidden text files: .jsspass and .nickname. The .nickname file stores the names of the token and certificate that gateway currently uses, in the form of token_name:certificate_name. If using the default token (the token on the default internal software encryption module), omit the token name. In most cases, only the certificate name is stored in .nickname file.
The .jsspass file contains the password for the encryption module that iPlanet Portal Server gateway currently uses. The default module is the internal software module.
During the installation of the iPlanet Portal Server gateway component, a self-signed SSL certificate is created and installed. If necessary, use the certadmin script to do additional certificate administration.
Generating a Self-Signed SSL Certificate for the Gateway Component
Administrators use the certamin script to generate a self-signed certificate for the gateway. To do this, complete the following steps:
-
As root, run the certadmin script. The following example assumes that /opt is the installation directory.
- Select 1 from the Certificate Administration menu to generate a self-signed certificate.
-
When Certificate Administration script asks if you want to keep the existing database files, select whether to keep the existing certificate database files.
-
When a self-signed certificate is generated and the prompt returns, use these commands to restart the gateway component for the certificate to take effect:
# /opt/SUNWips/bin/ipsgateway stop
# /opt/SUNWips/bin/ipsgateway start
Multiple certificates can be stored in the database files. The one that the gateway component uses is identified by the .nickname file. You can edit this file to switch to a different existing certificate.
Obtaining and Installing an SSL Certificate from a Certificate Authority
During installation of the gateway component of the Portal Server product, a self-signed certificate is created and installed. At any point after installation, you can install SSL certificates signed either by vendors who provide official certificate authority (CA) services or by your corporate CA.
Three main steps are involved in this task.
- Generating a Certificate Signing Request (CSR)
- Using the CSR to Order a Certificate from a CA
- Installing the Certificate from the CA
Generating a Certificate Signing Request (CSR)
To generate a certificate signing request, complete the following steps:
-
As root, run the certadmin script. The following example assumes that /opt is the installation directory.
- Select 2 from the Certificate Administration menu to generate a certificate signing request (CSR).
-
Provide the organization-specific information that the script asks for.
Note The webmaster's email and phone number are required.
A CSR is generated and stored in the file /tmp/csr.hostname and is printed to the screen so that you can copy and paste it.
Using the CSR to Order a Certificate from a CA
To use the certificate signing request to order a certificate from a certificate authority, complete the following steps:
- Go to the Certificate Authority's Web site and order your certificate.
- Provide the CSR from the last step, as requested by the CA.
- Provide other information, if requested by the CA.
- After you receive your certificate from the CA, save it in a file.
The following example omits the actual certificate data.
Include both the BEGIN CERTIFICATE line and the END CERTIFICATE line with the certificate in the file.
Note
Installing the Certificate from the CA
To install the certificate from the CA in your local database files in /etc/opt/SUNWips/cert, complete the following steps:
-
As root, run the certadmin script. The example assumes that /opt is the default location.
-
Select option 4 from the Certificate Administration menu to install your certificate from the CA.
-
The script asks you to enter certificate file name, certificate name and token name.
What is the name (including path) of file that contains the certificate?
Please enter the token name you used when creating CSR for this certificate []
-
-
When the script asks you to enter certificate file name, certificate name and token name, provide this information.
Tip Once the certificate is installed in /etc/opt/SUNWips/cert, the screen prompt returns.
-
Use these commands to restart the gateway component so that the certificate takes effect:
# /opt/SUNWips/bin/ipsgateway stop
# /opt/SUNWips/bin/ipsgateway start
Adding a Root CA Certificate
When the gateway is an SSL client, importing a root CA certification into the gateway's certificate database enables the gateway component to communicate with an Internet or an intranet HTTPS site. If the root certificate is not in the gateway's certificate database, the gateway component does not recognize the server's CA certificate, and the SSL handshake fails.
To import a root CA certificate into the gateway component's certificate database, complete the following steps:
-
As root, run the certadmin script. The example assumes that /opt is the default location.
- Select option 3 from the Certificate Administration menu to add the root CA certificate.
- When the script asks for the name of the file that contains the root certificate, provide this information.
If the gateway component is set up to communicate with an HTTPS site that presents a self-signed certificate, allowing the gateway component to trust any unknown CAs can be useful. However, this approach must be used with caution. See "Denying Unknown Certificate Authorities" for more information on configuring the gateway component.
Most well-known public certificate authorities are already included in the certificate database.
Tip
Viewing the Public CA list
To view the list of Public CAs, compete the following steps:
-
As root, run the certadmin script. The example assumes that /opt is the default location.
- Section option 6 from the certificate administration menu to display all root CA certificates.
Table 15 is a two column table that displays all public certificate authorities included in the certificate database by default. The first column contains the Certificate Authority name, and the second column lists heir trust attributes.
For information on modifying the trust attributes of a public CA, see "Modifying Trust Attributes of a Certificate."
Modifying Trust Attributes of a Certificate
The trust attributes of a certificate provide information about whether the certificate is a regular server certificate (also called user certificate) as opposed to a root certificate, and whether the certificate (in the case of a root certificate) can be trusted as the issuer of a server or client certificate.
Three trust categories are available for each certificate: SSL, email, and object signing. In the context of the gateway component, only the first category is useful. In each category position, zero or more attribute codes are used.
Table 16 is a two column table that lists the certificate trust attributes. The first column lists the possible attribute values, and the second column provides a description of that attribute.
Attribute codes for the categories are separated by commas, and the entire set of attributes is enclosed by quotation marks. For example, the self-signed certificate generated and installed during the gateway installation is marked u,u,u to designate that it is a server certificate (user certificate), as opposed to a root CA certificate.
Viewing Trust Attributes
You can use the certificate administration script to view all certificates and their corresponding trust attributes.
To view the trust attributes of a certificate, complete the following steps:
-
As root, run the certadmin script. The example assumes that /opt is the default location.
- Select option 7 from the certificate administration menu to list all certificates.
Setting the Trust Attribute for a Certificate
The trust attributes of a certificate must be modified if client authentication is used with the gateway.
An example of client authentication is PDC (Personal Digital Certificate) as described in Chapter 6 of the iPlanet Portal Server 3.0 Administration Guide. The CA that issues the PDCs must be trusted by the gateway. For example, the CA certificate should thus be marked T for SSL.
To set the trust attribute for a certificate, complete the following steps:
-
As root, run the certadmin script. The example assumes that /opt is the default location.
- Select option 5 from the certificate administration menu to change a certificate's trust attributes.
- When the script asks for the name of the certificate, provide this information. For example: Thawte Personal Freemail CA.
- When the script asks for the certificate's trust attribute, provide this information. For example: CT,CT,CT (in this case, this is the default new value, so you just need to select Enter)
Once the certificate trust attribute is changed, the gateway recognizes client certificates signed by that certificate authority.
Adding a Gateway After Installation
The first two steps in the procedure "To Add a Gateway After Installation" in the iPlanet Portal Server Administration Guide are incorrect. The correct procedure for adding a gateway after installation is described here.
To add a gateway after you install Portal Server, complete the following steps:
- Select Server Management on the administration console menu.
-
Select Manage Server Profile.
- Scroll to the Gateway List attribute box.
- Type the fully qualified host name of the new gateway in the field below the attribute box.
-
Select Add to add the gateway.
-
The new gateway uses the default platform values for gateway port number, name of platform profile, retry interval, and default domain.
-
-
If the added gateway is on a different domain from the iPlanet Portal Server, scroll to the Cookie Domain List field and enter the new gateway domain name in the field.
-
For example, if the new gateway host name is host1.domain1.com and the iPlanet Portal Server host name is host2.domain2.com, then domain1.com is added to the Cookie Domain List attribute.
-
- Select Add.
- Select Submit to create the new gateway. A message that the profile was successfully updated is displayed.
- Select Continue.
- Select Manage Domains to add new gateway URLs so that the user can log in from the gateway.
- Select the domain desired to give access to the new gateway to open its Domain, Role and Users page.
- Select the Authentication link.
- Scroll to the Domain URLs List window attribute and type the gateway host name in the field.
- Select Add. Additional forms of the URL are also added to this list as indicated by the following steps.
-
Type the IP address of the new gateway.
- Select Add.
-
Type the URL in the form of gateway_ipaddress/gateway_domain.
- Select Add.
-
Enter the URL in the form of /gateway_domain.
- Select Add.
- Select Submit. The Profile Successfully Updated message is displayed.
- Select Continue and repeat Step 11 through Step 21 for any other domains that require access to the new gateway.
- From the administration console home page, select the Server Management link from the left frame.
- Select the server name associated with the added gateway and select Restart Servers. The prompt, Restart request had been sent to the servers, is displayed.
- Select Continue to return to the Server Management page.
How to Report Problems
If you have problems with iPlanet Portal Server, contact iPlanet customer support using one of the following mechanisms:
-
iPlanet online support Web site at http://www.iplanet.com/support/online/
- The telephone dispatch number associated with your maintenance contract
So that we can best assist you in resolving problems, please have the following information available when contacting customer support:
- Description of the problem, including the situation where the problem occurs and its impact on the operation
- Machine type, operating system version, and product version, including any patches and other software that might be affecting the problem
- Detailed steps on the methods used to reproduce the problem
- Any error logs or core dumps
Where to Find More Information
- iPlanet Portal Server release notes and other documentation — http://docs.sun.com/db/prod/sunone