9.2 Upgrading from Access Manager 3.0 SP4 to Access Manager 3.1 SP2

For the 3.0 support packs, we recommended that you upgrade all Access Manager components at the same time. The 3.1 SP2 upgrade process has been modified so that you can upgrade a cluster of components rather than all components. For example, you can upgrade your Administration Consoles, then wait a few days before upgrading the Identity Servers. You should not use the new 3.1 SP2 features until all components have been upgraded to 3.1 SP2.

IMPORTANT:Your Access Manager components must be running 3.0 SP4 to upgrade to 3.1 SP2. If they are running an earlier version, you must first upgrade them to 3.0 SP4.

The following steps outline the order in which you should upgrade the components. It is the only order that has been tested, and Novell strongly recommends that you take this approach. If you experience problems, Novell Support might request that you restore a backup on the previous version. Make sure you have a current backup. For instructions, see Backing Up the Access Manager Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

J2EE Agents cannot be upgraded from 3.0 SP4 to 3.1 SP2. To use the agents in 3.1 SP2, you need to perform a clean install of the agents.

We recommend that you use the following schedule as you upgrade to 3.1 SP2:

If a component fails to upgrade successfully, see Section 9.2.8, Troubleshooting a Failed Upgrade for a solution.

9.2.1 Before Starting the Upgrade

  1. Make sure all components are upgraded to at least 3.0 SP4:

    1. In the Administration Console, click Access Manager > Auditing > Troubleshooting > Version.

    2. Verify that your components are running the following versions:

      Component

      Access Manager 3.0 SP4 Version Number

      Administration Console

      3.0.4.38 through 3.0.4.69

      Identity Server

      3.0.4.38 through 3.0.4.69

      Linux Access Gateway

      3.0.4.38 through 3.0.4.69

      NetWare Access Gateway

      3.0.503

      J2EE Agents (all versions, all platforms)

      3.0.4.38

      SSL VPN

      3.0.4

  2. Back up your system.

    For instructions, see Backing Up the Access Manager Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  3. Back up customized Tomcat files on your Access Manager components.

    If you have customized the tomcat4.conf file or the server.xml file, back up these files before upgrading. These files are overwritten during the upgrade process.

  4. Back up the custom configuration files that you have created for your Identity Server:

    • Back up any customized JSP pages and related files. The upgrade process replaces any custom JSP pages that have the same filename as the JSPs that ship with the product.

      The JSP files are located in the /var/opt/novell/tomcat5/webapps/nidp/jsp directory.

    • If you are using Kerberos, back up the bcsLogin.conf and keytab files.

      These files are located in the /opt/novell/java/jre/lib/security directory.

  5. Verify the operating system version of your Administration Consoles and Identity Servers.

    • If you have any Administration Consoles running on SUSE Linux Enterprise Server (SLES) 9, upgrade the operating system to SLES 10 or SLES 11.

      For instructions, see Upgrading the Administration Console to SLES 10 or SLES 11.

    • If your machine is running SLES 10 SP1, upgrade to SLES 10 SP2 or SP3.

    • If your machine is running on SLES 10 SP2, you can upgrade to 3.1 SP2 before upgrading the operating system to SLES 11.

  6. If you have installed a previous version of the Administration Console or the Identity Server on a machine that does not have at least 1 GB of memory, the upgrade to SP2 fails. You need to install more memory before upgrading. This upgrade check is below the recommended minimum of 4 GB.

    If you prefer to install on a new machine rather than adding more memory to an old machine, see Moving the Primary Administration Console to New Hardware in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  7. If you have changed the password of the Tomcat keystore on an Administration Console that isn’t installed with an Identity Server, you need to change the password back to the default password.

    1. Change to the /var/opt/novell/novlwww directory.

    2. Use the keytool utility to change the password in the .keystore file to changeit.

  8. If you have installed the high bandwidth version of the SSL VPN server and the server is installed with another Access Manager component, install the SSL VPN High Bandwidth Key.

    When you upgrade components on machines that have multiple Access Manager components installed, all components are automatically upgraded. If you have not installed this key, your SSL VPN server reverts to a low bandwidth version.

    1. Log in to the Novell Customer Center and download the high bandwidth key.

    2. Copy the RPM to your SSL VPN machines.

    3. Use the following RPM command to install it:

      rpm -ivh <rpm-name>

      Replace <rpm-name> with the name of the SSL VPN High Bandwidth Key.

  9. If you have configured the Identity Server to send attributes to the Access Gateway, decide on an upgrade strategy for a potential issue.

    If any of the attributes you are sending have empty values, users cannot authenticate until you have upgraded all your Identity Servers and Access Gateways to SP2 or you have disabled the sending of attributes until you have upgraded all components. For more information about this issue, see TID 7005475.

  10. If you have any NetWare Access Gateways, export their configuration.

    The NetWare Access Gateway is not supported in 3.1 SP2. As soon as you upgrade the Administration Console, the only option available for the NetWare Access Gateway is to export its configuration. For information on how to convert a NetWare Access Gateway to a Linux Access Gateway Appliance, see Section 9.11, Converting a NetWare Access Gateway.

  11. Continue with Section 9.2.2, Upgrading the SP4 Administration Consoles.

