8.1 Upgrading Access Manager on Linux

8.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 Administration Console

If Identity Server is installed on the same machine as Administration Console, Identity Server is automatically upgraded with 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.

    The system displays an information message to enable Syslog on the Auditing user interface of the Administration Console after the upgrade.

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

  8. Enter the Access Manager Administration Console user ID.

  9. Enter the Access Manager Administration Console password.

  10. Re-enter the password for verification.

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

    Upgrade completed successfully.

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

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

Upgrading Identity Server

Use the following procedure to upgrade stand-alone Identity Server. If you have installed both Identity Server and Administration Console on the same machine, see Upgrading 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.2 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.

    The system displays a warning to back up all JSPs before proceeding with the upgrade:

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

  8. Enter the Access Manager Administration Console user ID.

  9. Enter the Access Manager Administration Console password.

  10. Re-enter the password for verification.

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

    Upgrade completed successfully.

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

Upgrading 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.

8.1.2 Upgrading Access Manager

You must be on Access Manager 3.2 SP3 or a higher version to upgrade to 4.2. 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 SP3 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.

NOTE:If you have enabled history for risk-based authentication in Access Manager 4.1, you must upgrade the database for risk-based authentication after upgrading to 4.2. You can find the upgrade script here: /opt/novell/nids/lib/webapp/WEB-INF/RiskDBScript.zip.

MySQL: Run netiq_risk_mysql_upgrade.sql

Oracle: Run netiq_risk_oracle_upgrade.sql

Upgrading Administration Console

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

If Identity Server is installed on the same machine as Administration Console, Identity Server is automatically upgraded with Administration Console. If you are upgrading this configuration and you have custom JSP pages, you can backup 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/tomcat/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 and press Enter.

    The system displays an information message to enable Syslog on the Auditing user interface of Administration Console after the upgrade.

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

  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. (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/tomcat.conf file, then after the upgrade, you must copy the customized setting to the new file. For more information about copying the customized setting, refer Step 13 of Upgrading Identity Server.

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

Upgrading Identity Server

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

IMPORTANT:Ensure to complete the following actions before you begin:

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

  • Make sure that Administration Console is running. However, you must not perform any configuration tasks in 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. Type Y to continue with the upgrade, then press Enter.

  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 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/WEB-INF/lib

    • /opt/novell/nam/idp/webapps/nidp/WEB-INF/web.xml

    • /opt/novell/nam/idp/webapps/nidp/WEB-INF/classes

    • /opt/novell/nam/idp/webapps/nidp/WEB-INF/conf

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

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

    • /opt/novell/nids/lib/webapp/classUtils

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

      Also, add the following line to the server.xml file to use the new features on the user portal. For information about new features of user portal, refer Access Manager 4.2 Release Notes.

      <Connector NIDP_Name="localConnector" URIEncoding="utf-8" acceptCount="100" address="127.0.0.1" connectionTimeout="20000" maxThreads="600" minSpareThreads="5" port="8088" protocol="HTTP/1.1" />

      An example below shows that the IP address is removed and ciphers added.<Connector NIDP_Name="connector" port="8443" address="" ciphers="SSL_RSA_WITH_RC4_128_MD5, SSL_RSA_WITH_RC4_128_SHA, ... ../>

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

NOTE:If you are using Kerberos and you have renamed nidpkey.keytab and bcsLogin.conf with any other name, ensure that you modify the upgrade_utility_functions.sh script located in the novell-access-manager-x.x.x.x-xxx/scripts folder with these names before upgrading Access Manager.

NOTE:If you have customized the Java settings in the /opt/novell/nam/idp/conf/tomcat.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.2 Administration Guide .

Upgrading Access Gateway Appliance

Prerequisite: If you are on 3.2.3 or higher, before upgrading to 4.2, you must first upgrade the base operating system of Access Gateway Appliance to the latest operating system that is included in the 4.2 Access Gateway appliance ISO. For more information about how to upgrade, see Section 9.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/webapps/nesp/WEB-INF/web.xml

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

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

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

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

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

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

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

Upgrading Access Gateway Service

Prerequisites for Access Gateway Service

  • Manually back up the /opt/novell/nam/mag/conf/tomcat.conf and the /opt/novell/nam/mag/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_42_AccessGatewayService_Linux_64.tar.gz file from the NetIQ download site and extract it by using the following command:

    tar -xzvf <AM_42_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, 4.0.x or 4.1.x environment the corresponding changes will need to be applied to the 4.2 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.2 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.2 /opt/novell/nam/idp/conf/tomcat.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, 4.0.x or 4.1.x, ensure that you apply the same to the new 4.2 /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/tomcat/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:If you have customized the Java settings in the /opt/novell/nam/idp/conf/tomcat.conf file, then after the upgrade, you must copy the customized setting to the new file.