7.1 Upgrading Access Manager on Linux

7.1.1 Upgrading the Evaluation Version to the Purchased Version

If you have downloaded the evaluation version and want to keep your configuration after purchasing the product, you need to upgrade each of your components with the purchased version. The upgrade to the purchased version automatically changes your installation to a licensed version.

After you have purchased the product, log in to the NetIQ Customer Center and follow the link that allows you to download the product. Then use the following sections for instructions on upgrading the components:

Upgrading the Administration Console

If the Identity Server is installed on the same machine as the Administration Console, the Identity Server is automatically upgraded with the Administration Console.

  1. Open a terminal window.

  2. Log in as the root user.

  3. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  4. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./upgrade.sh

  5. The system displays the confirmation message along with the list of installed components. For example, if the Administration Console and Identity Server are installed on the same machine, the following message is displayed: 

    The following components were installed on this machine 

1. Access Manager Administration Console 
2. Identity Server 
Do you want to upgrade the above components (y/n)?

  6. Type Y and press Enter.

  7. Enter the Access Manager Administration Console user ID.

  8. Enter the Access Manager Administration Console password.

  9. Re-enter the password for verification.

  10. The system displays the following message when the upgrade is complete:

    Successfully upgraded.

    The upgrade logs are located in the /tmp/novell_access_manager/ directory. The logs have time stamping.

If you encounter an error, see Troubleshooting a Linux Administration Console Upgrade in the NetIQ Access Manager 4.1 Administration Guide .

Upgrading the Identity Server

Use the following procedure to upgrade the stand-alone Identity Server. If you have installed both the Identity Server and the Administration Console on the same machine, see Upgrading the Administration Console.

NOTE:If you have modified the JSP file to customize the login page, logout page, and error messages, you can restore the JSP file after installation. You should sanitize the restored JSP file to prevent XSS attacks. For more information, see Preventing Cross-site Scripting Attacks in the NetIQ Access Manager 4.1 Administration Guide .

  1. Open a terminal window.

  2. Log in as the root user.

  3. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  4. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./upgrade.sh

  5. The system displays the following confirmation message: 

    The following components were installed on this machine

1. Identity Server

Do you want to upgrade the above components (y/n)?

  6. Type Y and press Enter.

  7. Enter the Access Manager Administration Console user ID.

  8. Enter the Access Manager Administration Console password.

  9. Re-enter the password for verification.

  10. The system displays the following message when the upgrade is complete:

    Successfully upgraded.

    The upgrade logs are located in the /tmp/novell_access_manager/ directory. The logs have time stamping.

Guidelines to Upgrade from Access Manager 4.0 to 4.0 SP1

Starting from Access Manager 4.0 SP1 release, the default binding supported is SOAP 1.2. If you want to use SOAP 1.1, perform the following steps on all instances of the Identity Server:

  1. Edit the sun-jaxws.xml file.

    Linux: /opt/novell/nam/idp/webapps/nidp/WEB-INF

    Windows: C: \Program Files (x86)\Novell\Tomcat\webapps\nidp\WEB-INF\lib

  2. Remove all instances of bindings from the endpoints in the sun-jaxws.xml file and save the changes. A binding is represented by the following line in this file:

    binding="http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/"

  3. Restart the Identity Server by using the following command: command.

    Linux: /etc/init.d/novell-idp restart

    windows: net start Tomcat7

NOTE:If you are upgrading the Identity Server from 4.0 to 4.1 and have configured the Google Authenticator custom class, all the existing (registered) users are moved to the new implementation seamlessly. But if you are a new user planning to register with the Google Authenticator, you must configure the contract using the TOTP class implementation available as part of 4.x.x.

Upgrading the Access Gateway Appliance

  1. Open a terminal window.

  2. Log in as the root user.

  3. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  4. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./ma_upgrade.sh

  5. Enter the Access Manager Administration Console user ID.

  6. Enter the Access Manager Administration Console password

  7. Re-enter the password for verification

    The upgrade logs are located in the /tmp/novell_access_manager/ directory. The logs have time stamping.