Upgrading the Administration Console to SLES 10 or SLES 11

  1. Make a note of the hostname, IP address, and the version of the installed primary Administration Console.

    When you re-install the Administration Console, you need to install this version using the same hostname and IP address.

  2. Back up your system.

    For instructions, see Backing Up the Access Manager Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  3. Move the backup configuration file to a different machine.

    If you are going to re-install on the same machine, all data on the machine is lost. If you install on new hardware, the old machine must be removed from the network.

  4. (Conditional) If an Identity Server is installed on the same machine as the Administration Console:

    1. Remove the Identity Server from the L4 switch configuration.

    2. Remove the Identity Server from the cluster configuration.

    3. Back up any customized files on the Identity Server.

  5. (Conditional) If you are planning to install the primary Administration Console on new hardware, down the existing primary Administration Console and remove it from the network.

  6. Perform a fresh installation of SLES 10 or SLES 11.

    An operating system upgrade is not recommended. If you select to perform an operating system upgrade, you need to perform an additional task. See Section A.8.1, After You Upgrade from SLES 9 to SLES 10, Access Manager 3.1 SP2 Fails to Install.

  7. Make sure the following packages are installed:

    • gettext: The required library and tools to create and maintain message catalogs.

    • python (interpreter): The basic Python object-oriented programming package.

    • compat: Libraries to address compatibility issues. On SLES 11, the compat-32bit package is available in the SLES11-Extras repository. For information on enabling this repository, see TID 7004701.

    Use YaST to install the packages.

    Use the following command to verify:

    rpm -qa | grep <package name>

  8. Copy the backup configuration file to the machine.

  9. Copy the required version of the installation file to the machine and extract it.

  10. (Conditional) If you are upgrading from SLES 9 to SLES 11, modify the install.sh script.

    For instructions, see Modifying the Installation Script for SLES 11.

  11. Remove this machine from the network.

    NOTE:This step is required to avoid any traffic from the remote devices to this Administration Console in the current state. This also avoids any conflict between the eDirectory tree names of the primary and secondary Administration Console.

  12. Install primary Administration Console.

    For instructions, see Installing the Access Manager Administration Console.

  13. Restore your configuration.

    For instructions, see Restoring an Administration Console Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  14. Open iMonitor on the primary Administration Console:

    1. Enter the following URL:

      https://<ip-address>:8030/nds

      Replace <ip-address> with the IP address of your Administration Console.

    2. Disable the eDirectory outbound and inbound synchronization for 24 hours.

      For more information, see “Enabling/Disabling Normal Synchronization” in the eDirectory documentation.

  15. Connect this machine to the network so that the primary Administration Console is visible to all the devices.

  16. (Conditional) If an Identity Server was installed on the same machine as the Administration Console:

    1. Install the same version of the Identity Server that matches the Administration Console version.

      For instructions, see Installing the Novell Identity Server.

    2. Restore any customized files to the Identity Server.

    3. Add the Identity Server to the cluster configuration.

    4. Add the Identity Server to the L4 switch configuration.

  17. If you have secondary Administration Consoles running on SLES 9, down these secondary consoles.

  18. Re-enable eDirectory synchronization on the primary Administration Console:

    1. Enter the following URL:

      https://<ip-address>:8030/nds

      Replace <ip-address> with the IP address of your primary Administration Console.

    2. Enable the outbound and inbound synchronization.

      For more information, see “Enabling/Disabling Normal Synchronization” in the eDirectory documentation.

  19. Check the health of all devices to ensure they are working fine.

  20. Select one of the following:

    If you have secondary Administration Consoles running on SLES 9, continue with Upgrading Secondary Administration Consoles to SLES 10 or SLES 11.

    If you have finished migrating Administration Consoles to a new operating system, continue with Section 9.2.2, Upgrading the SP4 Administration Consoles.

Upgrading Secondary Administration Consoles to SLES 10 or SLES 11

  1. In the Administration Console, click Auditing > Troubleshooting.

  2. In the Other Known Device Manager Servers section, use the Remove button to remove any secondary consoles.

  3. (Conditional) If an Identity Server was installed on the same machine as a secondary Administration Console:

    1. Remove the Identity Server from the L4 switch configuration.

    2. Remove the Identity Server from the cluster configuration.

    3. Back up any customized files on the Identity Server.

  4. Install SLES 10 or SLES 11.

  5. Make sure the following packages are installed:

    • gettext: The required library and tools to create and maintain message catalogs.

    • python (interpreter): The basic Python object-oriented programming package.

    • compat: Libraries to address compatibility issues. On SLES 11, the compat-32bit package is available in the SLES11-Extras repository. For information on enabling this repository, see TID 7004701.

    Use YaST to install the packages.

    Use the following command to verify:

    rpm -qa | grep <package name>

  6. Reinstall the secondary consoles to the same version you used for the primary Administration Console.

    If you are installing on SLES 11, make sure to use the modified install.sh file.

  7. (Conditional) If an Identity Server was installed on the same machine as the secondary Administration Console:

    1. Install the same version of the Identity Server that matches the Administration Console version.

      For instructions, see Installing the Novell Identity Server.

    2. Restore any customized files to the Identity Server. For more information on restore, see Restoring an Identity Server in the Novell Access Manager 3.1 SP2 Administration Console Guide.

    3. Add the Identity Server to the cluster configuration.

    4. Add the Identity Server to the L4 switch configuration.

  8. Continue with Section 9.2.2, Upgrading the SP4 Administration Consoles.

Modifying the Installation Script for SLES 11

The Access Manager 3.0 SP4 installation script (install.sh) for the Administration Console verifies that the operating system is SLES 9 or SLES 10. To modify the script so that you can install the Administration Console on SLES 11, you need to modify three lines in the file:

  1. Find the following line in the file. If your editor numbers the lines, it is line 815.

     if [ "$VERSION" -lt 9 -o "$VERSION" -gt 10 ]

  2. Replace this line with the following:

    if [ "$VERSION" -lt 9 -o "$VERSION" -gt 11 ]

  3. Find the following line in the file. If your editor numbers the lines, it is line 1064.

    if grep "IPADDR=\('\?\)${CHK_ADDR}\1" "${CFG_FILE}" > /dev/null 2>&1

  4. Replace this line with the following two lines:

     grep ${CHK_ADDR} "${CFG_FILE}" | grep "IPADDR=" > /dev/null 2>&1
      if [ $? -eq 0 ]

  5. Find the following line in the file. If your editor numbers the lines, it is line 1066.

    if grep "BOOTPROTO=\('\?\)static\1" "${CFG_FILE}" > /dev/null 2>&1

  6. Replace this line with the following two lines:

    grep "static" "${CFG_FILE}" | grep "BOOTPROTO=" > /dev/null 2>&1
     if [ $? -eq 0 ]

  7. Save the file.

    You can use this modified script to install the 3.0 SP4 version of the Administration Console and the Identity Server on SLES 11.

    IMPORTANT:This should only be used as a temporary setup while upgrading to 3.1 SP2.

  8. Continue with Step 6 in the “Upgrading the Administration Console to SLES 10 or SLES 11”section.

9.2.2 Upgrading the SP4 Administration Consoles

The primary Administration Console must be the first device that is upgraded to 3.1 SP2.

If an Identity Server or an SSL VPN server is installed on the same machine as the Administration Console, these devices are automatically upgraded at the same time as the Administration Console.

  1. (Conditional) If you have an Identity Server installed on the same machine as the primary Administration Console, modify the L4 switch so that no traffic is sent to this Identity Server.

    When the Identity Server is taken offline for the upgrade, any users logged into this server are seamlessly transferred to another server.

  2. Upgrade the primary Administration Console.

    For upgrade information, see Section 9.6.1, Upgrading the Linux Administration Console.

  3. Before logging into the 3.1 SP2 Administration Console, clear your browser cache.

  4. (Conditional) If the machine contains an SSL VPN server, it was automatically upgraded with the Identity Server. To determine what needs to be done next, see Section 9.2.6, Upgrading the SP4 SSL VPN Servers.

  5. If the machine contains just an Administration Console or an Administration Console and an Identity Server, upgrade any secondary consoles.

  6. Verify that the system is in a manageable state. All devices should display green as their health state.

    You should be able to edit the configuration and policies for your Access Gateways and agents.

    If you don’t need to upgrade an Identity Server with the Administration Console, your Identity Servers cluster should contain only 3.0 SP4 servers. In this condition, you should be able to edit their cluster configuration and the policies. If you needed to upgrade an Identity Server with an Administration Console, the Identity Servers cluster configuration should not be modified until you have upgraded all the Identity Servers in the cluster.

    You should not try to use 3.1, 3.1 SP1, or 3.1 SP2 features until all components have been upgraded. The new 3.1 policy features such as policy extensions, policy copy, and force data read appear on the policy configuration pages, but they won’t be active until all components have been upgraded, including the policy engine.

  7. If the upgrade is successful, continue with Section 9.2.3, Upgrading the SP4 Identity Servers.

    If the upgrade is unsuccessful, see Section 9.2.8, Troubleshooting a Failed Upgrade.

9.2.3 Upgrading the SP4 Identity Servers

The Identity Servers can be upgraded one at time. This allows your site to remain up during the upgrade. However, they should all be upgraded as quickly as possible.