7.1.2 Upgrading Access Manager

You must be on Access Manager 3.2 SP2 or a higher version to upgrade to 4.1 or higher. For upgrading, you need to upgrade the components in the following order:

While you are upgrading the components, take care of the following points:

  • Ensure that you are on Access Manager 3.2 SP2 or a higher version.

  • You must backup the files that you have customized.

  • Ensure that you follow the procedure given below for both Linux and Red Hat:

  1. Open the nds.conf file available under /etc/opt/novell/eDirectory/conf/.

  2. Delete all the duplicate lines from the file. For example the file may contain two lines of n4u.server.vardir=/var/opt/novell/eDirectory/data. Delete one of them.

  3. Restart eDirectory using /etc/init.d/ndsd restart command.

Upgrading the Administration Console

NOTE:Access Manager by default supports Tomcat 8.0.18 and OpenSSL 1.0.1o. Due to this, the Identity Server and Access Gateway disable requests from clients that are on versions lower than TLS1. However, the Access Gateway can continue communication with web servers that are on versions lower than TLS1.

If the Identity Server is installed on the same machine as the Administration Console, the Identity Server is automatically upgraded with the Administration Console. If you are upgrading this configuration and you have custom JSP pages, you can either create your own backup of these files or allow the upgrade program to back them up for you.

  1. Back up any customized JSP pages and related files.

    Even though the upgrade program backs up the JSP directory and its related files in the /root/nambkup folder, it is a good practice to backup these files.

    /var/opt/novell/tomcat7/webapps/nidp/jsp

  2. Open a terminal window.

  3. Log in as the root user.

  4. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  5. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./upgrade.sh

  6. The system displays the confirmation message along with the list of installed components. For example, if the Administration Console and Identity Server are installed on the same machine, the following message is displayed: 

    The following components were installed on this machine 

1. Access Manager Administration Console 
2. Identity Server 
Do you want to upgrade the above components (y/n)?

  7. Type Y to upgrade. A Warning message regarding backup and restore of JSP files is displayed.

  8. Type Y to continue with the upgrade, then press Enter.

  9. Type Y to restore the custom login pages.

  10. Enter the Access Manager Administration Console user ID.

  11. Enter the Access Manager Administration Console password.

  12. Re-enter the password for verification.

  13. The system displays the following message when the upgrade is complete:

    Upgrade completed successfully.

  14. (Optional) To view the upgrade files:

    • To view the upgrade log files, see the files in the /tmp/novell_access_manager directory.

    • If you selected to back up your configuration and used the default directory, see the zip file in the /root/nambkup directory. The log file for this backup is located in the /var/log directory.

    • If the Identity Server is installed on the same machine, the JSP directory was backed up to the /root/nambkup directory. The file is prefixed with nidp_jps and contains the date and time of the backup.

NOTE:If you have customized the Java settings in the /opt/novell/nam/idp/conf/tomcat7.conf file, then after the upgrade, you must copy the customized setting to the new file.

If you encounter an error, see Troubleshooting a Linux Administration Console Upgrade in the NetIQ Access Manager 4.1 Administration Guide .

Upgrading the Identity Server

Use the following procedure to upgrade the stand-alone Identity Server. If you have installed both the Identity Server and the Administration Console on the same machine, see Upgrading the Administration Console.

IMPORTANT:Make sure to complete the following before you begin:

  • If you are upgrading the Access Manager components on multiple machines, ensure that the time and date are synchronized on all machines.

  • Make sure that the Access Manager Administration Console is running. However, you must not perform any configuration tasks in the Administration Console during an Identity Server upgrade.

  1. Back up any customized JSP pages and related files.

    Even though the upgrade program backs up the JSP directory and its related files in the /root/nambkup folder, it is a good practice to backup these files.

  2. Open a terminal window.

  3. Log in as the root user.

  4. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  5. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./upgrade.sh

  6. The system displays the following confirmation message: 

    The following components were installed on this machine