NOTE:When you upgrade the Identity Server, the Session Timeout value is rounded up to the nearest value divisible by 5, then this value is assigned to all contracts. After all the Identity Servers in the cluster have been upgraded, you can modify the Authentication Timeout on each contract to meet your security requirements. You can also modify the Default Timeout value (the new name for the Session Timeout option) to the value you want assigned to new contracts and to federated sessions that cannot be associated with a contract.

  1. Modify the L4 switch so that no traffic is sent to the Identity Server you have selected to upgrade.

    When the Identity Server is taken offline for the upgrade, any users logged into this server are seamlessly transferred to another server.

  2. Upgrade the Identity Server.

    For more information, see Section 9.7.1, Upgrading the Linux Identity Server.

  3. Decide whether a custom login page is required.

    As soon as you have a 3.1 SP2 server in the cluster, be aware that the user experience is not the same for all users. Users who are attached to the 3.0 servers are prompted with the 3.0 login page. Users who are attached to the 3.1 SP2 servers are prompted with the 3.1 SP2 login page. One solution to this mixed environment is to upgrade all servers as quickly as possible. The other solution is to use a custom login page and enable it for both the 3.0 and 3.1 servers. This makes the login experience the same, but session failover when an Identity Server goes down is not seamless. The users who used the down server for authentication are prompted to log in again.

    Custom 3.0 login pages cannot be used with 3.1 SP2 without modification. For information on how to modify 3.0 custom pages, see Section 9.2.4, Modifying 3.0 Login Pages for 3.1 SP2.

  4. (Conditional) If you have set up Kerberos authentication, modify the bcsLogin.conf file in the /opt/novell/java/jre/lib/security directory.

    Replace other in the first line with the following:

    com.sun.security.jgss.accept

    This is required because Access Manager 3.1 SP2 uses a different version of Java.

  5. (Conditional) If the Identity Server contained an SSL VPN server, the SSL VPN server was upgraded with the Identity Server. See Section 9.2.6, Upgrading the SP4 SSL VPN Servers before upgrading another Identity Server.

  6. (Conditional) If you are using Novell SecretStore®, verify that the 3.1 SP2 settings match your 3.0 configuration.

    1. In the Administration Console, click Devices > Identity Servers > Edit > Local > [Name of User Store].

    2. If this eDirectory™ user store has SecretStore installed on it, select the Install NMAS SAML method option.

    3. If you enabled secret store lock checking in 3.0, select the Enable Secret Store lock checking option.

    4. Click OK twice, then update the Identity Server.

  7. (Conditional) If you have set up trusted identity providers, you need to configure a card for them.

    If you configured a link on the login page that allowed your users to select the identity provider they wanted to use for authentication, this link is removed when you upgrade to 3.1 SP2. To add the link to the 3.1 SP2 login page, you need to configure an authentication card for each identity provider.

    1. In the Administration Console, click Devices > Identity Servers > Edit > [Protocol] > [Identity Provider] > Authentication Card.

    2. In the Text box, specify a description for the identity provider.

      If you used only a text link in 3.0, enter that text here.

    3. In the Image list, click <Select local image> to upload a custom image.

      If you used an image for the link in 3.0, upload the image file and use it for the authentication card. Images must fall within the size bounds of 60 pixels wide by 45 pixels high through 200 pixels wide by 150 pixels high.

      For ease of use, each identity provider should have its own unique image.

    4. Enable the Show Card option.

    5. Repeat these steps for each configured identity provider.

    6. Update the Identity Server.

  8. Reconfigure the L4 switch so that the upgraded server receives traffic.

  9. Upgrade another server in the cluster.

    When you take the second server offline for an upgrade, users might not be seamlessly transferred. They might be prompted to log in again.

  10. Restore any custom files before bringing the server back online. See Step 3 and Step 4.

  11. Upgrade the remaining servers in the cluster.

    You should not try to use any of the new 3.1, 3.1 SP1, or 3.1 SP2 features until all Access Manager components have been upgraded to 3.1 SP2.

  12. (Conditional) If you are using the 3.1 login page, configure authentication cards for the contracts that you are using.

    In 3.1 SP2, all contracts can have an associated authentication card. If you allow the cards to appear on the login page, users can select their authentication method by selecting the card.

    The upgrade process does not try to assign cards to custom contracts because it cannot anticipate all the ways the contracts might have been customized. To assign a card to a contract:

    1. In the Administration Console, click Devices > Identity Servers > Edit > Local > Contracts.

    2. Click the name of a contract, then click Authentication Card.

    3. In the Text box, specify a description of the contract. You might want to use the name of the contract for this description.

    4. From the drop-down list, select an image.

      For the default contracts and classes, Access Manager supplies some cards for you to use. You can use these images or use the <Select local image> option to upload your own custom images. Images must fall within the size bounds of 60 pixels wide by 45 pixels high through 200 pixels wide by 150 pixels high.

      Default Contract or Class

      Default Image Name

      Name/Password - Basic

      Basic Auth Username Password

      Name/Password - Form

      Form Auth Username Password

      Secure Name/Password - Basic

      Secure Basic Auth Username Password

      Secure Name/Password - Form

      Secure Form Auth Username Password

      Kerberos

      Kerberos

      NMAS

      NMAS Biometrics

      X509Class

      X509

      OpenIDClass

      OpenID

      NPOrRadiusOrX509Class

      Combination Authentication: X509, UserName Password, or Radius

    5. Enable the Show Card option if you want the card to appear on the login page.

    6. Repeat these steps for each contract.

      If you have configured your protected resources on the Access Gateway to use Any Contract and you want the users to select how they authenticate, each configured contract needs to have a card.

    7. Update the Identity Server.

  13. If the upgrade is successful, continue with Section 9.2.5, Upgrading the SP4 Linux Access Gateway Appliances.

    If the upgrade is unsuccessful, see Section 9.2.8, Troubleshooting a Failed Upgrade.

9.2.4 Modifying 3.0 Login Pages for 3.1 SP2

If you have created custom login pages for use with specific protected resources, you need to modify these login pages before installing them on the Identity Servers running Access Manager 3.1 SP2. If you want the login page to have the same look and feel as the 3.0 login page, you can modify the login.jsp file from 3.0 so that it works on 3.1 SP1. If you want your custom login pages to have the 3.1 look and feel, see Customizing the Identity Server Login Page in the Novell Access Manager 3.1 SP2 Identity Server Guide.

For information on how to modify a 3.0 login.jsp page to compile and run on 3.1 SP1, see the following:

Modifying the Properties of the Authentication Class or Method

In Access Manager 3.0, the login page for a particular authentication contract can be altered by setting an alternative JSP in the properties of an authentication class or method. In 3.1 SP2, setting the same JSP property causes the JSP to display in the credential frame of the login page. To create the same effect in 3.1 SP2, you must add the MainJSP property to the authentication method.

Property Name: MainJSP

Property Value: true

Property names and values are case sensitive.

Setting the MainJSP property causes the login.jsp page to be displayed in the main frame, not in the credential frame. For more information about setting property values, see Specifying Common Class Properties in the Novell Access Manager 3.1 SP2 Identity Server Guide.

Converting Custom Access Manager 3.0 JSPs to 3.1 JSPs

Changes were made in Access Manager 3.1 to simplify the JSPs that need to be created by authentication class developers. The changes allow the developers of new authentication classes to focus on the collection of required credentials and not on other aspects of the user interface. These changes have made JSPs used in Access Manager 3.0 incompatible with 3.1 SP2.

The line numbers in the following steps refer to the lines in an unmodified 3.0 login.jsp file. To understand what the lines the numbers refer to, see Section B.0, Modifications Required for a 3.0 Login Page.

To convert a 3.0 JSP to a 3.1 SP2 JSP:

  1. Remove the following import statement found in line 5:

    <%@ page import="java.net.*" %>

  2. Add the following import statement:

     <%@ page import="com.novell.nidp.ui.*" %>

  3. Find the following code in lines 12 through 18: 

    response.setHeader("Pragma", "No-cache");