1. Identity Server

Do you want to upgrade the above components (y/n)?

  7. Type Y and press Enter. A Warning message regarding backup and restore is displayed.

  8. Would you like to continue this upgrade? Type Y to upgrade.

  9. The system displays the following message: 

    If old jsp pages need to be restored, ensure that you sanitize them to prevent possible Cross-site Scripting attacks. You can sanitize jsp pages after restoring them. Do you want to restore custom login pages? (y/n):

    Type Y to restore.

  10. Enter the Access Manager Administration Console user ID.

  11. Enter the Access Manager Administration Console password

  12. Re-enter the password for verification

  13. The system displays the following message when the upgrade is complete:

    Upgrade completed successfully.

  14. Restore any customized files from the backup taken earlier. To restore files, copy files to the respective locations:

    • /opt/novell/nam/idp/webapps/nidp/jsp

    • /opt/novell/nam/idp/webapps/nidp/html

    • /opt/novell/nam/idp/webapps/nidp/images

    • /opt/novell/nam/idp/webapps/nidp/config

    • /opt/novell/nam/idp/webapps/nidp/WEBINF/lib

    • /opt/novell/nam/idp/webapps/nidp/WEBINF/web.xml

    • /opt/novell/nam/idp/webapps/nidp/WEBINF/classes

    • /opt/novell/nam/idp/webapps/nidp/WEBINF/conf

    • /opt/novell/java/jre/lib/security/bcslogin.conf

    • /opt/novell/java/jre/lib/security/nidpkey.keytab

    • /opt/novell/nam/idp/webapps/nidp/classUtils

    • /opt/novell/nam/idp/conf/server.xml

    • /opt/novell/nam/idp/conf/tomcat.conf

NOTE:If you want to name the .keytab file to a name other than nidpkey.keytab, before upgrading, ensure that you modify the upgrade_utility_functions.sh script located under novell-access-manager/scripts folder.

NOTE:If you have customized the Java settings in the /opt/novell/nam/idp/conf/tomcat7.conf file, then after the upgrade, you must copy the customized setting to the new file.

NOTE:If you have modified the JSP file to customize the login page, logout page, and error messages, you can restore the JSP file after installation. You should sanitize the restored JSP file to prevent XSS attacks. For more information, see Preventing Cross-site Scripting Attacks in the NetIQ Access Manager 4.1 Administration Guide .

Upgrading the Access Gateway Appliance

Prerequisite: If you are on 3.2.2 or higher, before upgrading to latest version, you must first upgrade the base operating system of the Access Gateway appliance to the latest operating system that is included in the latest Access Gateway appliance ISO. For more information about how to upgrade, see Section 8.0, Upgrading the Operating System for Access Gateway Appliance.

  1. Back up any customized JSP pages and related files.

    Even though the upgrade program backs up the JSP directory and its related files in the /root/nambkup folder, it is a good practice to backup these files.

  2. Open a terminal window.

  3. Log in as the root user.

  4. Download the upgrade file from dl.netiq.com and extract the tar.gz file using the following command: tar -xzvf <filename>.

    NOTE:For information about the name of the upgrade file, see the specific Release Notes on the Access Manager Documentation website.

  5. Change to the directory where you unpacked the file, then enter the following command in a terminal window:

    ./ma_upgrade.sh

  6. A Warning message regarding backup and restore is displayed. If you have customized any files, take a backup and restore them after installation.

  7. Would you like to continue this upgrade? Type Y to continue.

  8. Do you want to restore custom login pages? Type Y to confirm.

  9. Enter the Access Manager Administration Console user ID.

  10. Enter the Access Manager Administration Console password

  11. Re-enter the password for verification

  12. The system displays the following message when the upgrade is complete:

    Upgrade completed successfully.

  13. Restore any customized files from the backup taken earlier. To restore the files, copy the files to the respective locations below:

    • /opt/novell/nam/mag/tomcat/webapps/nesp/WEB-INF/web.xml

    • /opt/novell/nam/mag/tomcat/webapps/nesp/jsp

    • /opt/novell/nam/mag/tomcat/webapps/nesp/html

    • /opt/novell/nam/mag/tomcat/webapps/nesp/images

    • /opt/novell/nam/mag/webapps/agm/WEB-INF/config/current

    • /opt/novell/nam/mag/tomcat/webapps/nesp/config

    • /opt/novell/devman/jcc/scripts/presysconfig.sh

    • /opt/novell/devman/jcc/scripts/postsysconfig.sh