response.setHeader("Cache-Control", "no-cache");

       Locale locale = request.getLocale();
       String strLanguageCode = locale.getLanguage();
       String strImageDirectory = NIDPResourceManager.getInstance(). getImageDirectory(locale);
       NIDPResource resource = NIDPResourceManager.getInstance(). get(JSPResDesc.getInstance(), locale);

  4. Replace the code found in Step 3 with the following line:

         ContentHandler handler = new ContentHandler(request,response);

  5. Remove all code and HTML associated with the following method:

    request.getAttribute("identify")

    Remove lines 73 through line 79, and all of line 80 except for the ending Java code marker (%>). In 3.0, if user identification was necessary, this code handled it. In 3.1 SP1, the identity provider handles user identification when necessary.

  6. .Remove all code and HTML associated with the following method:

    request.getAttribute("provision")

    Remove lines 108 through line 120. In 3.0, if provisioning was available, this method handled provisioning. In 3.1 SP1, the identity provider handles provisioning.

  7. Remove all code and HTML associated with DisplayableProvider objects. Remove lines 126 through 159.

    In 3.0, this code displayed the federated identity providers. In 3.1, this has been replaced with authentication cards and is handled by the identity provider. For information on how to add federation links to your login page, see Modifying a Custom JSP for Federation Links.

  8. Remove all code and HTML associated with the following method:

    request.getAttribute("cancel")

    Remove lines 165 through 176. In 3.0, if an option to cancel was available, this code handled it. In 3.1 SP2, the identity provider handles canceling.

  9. Replace any references to strLanguageCode with handler.getLanguageCode().

  10. Replace all references to the locale variable with request.getLocale().

  11. Image references formerly included the strImageDirectory variable. This variable has been removed, and image references must use the following method: 

    handler.getImage("btnlogin.gif",true)

    The first parameter specifies the filename of the image. The second parameter specifies the location of the file:

    • Specify false if the image is not localized and is always located in the \images directory.

    • Specify true if the image is localized and is located in an appropriate language directory in the \images directory.

    On line 104, replace the image src (src="<%= request.getContextPath() %>/images/<%=strImageDirectory%>/btnlogin_<%=strImageDirectory%>.gif") with the following:

    src="<%=handler.getImage("btnlogin.gif",true)%>"

  12. Replace references to resource.getString0(resource) with handler.getResource(resource).

  13. Replace the following resources if they exist in your file:

    JSPResDesc.LOGIN_TITLE with JSPResDesc.TITLE

    JSPResDesc.LOCAL_LOGIN with JSPResDesc.PRODUCT

  14. Some other resources might not be available. Replace any of these resources with the text that you need for your site.

  15. Copy the file to the jsp directory of your Identity Server.

    Linux: /var/opt/novell/tomcat5/webapps/nidp/jsp

    Windows: C:\Program Files\Novell\Tomcat\webapps\nidp\jsp

  16. Test the page by logging in.

  17. (Conditional) If you get a blank page instead of a login page:

    1. Ensure that logging is turned on (click Devices > Identity Servers > Edit > Logging). Make sure that File Logging is enabled, that Echo to Console is enabled, and that Application logging is set to Debug.

    2. Try logging in again.

    3. Look for errors in the catalina.out (Linux) or stdout.log (Windows) file.

      Search for the name of your custom login page. Each line in the file with an error generates an error message. For example, if you missed removing a reference to locale, the file contains a message similar to the following:

      An error occurred at line: 129 in the jsp file: /jsp/login_custom.jsp
locale cannot be resolved
126:   {
127: %>        
128:         <tr>
129:                <td colspan=4 width="100%" align="center"><%=NIDPCripple.getCrippleAdvertisement(locale)%></td>
130:         </tr>
131: <%
132:   }

  18. (Optional) To view a 3.0 login.jsp file that has been modified (but not customized) to compile on 3.1 SP1 IR1, see Section B.0, Modifications Required for a 3.0 Login Page.

Preserving the Target

With a custom login page, users accessing protected resources on the Linux Access Gateway Appliance are sometimes presented with the Identity Server user portal page and not the protected resource after submitting their credentials. This happens when the user is redirected to the login page, but waits for longer than the session timeout before submitting the credentials.

In this scenario, the Identity Server realizes that the original session is invalid and creates a new session to validate the credentials. With this new session, the original user’s context is lost and that context contained the target, or the redirect URL, to be used after validating the credentials.

To add the hidden target or redirect field to the form, the following code needs to be added somewhere within the form content of the JSP. With this code available, the new session can still reference the URL to redirect the user to even if the session has timed out.

<%
 String target = (String) request.getAttribute("target");
 if (target != null)
   {
     %>
          <input type="hidden" name="target" value="<%=target%>">
    <%
   }
%>

Modifying a Custom JSP for Federation Links

The 3.1 login page uses cards for federation. To make your 3.0 federation links compatible with 3.1, make the following modifications to your custom login pages that contain federation links:

  1. Near the top of the JSP file, add the following import statements:

    <%@ page import="com.novell.nidp.authentication.card.*" %>
<%@ page import="com.novell.nidp.common.util.*" %>

  2. Add the following include statement for the style sheet:

    <link rel="stylesheet" href="<%= handler.getImage("cards.css",false)%>"
type="text/css">

  3. Add the following lines to include the cards31.jsp file:

    <tr>
   <td width="50%">&nbsp;</td>
   <td style="background-color: #efeee9; padding: 10px" colspan=2>

      <%@ include file="cards31.jsp" %>

   </td>
   <td width="100%">&nbsp;</td>
</tr>

9.2.5 Upgrading the SP4 Linux Access Gateway Appliances

When the Access Gateways in the cluster have been upgraded, you can modify the 3.0 features, but you should not try to use any of the new 3.1, 3.1 SP1, or 3.1 SP2 features until all Access Manager components have been upgraded to 3.1 SP2.

You need to upgrade your SLES 9 Access Gateways to SP2 before you can then migrate them to SLES 11.

NetWare Access Gateways must be converted to Linux Access Gateways. For more information, see Section 9.11, Converting a NetWare Access Gateway.