Upgrading the Access Gateway Service

Prerequisites for Access Gateway Service

  • Manually back up the /var/opt/novell/tomcat5/conf/tomcat5.conf and /var/opt/novell/tomcat7/conf/server.xml files.

    The ag_upgrade.sh script takes care of backing up the remaining customized files automatically. These files get automatically backed up at the /root/nambkup folder and includes apache configuration and error pages.

Process

  1. Download the AM_41_AccessGatewayService_Linux_64.tar.gz file from the NetIQ download site and extract it using the following command:

    tar -xzvf <AM_41_AccessGatewayService_Linux_64.tar.gz>

  2. Run the ag_upgrade.sh script from the folder to start the upgrade.

  3. Specify the following information:

    User ID: Specify the name of the administration user for the Administration Console.

    Password and Re-enter Password: Specify and re-enter the password for the administration user account.

    The Access Gateway Service is upgraded. The following message is displayed when upgrade is complete: 

    Starting Access Manager services...
Backup of customized files are available at /root/nambkup. Restore them if required.

  4. View the log files. The install logs are located in the /tmp/novell_access_manager/ directory.

  5. Restore any customized files from the backup taken earlier as part of steps in Prerequisites for Access Gateway Service.

    To restore the files, copy the content of the following files to the corresponding file in the new location.

    Old File Locations

    New File Location

    /root/novell_access_manager/apache2/(contains apache var files)

    /opt/novell/apache2/share/apache2/error

    /root/novell_access_manager/nesp/ (contains modified error pages)

    /var/opt/novell/tomcat/webapps/nesp/jsp/

    server.xml:

    If you have modified any elements or attributes in the 3.2.x or 4.0.x environment the corresponding changes will need to be applied to the 4.1 server.xml file.Typical changes done to the server.xml include modifying the 'Address=' to restrict the IP address the application will listen on, or 'maxThreads=' attributes to modify the number of threads.

    In the following example, 3.2..x has customized maxThreads value.

    <<Connector port="9009" enableLookups="false" redirectPort="8443" protocol="AJP/1.3" address="127.0.0.1" minSpareThreads="25" maxThreads="700" backlog="0" connectionTimeout="20000, ... ../>

    Make a note of the customizations and copy paste the changed values in the 4.1 server.xml file

    tomcat.conf:

    Copy any elements or attributes that you have customized in the tomcat7.conf file to the tomcat.conf file.For example, if you have included the environment variable to increase the heap size by using -Xmx/Xms/Xss attributes in the tomcat7.conf file, copy this variable to the 4.1 /opt/novell/nam/idp/conf/tomcat7.conf file.

  6. Modify the required properties in /opt/novell/nam/mag/webapps/agm/WEB-INF/agm.properties using back up file /root/novell_access_manager/agm/agm.properties. If you have customized the agm.properties file from the backup taken in 3.2.x or 4.0.x, ensure that you apply the same to the new 4.1 /opt/novell/nam/mag/webapps/agm/WEB-INF/agm.properties file. An example below shows the how to enable the backend webserver's webpage caching and the cache location.

    apache.disk.cache.enabled=yes

    apache.disk.cache.root=/var/cache/novell-apache2

  7. Change the ownerships of the following files (with read access to tomcat user) using the following commands:

    chown -R novlwww:novlwww /var/opt/novell/tomcat7/webapps/nesp/jsp/

    chown -R novlwww:novlwww /opt/novell/nam/mag/webapps/agm/WEB-INF/agm.properties

  8. On the newly added Access Gateway Service, restart Tomcat using the /etc/init.d/novell-mag restart or rcnovell-mag restart command.

NOTE:After upgrading to 4.1, manually configure the customized Java settings.

7.1.3 Applying Access Manager 4.1.2 Hotfix* Patch for Linux

You can upgrade Access Manager 4.1.2 to 4.1.2 Hotfix* by applying the Hotfix patch.

NOTE:Hotfix* is used to represent the hotfix number released for Access Manager 4.1.

The patch helps you upgrade to the latest Access Manager with ease. Instead of downloading tar files that contain the entire set of binaries, you can download a .zip file that contains incremental changes in form of a patch file. You can use this patch file to update all components of your Access Manager.

If you have multiple components installed on the same system, the patch installation process will take care of updating all the binaries of these components. For example, if you have both Identity Server and Administration Console installed on a system, installing the patch takes care of updating the binaries of Identity Server and Administration Console.

IMPORTANT:In a cluster setup, ensure that you install the patch on each node of the Access Manager setup.

Installing the Patch

Perform the following steps before applying the patch.

  1. Save the hotfix file to the server running Access Manager. If you have multiple servers in your set up, ensure that you copy this .zip file to all the servers.

  2. Extract the patch file by using the unzip <patch name>.zip command.

    After extraction, the following files and folders are created in the <patch name> folder:

    Table 7-1 Files and folders created in the <patch name> folder after extracting the hotfix installer ZIP file

    File/Folder Name

    Description

    rpm

    Contains rpm files for the patch to run on a Linux server.

    Patchtool

    Contains logging properties file and files necessary for the patch to run on a Windows server.

    installPtool.sh

    Script to install the patch and the patch tool on a Linux server.

    installPatch.sh

    Script to install the HF* patch tool and the updated binaries on a Linux server.

    installPtool.cmd

    Script to install the patch on a Windows server.

    <patch name>-xxx.patch

    The patch file. The name of the patch file changes for each HF release.

    NOTE:xxx represents the build number which is available in the respective release readme.

  3. Log in as the root user.

  4. Go to the location where you have extracted the patch files.

  5. Run the sh installPatch.sh command.

    This command installs the patch and the bundled binaries.

    HINT:To manage the Access Manager patch file, go to /opt/novell/nam/patching/bin folder.

If the patch is already installed, the installer exits with a message.

Administering Patches

  1. After the patch is installed, go to the /opt/novell/nam/patching/bin folder.

  2. Use the following options to administer the Access Manager Appliance patch file.

NOTE:xxx represents the build number which is available in the respective release readme.

Option

Description

Command on Linux server

-qa

Lists all installed patches.

./patch -qa

-q

Lists details of an installed patch.

./patch –q

Example: If you have installed <latest release patch name>, use the following command:./patch –q HF*-xxx

-i

Installs a patch. During installation of a patch, all running services are stopped temporarily. After a patch is installed, all services are restarted and details of the operation are written to log files.

./patch –i <location and patch name>

Example:./patch –i /tmp/AM_4121-xxx.patch

-e

Removes an installed patch. The patch maintains content relationship among patches. So, if you have installed patch 1 and patch 2, patch 1 cannot be removed without removing patch 2. This is because patch 2 contains details of patch 1 as well.During the patch process, all the running services are stopped temporarily.

./patch –e <patch name>

Example:./patch –e HF*-xxx

-qpl

Lists details of a patch that is not installed. If you want to view the changes that are included in the patch file without installing it on your server, use this option

./patch –qpl <location and patch name>

Example:./patch –qpl /tmp/AM_4121-xxx.patch

-v

Verifies integrity of a patch.

./patch –v <location and patch name>

Example:./patch –v /tmp/AM_4121-xxx.patch

-t

Verifies if services can be restored by the installer.

./patch –t <location and patch name>

Example:./patch –t /tmp/AM_4121-xxx.patch