Upgrading a Standalone Access Gateway Appliance or an Appliance with SSL VPN Server

  1. Upgrade a secondary server in the cluster. The primary server needs to be the last server upgraded.

    1. Select one of the following:

      If you first installed the Access Gateway with the Access Manager 3.0 release and you are upgrading to 3.1 SP2, run the keystore clean up script. For instructions, see Running the Keystore Clean-Up Script.

      If you first installed the Access Gateway with the Access Manager 3.0 release and you are upgrading to 3.1 SP2 IR1, continue with Step 1.b.

      If you first installed the Access Gateway with 3.0 SP1 release, continue with Step 1.b.

    2. Run the upgrade script.

      The Linux Access Gateway Appliance supports multiple upgrade methods. For information about these methods, see Section 9.8, Upgrading the Linux Access Gateway Appliance.

      If the Access Gateway server contains an SSL VPN server, upgrade it with the Access Gateway.

  2. Upgrade the other secondary servers in the cluster.

  3. Upgrade the primary server in the cluster.

  4. If the upgrade is successful, make some configuration changes and update the Access Gateways to start using the new features for SP2.

    If the upgrade is unsuccessful, see Section 9.2.8, Troubleshooting a Failed Upgrade.

  5. (Conditional) If an SSL VPN was not installed with the Access Gateway Appliance, continue with one of the following:

  6. (Conditional) If an SSL VPN server was installed with the Access Gateway Appliance, continue with Configuration Changes to the SSL VPN Server Installed with the Access Gateway Appliance.

Configuration Changes to the SSL VPN Server Installed with the Access Gateway Appliance

After you have upgraded the SSL VPN server installed along with the Access Gateway Appliance, you must modify the existing path-based service accelerating the SSL VPN server as follows:

  1. In the Administration Console, click Devices > Access Gateways > Edit > [Name of Reverse Proxy].

  2. In the Proxy Service List section, click the SSL VPN service that you have configured.

  3. Select the Web Servers tab.

  4. Click the IP address link in the Web Server List section.

  5. Change the IP address to 127.0.0.1, which is the loopback IP address.

    Originally, the public IP address of SSL VPN was configured as the IP address of the Web server.

  6. Click OK when prompted to the purge cache.

  7. Click OK, then click Update on the Configuration page to save your modifications.

  8. Continue with one of the following:

Running the Keystore Clean-Up Script

The location of the keystores on Administration Console for the Embedded Service Provider of the Access Gateway Appliance changed in Access Manager 3.0.1. The SLES 9 Access Gateway Appliance works with the keystores in either the old or the new location. However, when you migrate your SLES 9 Access Gateway Appliances to SLES 11, the SLES 11 Access Gateway Appliance cease to function because it cannot find the Embedded Service Provider keystores.

NOTE:The keystore clean-up script is required if you are upgrading to Access Manager 3.1 SP2. If you are upgrading to 3.1 SP2 IR1, the upgrade script moves the keystores to the new location.

To run a script that moves the keystores to the new location:

  1. Back up your system.

    For instructions, see Backing Up the Access Manager Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  2. Discover the device ID for the Embedded Service Provider of the Access Gateway Appliance:

    1. In the Administration Console, click Auditing > General Logging.

    2. In the Access Gateways section, view the IP address, then the ID number. The device ID for the Embedded Service Provider of Access Gateway begins with an idp-esp- prefix.

    3. Record all the device IDs for your Access Gateways.

  3. Log in to the primary Administration Console as root.

  4. Download the AM_31_SP2_LAG300_keystorePathScript.sh script from Novell Downloads.

  5. Enter the following command:

    AM_31_SP2_LAG300_keystorePathScript.sh

  6. Enter the IP address of your Administration Console machine.

  7. Enter the name of the Access Manager administrator.

  8. Enter the password for the administrator.

  9. Type the entry number for the device ID, then press Enter.

    The device ID is displayed with the name of the Access Gateway in parentheses.

  10. In the Administration Console, restart the Embedded Service Provider:

    1. Click Devices > Access Gateways.

    2. Select the Access Gateway.

    3. Click Actions > Service Provider > Restart Service Provider.

  11. Repeat Step 5 through Step 10 for each Access Gateway in the cluster.

9.2.6 Upgrading the SP4 SSL VPN Servers

Your configuration determines when you upgrade the SSL VPN servers:

After you have upgraded the SSL VPN servers, continue with the next required component. After all devices have been successfully upgrade, continue with Section 9.2.7, Upgrading the Policies.

If the upgrade is unsuccessful, see Section 9.2.8, Troubleshooting a Failed Upgrade.

Multiple SSL VPN Servers per Protected Resource

If you have configured a protected resource to be serviced by multiple SSL VPN servers, these servers can be a mixture of 3.1 SP2 and 3.0 until you have finished upgrading any secondary Administration Consoles, Identity Servers, and Linux Access Gateway Appliances. However, as long as there is a mixture, the user experience varies. When the user sets up a connection to the 3.0 server, the user accesses the 3.0 client and uses its interface. When the user is directed to the 3.1 SP2 server and sets up a connection, the user accesses the 3.1 SP2 client and uses its interface.

Continue with the next required component:

  • If the SSL VPN server was installed on the Administration Console, continue upgrading the secondary consoles.

  • If the SSL VPN server was installed on the Identity Server, continue upgrading the other Identity Servers in the cluster.

  • If the SSL VPN server was installed on the Linux Access Gateway Appliances, continue upgrading the other Access Gateways in the cluster.

Servlet Load Balancing

If you have configured the SSL VPN server to use servlet load balancing, you need to immediately upgrade all SSL VPN servers. If the servers are installed with other Access Manager components, upgrade those components. For instructions, see the following:

If the SSL VPN servers are installed on separate machines, see Section 9.10.3, Upgrading SSL VPN Installed on a Separate Machine.

Updating Configuration Changes to the Upgraded Server

After you have upgraded your SSL VPN server, you must follow the steps given below before you perform any configuration changes:

  1. In the Administration Console, click Devices > SSL VPNs > Edit.

  2. Click OK in the dialog box prompting you to update the servers.

  3. Click OK, then click Update on the Configuration page to save modifications.

  4. Define the security levels by using the client integrity check policies and associating the traffic policies to the appropriate security level, before you allow any client connections.

    For more information on assigning security levels to traffic policies, see Configuring Client Security Levels in the Novell Access Manager 3.1 SP2 SSL VPN Server Guide. This is a mandatory activity before you proceed with any other configuration steps because after the SSL VPN servers are upgraded, all the traffic policies are associated to security level None by default. In such a scenario, all the traffic policies are pushed to the client, even if the client fails the client integrity check.

  5. (Optional) If you configured SSL VPN to connect only in Kiosk mode, to download the applet when a user uses Internet Explorer, or to enable SSL VPN to connect to Citrix servers by using config.txt and web.xml files, do the following:

Upgrading Clustered SSL VPN Servers

If you clustered the SSL VPN servers in 3.0, upgrade the SSL VPN servers after you have upgraded the Administration Console, Identity Server, and the Linux Access Gateway.

9.2.7 Upgrading the Policies

The following procedures cause some down time for your system. Perform them when the fewest users are accessing your system.

  1. Make sure all devices are in a Current state.

    All configuration changes to the devices need to be applied before upgrading the policies.

  2. Back up your system.

    For instructions, see Backing Up the Access Manager Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.

  3. After you have upgraded all the Access Manager components, upgrade the policies:

    1. In the Administration Console, click Policies > Policies.

    2. To view the devices that need to have their policies upgraded, click Details.

    3. Review the list, then click Upgrade Policies.

  4. Update the policies on all the Identity Servers.

    Existing authenticated sessions continue to work. New authentications fail until all the Identity Servers and Access Gateways have been updated.

    If the update to an Identity Server fails, perform an amrestore. If you modified the Tomcat password, you need to back up the Tomcat server.xml file before running the restore. See Restoring an Administration Console Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide. Then restart the Identity Server.

    Solve the problem before attempting to upgrade the policies again.

  5. Update the Access Gateways.

    If the update to an Access Gateway fails, perform an amrestore. If you modified the Tomcat password, you need to back up the Tomcat server.xml file before running the restore. See Restoring an Administration Console Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide

    Restart the Identity Servers, then re-push the configuration to the Access Gateway. Click Auditing > Troubleshooting, scroll to the Current Access Gateway Configurations section, select the Access Gateway, then click Re-push Current Configuration.

    Solve the problem before attempting to upgrade the policies again.

  6. Start using the new 3.1, 3.1 SP1, and 3.1 SP2 features.

    For a description of the new features, see the following:

9.2.8 Troubleshooting a Failed Upgrade

If the upgrade fails for the Administration Console, reinstall a 3.0 SP4 version of the Administration Console and restore the backup. Fix the problems encountered in the failed upgrade before trying again.

If the upgrade fails for an Identity Server, an Access Gateway, or an SSL VPN server but the Administration Console has been successfully upgraded to 3.1 SP2, try installing a 3.1 SP2 version of the component with the same IP address as the failed component. When the device imports into the Administration Console, the component’s configuration information should be pushed to it.

  • To push the configuration to an Identity Server, restart the Identity Server.

  • To push the configuration to an Access Gateway, use the Re-push option. Click Auditing > Troubleshooting, scroll to the Current Access Gateway Configurations section, select the Access Gateway, then click Re-push Current Configuration.

If pushing the configuration to the newly installed device does not work, you need to reinstall the 3.0 SP4 version of the component and fix the problems encountered in the failed upgrade before trying again. To return all components to 3.0 SP4, use the backup you took before upgrading and perform an amrestore. If you have modified the Tomcat password, you need to back up the Tomcat server.xml file before running the restore. See Restoring an Administration Console Configuration in the Novell Access Manager 3.1 SP2 Administration Console Guide.